HAHTsite Application Server Installation Guide

Transcription

1 HAHTsite Application Server Installation Guide

2 Application Server Installation Guide release 4.0

3 Notice Copyright 1999 HAHT Software, Inc. All Rights Reserved July 1999 MN04-C 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 et. seq. or subparagraph (c)(1) and (2) of the Commercial Computer Software 96 Restricted Rights at FAR , as applicable. Contractor is HAHT Software, Inc., 4200 Six Forks Road, Raleigh, NC 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 Summit Software Company. This product includes software developed by the Apache Group for use in the Apache HTTP server project ( 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 Six Forks Road Raleigh, NC USA (919) (888) (in the USA) (919) (Technical Support)

4 Contents About This Book What s in this book vii Other HAHTsite documentation viii Other HAHTsite products viii Conventions viii HAHTsite Application Server installation directory viii Continuation characters in sample code ix HAHT Software s commitment to you ix 1 Planning Your Installation What s in this chapter Configuration considerations Machine roles: control, background, and foreground hosts Control host Backup control host Foreground host Background host Other configuration considerations Heterogeneous configurations Firewall configurations Load distribution Special notes for firewall installations Installing the HAHTsite Application Server (Windows NT) Introduction System requirements What the installation program does Important! Before You Start the Installation Procedure iii

5 Contents Running the setup program What s next? Verifying the installation Removing the Application Server Web server configuration (WinNT) Introduction About site configuration files Using the Web Server Utility (Windows NT) Starting the Web Server Utility What the Web Server Utility detects Adding hsrun to a Web server s CGI scripts directory Installing the HAHTsite Application Server (UNIX) Introduction System requirements What the installation program does Important! Before you start the installation procedure Running the setup program License information What s next? Java debugging setup for Solaris Java debugging setup for HP/UX Java debugging setup for AIX Connecting to an ODBC data source Using the flat-file ODBC drivers Editing.dbenv.conf Viewing the site definition page Configuring your Web server after the installation Verifying the installation Removing the Application Server from your system Web server configuration (UNIX) Using the Web Server Utility iv

6 Contents Starting Web Server Utility WSUtil s main menu [A]dd [M]odify [D]elete [L]ist [C]onfigure [Q]uit Database configuration Introduction Connecting to an ODBC data source (Windows NT) Connecting to an ODBC Data Source (UNIX) Editing environment variables for relational databases (UNIX) Increasing the number of file descriptors for flat-file ODBC drivers (Solaris) A Setting up NSAPI, ISAPI, and the Oracle Cartridge Introduction Setting Up NSAPI Windows NT UNIX Setting Up ISAPI Setting Up ISAPI for IIS Setting Up the Oracle Web Application Server Configuring the Administrator as an NSAPI, ISAPI, or Oracle application. 107 v

7 Contents vi

8 About This Book This book provides instructions for Web site administrators on installing and configuring the HAHTsite Application Server, a platform for deploying industrial-strength Internet and intranet Web applications. What s in this book The following table summarizes the contents of this book: Chapter/Appendix Chapter 1, Planning Your Installation Chapter 2, Installing the HAHTsite Application Server (Windows NT) Chapter 3, Web server configuration (WinNT) Chapter 6, Database configuration Appendix A, Setting up NSAPI, ISAPI, and the Oracle Cartridge Contents Gives a functional overview of configuring the HAHTsite Application Server. It also describes the various roles a machine can play, and how the Application Server interacts with other components in various configurations. Describes how to install the Application Server in a Windows NT environment. Describes how to configure your Web server using the Web Server Utility. Describes how to configure your Application Server to work with database connections. Describes how to configure NSAPI, ISAPI, and the Oracle Cartridge for use with the HAHTsite Application Server. vii

9 About This Book Other HAHTsite documentation Other documentation shipped with the HAHTsite Application Server includes: HAHTsite Application Server Administration Guide Online help for the HAHTsite Application Server Other HAHTsite products In addition to the Application Server and Application Server Administrator utility, the HAHTsite family of products includes: The HAHTsite IDE, a complete environment for building, publishing, and maintaining Web applications. Web developers use the suite of tools that come with the IDE to create their Web site applications. The HAHTsite IP, a subset of the IDE consisting of the features used by page layout artists, graphics designers, and content editors. Conventions The conventions used in this book are described here. HAHTsite Application Server installation directory The directory into which you install the HAHTsite Application Server is called the Application Server installation directory. This book uses the variable HAHTsiteInstallDir as a placeholder for the Application Server installation directory (e.g., c:\hahtsite). When you see this variable, you should replace it with the name of the Application Server installation directory on your system. Here is an example: 1 Copy the files from HAHTsiteInstallDir\bin into the Web server s CGI- BIN directory. If you installed the Application Server in c:\hahtsite, you would copy the files from c:\hahtsite\bin. viii

10 About This Book Continuation characters in sample code Some lines of sample code are too long to fit on one line. In that case, this book uses the HAHTtalk Basic line-continuation character ( _ ) at the end of a line. Example: Function Create (instancehandle As Long, createtime As Integer, _ scopecount As Long) As Integer 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) Technical Support (Voice) (919) Technical Support (FAX) (888) Sales (Voice in the USA) (919) Office (Voice) (919) Office (FAX) [email protected] General Information [email protected] Sales [email protected] Support World Wide Web ix

11 About This Book x

12 Planning Your Installation 1 What s in this chapter...2 Machine roles: control, background, and foreground hosts...2 Control host...3 Foreground host...3 Background host...4 Other configuration considerations...4 Special notes for firewall installations...5 1

13 Chapter 1: Planning Your Installation What s in this chapter Before you install the HAHTsite Application Server, you should understand the various installation configurations and determine the best configuration for your site. This chapter gives a functional overview of configuring the HAHTsite Application Server. It also describes the various roles a machine can play and the way the Application Server interacts with other components in various configurations. Note - This book deals exclusively with the full version of the HAHTsite Application Server. If you plan to run both the Developer Edition and the full Application Server on a single machine, be sure to name your full Application Server installation something other than Default, as this name would create a conflict with the Developer Edition installation. Configuration considerations Before you begin installing the HAHTsite Application Server, you must decide on an installation configuration for your site. The Application Server can be installed on any combination of one or more machines. The HAHTsite Application Server s open-ended, modular design provides for an incredible flexibility of configuration. The Application Server need not reside on the same machine as the Web server, and can be installed on one or more host machines depending on your specific needs. Machine roles: control, background, and foreground hosts There are three roles that a host machine can play in an Application Server configuration: control host, background host, and foreground host. Typically, a host machine plays only one of these roles at a time. However, in some configurations, a single machine can play more than one role at a time. As you prepare to install the Application Server, the first thing you must do is decide which role each computer will play in your configuration. Note that all 2

14 Chapter 1: Planning Your Installation machines in a configuration are referred to as hosts. A host machine may or may not have a Web server installed, depending on the role it is playing in the configuration. Control host In each Application Server installation, you must designate one machine as the control host. The control host runs the HAHTsite Application Server and the HAHTsite Administration Server, and must have a Web server installed. The Application Server should always be installed on the control host first. The control host stores configuration information for all of the foreground and background hosts. The master control process, hscontrol, runs on the control host and is responsible for: processing and verifying requests from foreground hosts and background hosts monitoring and updating the status of all host machines notifying the foreground hosts when background hosts or server groups on background hosts start or stop, or are added or removed broadcasting admin utility messages to all of the hosts The Application Server Administrator utility runs on the control host. Because this utility is a Web-based application, it can be accessed from any Internet connected machine, through a Web browser. Backup control host In addition to the primary control host, you can define additional backup control hosts. Should the primary control host fail, a backup control host takes over control functions for the cluster until the primary control host becomes available. The primary control host then takes over control host functions. Foreground host A foreground host runs the Application Server (including the hsrun process), a Web server, and the HAHTsite Redirector process. The Redirector process distributes requests for new application sessions among the configuration s background hosts. You can have one or more foreground hosts. In configurations where there is more than one foreground host, there must be a Web server router that distributes requests for a single URL (e.g., among Web servers. 3

15 Chapter 1: Planning Your Installation This means that the CGI alias used to find hsrun should be the same on all foreground hosts, and if you have ISAPI or NSAPI configured on one foreground host, you should have it configured on all foreground hosts. Note - Because the HAHTsite applications don t actually execute on a foreground host, a foreground host performs no database access, and therefore does not need to have database client software installed, or have data source names configured. Background host A background host runs the HAHTsite Application Server and delivers dynamic pages. You can have one or more background hosts. A background host receives requests for dynamic pages from the hsrun process running on a foreground host. Note - If your application will be performing database access, each of your background hosts must have the necessary database client software installed, and any necessary data source name(s) configured. Other configuration considerations Application Server configurations vary among sites. In addition to having various combinations of foreground and background hosts, your configuration can involve machines with different operating systems, and/or a firewall machine. Heterogeneous configurations Foreground and background hosts can run different operating systems (NT, Solaris, HP/UX, and AIX) in any combination. Firewall configurations Foreground and background hosts can run outside or inside a firewall, in any combination. In most cases, the control and background hosts reside behind the firewall. When you install the Application Server with a firewall, you will need to specify public and private IP addresses and ports for each host that resides behind the firewall. 4

16 Chapter 1: Planning Your Installation Load distribution The HAHTsite Redirector process, hsredir, runs on each foreground host, and distributes requests for new sessions among the background hosts. Round-robin distribution is used by default. You can optionally specify a relative performance number for each background host. The Redirector then assigns requests to hosts using a weighted distribution, based on performance factors. For example, if background hosts X, Y, and Z are given relative performance factors of 20, 30, and 50, they will receive approximately 20%, 30%, and 50% of the session assignments. Once a session has been assigned to a particular background host and Application Server process, all dynamic pages for that state ID are run on that host and process. Once installation is complete, you can use the Application Server Administrator utility to define relative performance numbers for each background host. Special notes for firewall installations If you plan to install the HAHTsite Application Server with a firewall, you (or a system administrator at your site) must configure some machine ports before starting the installation procedure. The firewall needs to have a range of public ports that will map to a range of private ports on the control and background host(s). 5

17 Chapter 1: Planning Your Installation Private inside.thiscompany.com Public Background1 2 processes Firewall 8005 Background Foreground 3 processes Control hscontrol Each background host must have a range of dedicated ports defined. These ports are used to listen for requests from hsrun on the foreground host(s). The number of ports in the range must equal the number of Application Server processes, plus one. The extra port is set aside for the administrative process hsrexec. The hsrexec process receives requests for new sessions, and must have its own port. For example, if a background machine is running 10 Application Server processes, and you enter a value of 9000, the server group will listen on ports You would enter the base port value (9000) in the Base of private IP port range field during setup. The port range on the firewall defines the corresponding range of firewall ports that the firewall maps to the private ports. For example, if you enter 8000, you should configure the firewall to map ports on the firewall to on the background host. The firewall must be configured to allow to access the TCP/IP ports on the inside.thiscompany.com by tunneling through the firewall. To do this, you must map a port on the firewall to a port on the control host. For example, you could map firewall.thiscompany.com:7000 to inside.thiscompany.com:

18 Chapter 1: Planning Your Installation IDE or IP machines should reside behind the firewall as well. The transfer URL to the Web server (on the foreground host) must be a URL that can be accessed from inside the firewall. This usually means that publishing will be via FTP or HTTP. 7

19 Chapter 1: Planning Your Installation 8

20 Installing the HAHTsite Application Server (Windows NT) 2 Introduction...10 System requirements...10 What the installation program does...10 Important! Before You Start the Installation Procedure...11 Running the setup program...15 To install the HAHTsite Application Server components...15 Completing the installation...27 Requesting a new license key (control host only)...32 What s next?...33 What other setup tasks do I need to perform?...33 To verify installation on foreground and background hosts...35 Verifying the installation...35 Removing the Application Server

21 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Introduction This chapter describes how to install and configure the HAHTsite Application Server on one or more Windows NT machines. The directions include special instructions for installing the Application Server on a control host (both primary and backup), foreground host, and background host. System requirements If you install the Application Server as a background host, the computer requires at least: Windows NT MB RAM 15 MB free disk space The disk requirements are less on the control and foreground machines. The amount of memory used by the Application Server depends on the complexity and number of HAHTsite applications running simultaneously. You should install the Application Server software using the above system requirements as a starting point. Later, you can fine-tune your system using the guidelines in Chapter 5, Tuning Tips, in the HAHTsite Application Server Administration Guide. What the installation program does The installation program does all of the following: 10

22 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Creates an installation directory tree (if it doesn t already exist) with the following subdirectories: approot (only on control and background hosts) audit bin cgibin (only on control and foreground hosts) conf. On the control host, the directory will contain these four subdirectories: ServerGroups, HostComputers, GroupHosts, and ControlHosts. doctree (only on control and foreground hosts) javaroot (only on background hosts) lib logs program samples sites (only on control and foreground hosts) userroot (only on background and control hosts) Creates a HAHTsite program group containing icons for starting an uninstall utility, a Web configuration utility (only on control and foreground hosts) and the HAHTsite Application Server Administrator utility (only on control hosts). Creates configuration files used by the Administrator utility. Places the executable file (hsrun and dependent files) for the Application Server in a location where the Web server can find it (only on control and foreground hosts). Installs ODBC (only on background hosts). Creates an NT service ( HAHTsite 4.0 Controller, HAHTsite 4.0 Foreground, or HAHTsite 4.0 Background ) to run the HAHTsite Application Server Administrator, the default server group, and any additional server groups that you create. Important! Before You Start the Installation Procedure Things to consider before you start the installation procedure: 11

23 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Item Control host first CORBA Determine machine roles DNS names Firewall Description Do not install the Application Server software on a foreground or background host until you ve installed the Application Server on the primary control host. The primary control host should be up and running before you install any foreground or background hosts, unless you plan to install the control and foreground or background hosts at the same time. To use CORBA with HAHTsite, you need to install the Visibroker for Java components on at least one background host. For high availability configurations, we recommend you install the Visibroker for Java components on multiple background hosts. In firewall configurations, you will also need to install the Visibroker for Java components on a foreground host, and use the Visibroker Gatekeeper to route CORBA requests through the firewall. Decide which hosts will perform the control (primary or backup), foreground, and background roles. A host can perform more than one role. For example, you can check both Foreground and Background; or a control host may also serve as either a foreground or background host. The setup program loads different software components on the hosts, depending on what role(s) they perform. For an overview of Application Server configurations, including a description of the host computer roles, see Chapter 1, Planning Your Installation. Note - A server group can have only one primary control host. Determine the DNS names of all host computers that will participate in the Application Server. The setup program displays this information for your verification. Know whether any Application Server hosts are behind a firewall. If so, know their private IP addresses. 12

24 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Item Java Virtual Machine installation NSAPI/ISAPI Previous Application Server installation Remote access Description HAHTsite supports the following Java Vitual Machines: Microsoft Sun Sun 1.2 ( Java 2 ) All hosts in your installation must use the same Java virtual machine. Note - If you plan to use the Java 2 VM, see Special note on using the Sun Java 2 virtual machine on page 14. If the NSAPI or ISAPI versions of hsrun are installed, you must also stop the Web server. If you intend to overwrite a previous Application Server installation, be sure to stop it prior to running setup. If you will have HAHTsite IDE and/or IP users (on client systems) publishing applications to the Application Server on a machine, you will need to grant remote access to those client systems for the following directories: The installation directory of the Application Server (on background hosts). Your Web server s document root or doctree directory (on control and foreground hosts). The installation will only recognize file sharing and FTP remote access methods. In the event that remote access to these directories is not setup before installation or you are using HTTP remote access, you can use the Application Server Administrator utility and the Web Server utility to change the local paths to remote paths following the completion of the installation. For information on using the Web Server Utility, see Chapter 3, Web server configuration (WinNT). A default site definition will be created by the installation process. You may need to customize and verify the site to ensure that all IDE and/or IP clients can publish successfully following the completion of the installation. 13

25 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Item Server group services Web server Description If you have any HAHTsite server groups running as NT services, stop them using the Services dialog on the Control Panel. Install your Web server (on the control and foreground machines). The setup program does not require the Web server software, but having the software installed and configured properly enables the setup program to automatically establish the interface between the Application Server and the Web server. Note - Consider installing the Apache Web server bundled with the HAHTsite IDE and IP setup program. Special note on using the Sun Java 2 virtual machine If you want to use the Sun Java 2 (1.2) virtual machine for your HAHTsite applications, you will need to perform the following procedure(s) after running setup. To configure your Application Server to use the Sun Java 2 VM 1 Edit your system PATH to include the following: d:\jdk1.2\bin;d:\jdk1.2\jre\bin\classic Where: d:\jdk1.2 is where you installed the JDK 1.2 compiler, d:\jdk1.2\jre is where you installed the Java VM for In the HAHTsite Application Server Administrator, click on Language. The Language Options form appears. 3 Under Java Options, select the radio button for Sun Click Save Changes. 5 Still in the HAHTsite Application Server Administrator, click on Directories. The Directories and Publishing Options form appears. 6 Edit the System Java Class Path as follows: Replace %INSTALLDIR%\lib\rt.jar with the following: d:\jdk1.2\jre\lib\rt.jar; Where: d:\jdk1.2\jre is where you installed the Java VM for 1.2. Note - You must also add d:\jdk1.2\lib\tools.jar; to the System Java Class Path to enable debugging for Java projects. 14

26 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 7 Click Save Changes. You can exit the HAHTsite Application Server Administrator at this time. Running the setup program Note - Installation is not complete until you ve run setup on each machine in the configuration. You should first run setup on the control host, then on each foreground and background host. To install the HAHTsite Application Server components 1 Log in to the Windows NT server using an account that has administrative privileges. If the HAHTsite Application Server is currently installed and running on the server, stop it and any server groups. 2 Insert the HAHTsite Application Server CD-ROM into the appropriate drive and start the setup program by selecting Run... from the Windows NT Start menu. Type drive:\winnt\i386\setup.exe, where drive is the drive containing the CD-ROM. Alternately, go to the Control Panel s Add/Remove Programs dialog. On the Install/Uninstall tab, click Install and follow the prompts until the setup program starts. A dialog informs you that the setup program is being prepared. If the setup program does not find a HAHTsite license in the system registry, the Software License Agreement dialog appears. 15

27 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 3 If the Software License Agreement is displayed on your screen, click Yes to accept the terms of the license. If you click No, the setup program will be terminated. After you click Yes, the Welcome dialog appears 4 Click Next to proceed with the installation. The Enter Serial Number dialog appears. 16

28 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 5 Enter the Serial number found on the back of the HAHTsite Application Server s CD jewel case, and click Next. Note - If you do not have a Java virtual machine (Java VM) installed on this machine, or the Microsoft Java VM detected is not the most recent version, setup asks you if you want to install the Microsoft Java VM at this time. HAHTsite 4.0 does not require the Microsoft Java VM, but it is recommended because of its significant performance benefits. Click Yes, and follow the resulting installation instructions. 6 The Select Components dialog appears. 17

29 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 7 Select this host computer s role(s) by selecting one or more check boxes. Your selection will determine which Application Server components the setup program installs on this machine. Click Next. Note - The installation is not complete until you ve installed the Application Server software components on all machines in the configuration. If this machine will be either a primary or backup control host, jump to Step 9 on page 19 to continue the installation procedure. If this machine will be a foreground or background host, the Setup Options screen appears. 18

30 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 8 Select one of the two setup options by clicking the option s button. The options are: Option Typical Custom Description Select Typical to install all Application Server software. Select Custom to perform a selective installation, or if you plan to use CORBA with your HAHTsite applications. 9 If there is a previous HAHTsite 3.1 or 4.0 Application Server installation on this machine, setup asks you whether you want to overwrite a previous installation. If you click No, jump to Step 11 on page 20. If you click Yes, setup provides a list of previous installations. 19

31 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 10 Select the radio button for the installation you want to overwrite, and click Next. Jump to Step 13 on page Select an installation name. Type a unique name for this Application Server installation in the Name field, and click Next. The Select Directory For Application Server 4.0 dialog appears. 20

32 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Verify the installation directory, or click browse to select an alternate. Click Next to proceed with the installation. If you have not set FTP or file sharing access for the selected directory, a warning appears to remind you that you will need to do so after the installation is complete. Click Ok to dismiss the warning. If you selected Typical in Step 8, jump to Step 13 on page 23. If you selected Custom in Step 8, the Select Options to Install screen appears. 12 Select components to install. 21

33 Chapter 2: Installing the HAHTsite Application Server (Windows NT) The Components box lists Application Server components. The checkbox beside each component is checked if the component is selected: click the box to select or exclude a component. Click the component name to see a description of the component in the Description box. Below the Description box, the space requirements for the component, and space available, are displayed. If you select ODBC Drivers, and then click the Change button, the Select Sub-components Dialog appears. Select the ODBC drivers you want to install, then click Continue. Click Next. 22

34 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 13 The firewall configuration screen appears. Specify your firewall configuration. Select the radio button that describes your Application Server configuration, and Click Next. Select the first radio button if your site does not use a firewall. Jump to Step 15 on page 24. Select the second radio button if this machine will reside inside the firewall and one or more machines in this distributed configuration will reside outside the firewall. Select the third radio button if this machine will reside outside the firewall, and one or more machines in this distributed configuration will reside inside the firewall. Jump to Step 15 on page 24. If you selected This machine is inside a masquerading firewall AND..., the Firewall Address screen appears. 23

35 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 14 Specify the firewall s public address. Enter the public DNS name for your firewall machine in the Public Firewall Address field. Click Next. The Administrative host information screen appears. 15 Specify the machine s name and DNS address. If you are installing a control host, specify the control port. Click Next. If you are installing a foreground or background host, jump to Step 17 on page 25. If you are installing a control host, the Master Administrator Username screen appears. 24

36 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 16 Specify the master administrator. Enter the master administrator s username in the Username field. Note - At this point, configuration for the control host is complete. Go to Completing the installation on page The Control Host information screen appears. Enter the control host s DNS address (this can be the machine s DNS name or IP address) and port number. Click Next. 25

37 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Note - If this foreground host resides outside a firewall, and the control host resides inside a firewall, you must provide the firewall name and port number that are mapped to the control host. When you click Next in the Control Host Information dialog, the Master User ID dialog appears. 18 Specify the master user ID, password, and domain for the control host. (If the control host is a UNIX server, the Domain field can be left blank.) Click Next. Note - At this point, configuration for the foreground host is complete. Go to Completing the installation on page 27. The List of Server Groups screen appears (for background host installations only). 26

38 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 19 Select the server group to which you want this background machine to belong. You can select only one server group. You can use the Administrator utility to include other server groups on this background host. At this point, configuration for the background host is complete. Complete the installation using the procedure that follows. Completing the installation 1 Select a program folder. 27

39 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Select the name of the program folder in which the Application Server program icons will be installed. You may select the default folder, choose an existing folder from the list, or type in a new folder name. If you are installing on a background host, jump to Step 4 on page 31. Static Web server detection begins (on control and foreground installations only). If no static Web servers are detected, the Web Server Information dialog appears (see Manual... in the table on page 29). The Web Server Detection Static Alias screen appears. 2 Use the fields on the Web Server Detection Static Alias screen to specify static Web server settings. The fields are described below: Field Web Server Web Server Virtual Host Description Select a Web server from the list of available Web servers. Select a virtual host computer from the list of hosts known to setup. 28

40 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Field Web Server Static Alias Manual... Description Shows the static alias location assigned to the Web server selected above. If your Web server was not detected, click Manual... to enter the Web server information manually. The Web Server Static Information dialog appears. If you do not supply this information, you may encounter problems during installation since setup attempts to make uninformed decisions about your web server configuration. Click Next. Dynamic Web server detection begins (on control and foreground installations only). If no dynamic Web servers are detected, the Web Server Information dialog appears (see Manual... in the table on page 31). The Web Server Detection Dynamic Alias screen appears. 29

41 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 3 Use the fields on the Web Server Detection Dynamic Alias screen to specify dynamic Web server settings. The fields are described below: Field Web Server Web Server Virtual Host Web Server Dynamic Alias Description Select a Web server from the list of available Web servers. Select a virtual host computer from the list of hosts known to setup. Shows the dynamic alias location assigned to the Web server selected above. 30

42 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Field Manual... Description If your dynamic Web server was not detected, click Manual... to enter the Web server information manually. The Web Server Dynamic Information dialog appears. If you do not supply this information, you may encounter problems during installation since setup attempts to make uninformed decisions about your web server configuration. Click Next. 4 File installation begins. As the software loads, the setup program displays progress bars. If your ODBC driver manager is currently in use, you will see the following warning dialog. If you see this warning, and you plan to use the sample application that comes with HAHTsite, you must manually create the data source for this database. For more information about creating an ODBC data source, see 31

43 Chapter 2: Installing the HAHTsite Application Server (Windows NT) Adding an ODBC data source on page 612 of the HAHTsite IDE and IP User s Guide. Note that the data source must be called HAHT_Intro40. 5 View License Reminder (on control host installation only). If you are installing on a control host, the User License Count dialog appears. This dialog is intended to remind you that the Application Server will use a default license key that allows only five concurrent active user sessions. In order to increase the licensed number of active sessions, you must request a permanent license key from HAHT Software. 6 Complete the installation. At this point, you are given the choice of reading the release notice. If you say no (or after you read and close the release notice), the Setup Complete dialog may appear if any DLLs could not be immediately updated because they were is use. Indicate whether or not you want to reboot your computer now so the DLLs can be updated, then click Finish. Requesting a new license key (control host only) To request a new license key immediately after installation, go to the HAHTsite Program Group (in the Windows Start menu) and select How to Request a License Key. The following page is displayed in a Web browser. 32

44 Chapter 2: Installing the HAHTsite Application Server (Windows NT) You can click the link to send an request for a new license key to HAHT Software. To ensure security, the license key will be returned to you via . Optionally, you can click the HAHTsite Application Server Administration link to start the Application Server Administration utility. For more information about using the Administration utility, requesting a license key, and upgrading your user license count, see Managing License Information in the HAHTsite Application Server Administration Guide. What s next? This section identifies any setup tasks that you still need to perform and directs you to a procedure for each task. What other setup tasks do I need to perform? The following table identifies the setup tasks that you must perform after the initial installation: If... Then You Need to... Go to This Section Your Web server was not installed at the time of the installation. Or: Since installation, you ve installed an additional Web server that you would like to use with HAHTsite. After installing your Web server, start the Web Server utility from the HAHTsite program group. (In a distributed configuration, this applies only to the control host and the foreground host.) Running the Web Server Utility in the HAHTsite Application Server Administration Guide. 33

45 Chapter 2: Installing the HAHTsite Application Server (Windows NT) If... Then You Need to... Go to This Section Any of your HAHTsite applications use databases (unless you plan to use only flat-file ODBC drivers). You allow HAHTsite IDE and/or IP users on client systems to publish applications to the Application Server. Set up connectivity to an ODBC data source. The setup program installs ODBC, but you will not be able to use a database with your HAHTsite applications until you connect to an ODBC data source. This task needs to be performed on both the client and the server side. Make sure the following directories are accessible via either file sharing, FTP, or HTTP transfers. The installation directory of the Application Server. The Web server document root or doctree directory A default site definition is created by the installation process. You may need to customize and verify the site to ensure that all IDE and/or IP clients can publish successfully. Database Configuration in the HAHTsite Application Server Administration Guide. Chapter 3, Web Server and Database Configuration in the HAHTsite Application Server Administration Guide. 34

46 Chapter 2: Installing the HAHTsite Application Server (Windows NT) If... Then You Need to... Go to This Section You installed a background host in a distributed configuration. You plan to use a Sun Java VM to debug Java projects. Configure one or more Distributed Server Groups to run on the background host. The Distributed Server Group(s) must be explicitly included on each background host. Also, the paths or URLs to use to publish dynamic components to the Server Group must be defined for each background host. Install the Sun JDK on your background host. Chapter 2, Maintaining Server Groups in the HAHTsite Application Server Administration Guide. Note - Be sure to set FTP or file sharing access for the installation directory if it was not done prior to installation. Verifying the installation When you install the Application Server in a distributed configuration, starting the Administrator utility verifies a successful installation on the control host. To verify installation on foreground and background hosts 1 Start the Administrator on the control host, as explained in Getting Started with the Administrator in Chapter 2 of HAHTsite Application Server Administration Guide. 2 Select the Host Computers button and verify that the green status indicator is lit for all foreground and background hosts. This verifies that the foreground and background hosts are successfully communicating with the control host. Removing the Application Server Use this procedure to remove the Application Server from your system. 35

47 Chapter 2: Installing the HAHTsite Application Server (Windows NT) 1 Use the HAHTsite Application Server Administrator s Applications option to ensure that no server groups are in use. 2 Use the Application Server Administrator utility to stop all HAHTsite server groups. 3 Use the Control Panel s Services utility to stop any active NT services for HAHTsite. 4 Select Start-> Programs-> HAHTSite Server-> Uninstall the HAHTsite Application Server. A confirmation dialog asks you to verify that you want to remove the program and all of its components. 5 Click Yes to uninstall the Application Server. You can also remove the Application Server with the Add/Remove Programs procedure on the Control panel. 36

48 Web server configuration (WinNT) 3 Introduction...38 About site configuration files...38 Using the Web Server Utility (Windows NT)...39 Starting the Web Server Utility...39 What the Web Server Utility detects...41 Static page aliases...41 CGI aliases...42 To set up an interface to a detected Web server...42 To set up an interface to an undetected Web server...44 Adding hsrun to a Web server s CGI scripts directory...46 To copy hsrun to a Web server s CGI scripts directory...46 To modify a configuration...47 To remove a configuration

49 Chapter 3: Web server configuration (WinNT) Introduction This chapter describes procedures that may be required to configure the HAHTsite Application Server with Web servers. About site configuration files When you install a foreground or control HAHTsite Application Server component on a machine, the HAHTsite installation program creates site configuration files that describe the interface between the Application Server and a Web server. The Application Server side of this interface includes information about where the HAHTsite IDE/IP should publish static pages (to the Web server s static page directory) and an alias to the Web server s CGI directory (which contains the Application Server s hsrun program files). When the installation program runs, it (among other operations): Locates the Web server s static page directory (the place where the Web server looks for static pages) and copies the pages needed by the HAHTsite Application Server Administrator utility to that directory. Locates the Web server s CGI directory (the place where the Web server looks for executable programs) and copies the hsrun program files to that directory. Configures the URL Path to the Web server s CGI directory. Sets up methods for transferring files from the IDE to the Web server and the Application Server. This information is stored in the site configuration files listed in the following table: File Type CGI Alias (.hca) Docroot (.hdr) Description Contains information on how to build a URL pointing to hsrun. (This is the program that the Web server executes to route requests for dynamic pages to a HAHTsite Application Server.) Describes how to publish static pages to a Web server, and the URL needed to browse the pages. 38

50 Chapter 3: Web server configuration (WinNT) File Type Server group (.hsg) Site definition (.hst) Description Created and updated by the Application Server Administrator utility. Created and updated by IDE/IP site management dialogs. These files store references to the.hsg,.hca, and.hdr files. Using the Web Server Utility (Windows NT) By default, the site configuration files listed in the table above are located in a host machine s HAHTsiteInstallDir\sites directory. Note - Although the site configuration files are stored in Windows INI-style format, it is strongly recommended that you not edit the files by hand. As shown in the table,.hsg files are managed by the Application Server Administrator utility, and.hst files are managed by IDE/IP site management dialogs. You should edit.hca and.hdr files with the HAHTsite Web Server Utility (Web Server Utility). Here are some situations where you would want to use Web Server Utility: You installed a new Web server after installing a HAHTsite Application Server. You made changes to the configuration of the Web server you use with the Application Server. You want to customize the interface between a Web server and the Application Server, or remove an interface to a Web server that you no longer use. Starting the Web Server Utility You can start the Web Server Utility from the HAHTsite program group or from the HAHTsite installation directory (HAHTsiteInstallDir\program\wsutil.exe). The contents of the Web Server Utility main dialog will vary, depending on which and how many Web servers are installed, and on whether they have 39

51 Chapter 3: Web server configuration (WinNT) been previously added. The following figure shows the main dialog on an Application Server host with interfaces to a WebSTAR server and a Microsoft Internet Information Server. The following table summarizes the functions of the utility s five main buttons: Button Add Auto- Detected... Add Web Server... Add HSrun... Modify... Delete... Function Display how detected Web servers are configured, along with the corresponding Application Server settings needed to accommodate that configuration. Optionally, save the displayed Application Server settings to.hca and.hdr configuration files. Set up an interface to Web server components that Web Server Utility does not detect, or add new components to an existing Web server. Place the HAHTsite hsrun programs into a Web server s CGI directory. Modify one or more Application Server settings of an existing interface. Remove.hca and.hdr configuration files. 40

52 Chapter 3: Web server configuration (WinNT) If you re building an interface to a newly installed or modified Web server, click Add Auto-Detected. This causes Web Server Utility to search the Registry for installed Web servers and display the results of the search in the Add Detected Web Server dialog. If the Web server you want to use is listed, proceed to the next section. If your Web server does not appear, exit from the Add Detected Web Server dialog (click Cancel) and proceed to To set up an interface to an undetected Web server on page 44. What the Web Server Utility detects When Web Server Utility detects a Web server, it displays two types of entries in the Add Detected Web Server dialog: the Web server s static page aliases and its CGI aliases. Static page aliases A Web server s static page alias maps a URL to a file-system directory. When given a URL to a static page, the Web server uses the information in its static page alias to locate the file specified in the URL. When you select a static page alias in Web Server Utility s Add Detected Web Server dialog and click Add, Web Server Utility creates a new.hdr site configuration file. The.hdr file contains information that the HAHTsite IDE/IP needs to publish static pages to the directory specified in the Web server s static page alias. 41

53 Chapter 3: Web server configuration (WinNT) CGI aliases A Web server s CGI alias maps a URL to a program file. When given a URL to a CGI program, the Web server uses the information in its CGI alias to locate the program specified in the URL. When you select a CGI alias in Web Server Utility s Add Detected Web Server dialog and click Add, Web Server Utility creates a new.hca site configuration file. The.hca file contains the information the HAHTsite IDE/IP needs to build a URL to the HAHTsite Application Server s hsrun program. If you have Perl scripts or other program files that you want to publish to a Web server s CGI directory, check the Add as Static box. Web Server Utility will create a new.hdr file, which will enable you to publish, from the HAHTsite IDE/IP, your program files to the Web server s CGI directory. To set up an interface to a detected Web server Here are the recommended steps for setting up a configuration for a detected Web server and a HAHTsite Application Server. 1 Click and expand the Web server you want to use. A typical Web server directory tree includes: A single directory whose name is the same as that of the host. Under this directory, a list of the Web server s static page and CGI aliases. 2 Examine the properties of the Web server components. 42

54 Chapter 3: Web server configuration (WinNT) To examine a component that you may want to add, click to select the item and then click Properties... For example, if you click /cgi-bin in the preceding figure and click Properties..., a dialog like the one shown below appears. (The fields in this dialog are read-only.) The dialog in Figure 3-4 indicates that, on the host barney, the Netscape FastTrack administrator has created an alias named cgi-bin pointing to the HAHTsite directory d:\hahtsite\cgibin. The URL field shows the URL that points to this HAHTsite directory. The following is an example of the dialog s Port tab: The Port tab indicates that the Netscape FastTrack server on Barney uses port 80 and searches directory d:\hahtsite\doctree for static files. The Web Server tab (not illustrated) displays the name and revision of the Web server. 3 After inspecting the information, click OK to return to the Add Detected Web Server dialog. 4 Click Add to add the Web server component to the HAHTsite site configuration. 43

55 Chapter 3: Web server configuration (WinNT) If Web Server Utility identifies the component as a CGI directory, the checkbox Add as Static asks whether static pages should be published to this destination. Where not relevant, the checkbox is dimmed out. In most cases, you should accept the default (no). If you have Perl scripts or other program files that you want to publish to a Web server s CGI directory, check the Add as Static box. Web Server Utility will create a new.hdr file, which enables you to publish program files from your HAHTsite project to the Web server s CGI directory. Repeat these steps for all expanded items that you want to add. (The Add button is dimmed out if Add is not a relevant action.) Clicking Add saves the Application Server configuration information you have inspected into the appropriate.hca and.hdr configuration files. During inspection, if you see a configuration problem (for example, an incorrect URL to the Web server s CGI directory), you can use Modify (see To modify a configuration on page 47) to change the Application Server s configuration as needed to accommodate the Web server s configuration. Alternatively, you can change the Web server s configuration, using the Web server s administration tool the run the Web Server Utility again. To set up an interface to an undetected Web server Here are the recommended steps for setting up an interface to an undetected web server: 1 If Web Server Utility does not detect your Web server, click Add Web Server to display the Static Web Server Information dialog. 44

56 Chapter 3: Web server configuration (WinNT) In this dialog, you can browse for and select Web server directories, construct URLs and aliases, and define methods for transferring information between the Web server and Application Server. 2 In the Name field, enter a name to identify this particular Web server interface. This name will appear in the Web Server Utility s main dialog. 3 From the Web Server Type list box, select the Web server s type. 4 The Browse URL field contains a URL that points to the Web server s static (doctree) directory; change it as needed. 5 Click Add... to display the Transfer Location dialog. 45

57 Chapter 3: Web server configuration (WinNT) 6 In the Protocol list box, select the method that will be used to transfer files between the Web server and the Application Server: File Copy, FTP, or HTTP. Note - The Web Server Utility specifies, but does not set up, the transfer method. Thus, File Copy may require a shared directory, while FTP requires you to set up an FTP site. Web Server Utility does not set up these methods. 7 In the Path field, enter the Web server s doctree directory. This is the place where the Web server looks for HTML files. If you do not know the name of the directory, click the Browse box on the right of the field. 8 In the OS Type drop-down box, select the Web server host s operating system: Windows NT, Windows 95, or UNIX. 9 If you selected the FTP transfer protocol, you can optionally add a Username and Password that will be used to logon to the FTP server when a project is published from the IDE/IP. You can also specify the number of retries if a file transfer fails. If you do not specify a username and password, the IDE/IP user will be prompted to enter these values at publish time. 10 Click OK to return to Web Server Utility s main dialog. Note - In most cases, you will add only one transfer location for a static page alias. However, you can add multiple transfer locations if, for example, you have a mirrored Web site or are using a router that can fetch pages from multiple locations. Adding hsrun to a Web server s CGI scripts directory The HAHTsite hsrun program routes requests for dynamic pages to the Application Server. The URLs for HAHTsite applications include the location into which a Web server looks for the hsrun program. This location is typically a Web server s CGI bin or scripts directory. Optionally, you can create, with the Web server s administration utility, an alias to the HAHTsite installation directory s CGI bin directory (which is, by default at HAHTsiteInstallDir\cgibin.) To copy hsrun to a Web server s CGI scripts directory 1 In the Web Server Utility, click Add hsrun... The hsrun Information dialog appears. 46

58 Chapter 3: Web server configuration (WinNT) 2 Enter a name for the Web server in the Name field, and select its type from the Web Server Type drop-down box. 3 The Browse URL field contains the URL that points to the Web server s CGI scripts directory: change this URL as required. 4 In the cgi-bin Directory field, enter the pathname of the Web server s CGI scripts directory, or, Click the browse button on the right side of the field if you do not know the path. 5 Click OK to copy all the hsrun program files from HAHTsiteInstallDir\cgibin to the selected location. To modify a configuration You change configuration values from Web Server Utility s main dialog. To do that: 1 Select the line for the value you want to change, and click Modify. 2 Change the values as desired and click OK. 47

59 Chapter 3: Web server configuration (WinNT) To remove a configuration You delete configuration values from the Web Server Utility main dialog. 1 Select the line for the value you want to remove and click Delete. 2 When prompted, click Yes to confirm that you want to delete the item. 48

60 Installing the HAHTsite Application Server (UNIX) 4 Introduction...50 System requirements...50 What the installation program does...51 Important! Before you start the installation procedure...52 Running the setup program...53 License information...67 What s next?...68 Java debugging setup for Solaris...71 Java debugging setup for HP/UX...71 Java debugging setup for AIX...71 Connecting to an ODBC data source...72 Using the flat-file ODBC drivers...73 Editing.dbenv.conf...73 Viewing the site definition page...74 Configuring your Web server after the installation...75 Verifying the installation...76 Removing the Application Server from your system

61 Chapter 4: Installing the HAHTsite Application Server (UNIX) Introduction This chapter describes how to install and configure the HAHTsite Application Server on a UNIX server. The HAHTsite Application Server software is available for Solaris or later, HP/UX or later, and AIX or later. System requirements The HAHTsite Application Server requires at least: A workstation or server with Solaris or later, HP/UX or later, and AIX or later. 64 MB physical RAM. Swap space or virtual RAM should be a multiple (by at least four) of physical RAM. 45 MB of free disk space. Any Web server that supports CGI 1.1 or greater. JDK or greater (with native threads) is required on AIX and HP/UX to enable server-side Java in HAHTsite applications and must be installed separately. As of the writing of this document, JDKs for these platforms could be downloaded from or respectively. (The Java Runtime Environment is distributed with the Application Server for Solaris.) If you install ODBC 3.0, you will need an additional 26 MB of free disk space (typically in /opt/odbc). The amount of memory used by the Application Server depends on the complexity and number of HAHTsite applications running simultaneously. You should install HAHTsite using the above system requirements as a starting point. Later, you can fine-tune your system using the guidelines in the HAHTsite Application Server Administration Guide. 50

62 Chapter 4: Installing the HAHTsite Application Server (UNIX) What the installation program does The installation program does all of the following if you install the Application Server onto a single host. If you install the Application Server in a distributed configuration, the program does what is appropriate for each host type, as indicated. Creates an installation directory tree if it doesn t already exist: approot (on background and control hosts only) bin (on background, foreground, and control hosts) cgibin (on control and foreground hosts only) conf (on background, foreground, and control hosts). On the control host, the directory will contain these four subdirectories: ServerGroups, HostComputers, GroupHosts, and ControlHosts. If HAHTsite authentication is used, file hspasswd is also added. logs (on background, foreground, and control hosts) sites (on foreground and control hosts only) userroot (on background and control hosts only) Creates configuration files used by the Administrator utility (on background, foreground, and control hosts). Places the executable file (hsrun and dependent files) for the Application Server in a location where the Web server can find it (on control and foreground hosts). Sets the user and group file ownership for the Application Server (on background, foreground, and control hosts). If you install the software as root, sets the User ID and Group ID that are used to start the Application Server automatically at system start-up (on control host only). If you install as an account other than root, you must start the Application Server manually. Configures your database environment. Installs ODBC if you do not already have ODBC installed (on background hosts only). Copies the odbc.ini RC file from the ODBC directory to the users s login directory. Sets the user and group ownership of the ODBC files. Configures your Web server to use NSAPI (if the Web server supports NSAPI) and to use standard CGI (on control and foreground hosts only). 51

63 Chapter 4: Installing the HAHTsite Application Server (UNIX) Installs and configures the HAHTsite Application Server Administrator utility (on the control only). Logs the information displayed during the installation to a file named install.log in the installation directories of the Application Server and ODBC (on background, foreground, and control hosts). Important! Before you start the installation procedure Before you start the installation procedure, you should: Install your Web server (on the control and foreground hosts, if you re installing into a distributed configuration). The setup program requires the Web server software to be installed in order to establish the interface between the Application Server and any Web servers. You have the option of reconfiguring the Web server later, by running the Web Server utility (wsutil) from the shell. The Web configuration utility will discover or build, for any installed Web server: The path to its CGI scripts directory and any alias for the directory The URL path to the Web server The path of the Web server s doctree directory If the Application Server has been installed previously in the same installation directory, stop it. If the NSAPI version of hsrun is installed, you must also stop the Web server. If you are going to build HAHTsite applications that use a vendor-specific relational database, you need to know the correct system-specific settings for the environment variables listed below. The setup program configures the environment variables for you if you supply the values during the installation. Otherwise, you can configure the environment variables after the installation (see Editing.dbenv.conf on page 73). Oracle ORACLE_HOME (the base directory used by Oracle to locate its binary files and the correct instance of Oracle). SQL Server/System 10.x or 11.x SYBASE (the home directory where SQL Server/System 10.x or 11.x is installed). Informix INFORMIXDIR (the home directory where Informix is installed) and INFORMIXSERVER (the server name where Informix is installed. This parameter is required for Informix). Ingres II_SYSTEM (the base directory for Ingres). 52

64 Chapter 4: Installing the HAHTsite Application Server (UNIX) Before starting to install the Application Server in a distributed configuration, you should: Know the TCP/IP names and addresses of all host computers that will participate in the distributed Application Server configuration. The setup program displays this information for your verification. Know whether any Application Server hosts are behind a firewall. If so, know their private IP addresses. Decide which hosts will perform the control, foreground, and background roles. (For an overview of distributed configurations, including a description of these host computer roles, see Chapter 1, Planning Your Installation. ) The setup program loads different software components on hosts depending on what role(s) they perform. Running the setup program If you are installing into a distributed configuration, note: Installation is not complete until you ve run setup on each host in the configuration. Follow this sequence: Run setup on the control host. Make sure that the control host is up and running, then run setup on each foreground and background host. This section describes how to run the setup program. The setup procedure is broken down into the following parts: 1 Starting the installation script 2 Following the installation script Note - The procedures do not show all of the informational text that appears on the screen during the installation. Information displayed during the installation can be found in the log files named install.log in the installation directories of the Application Server and ODBC. Starting the installation script 1 Log in with the login account that you want to use for the installation. 2 Insert the CD-ROM into the appropriate drive. At the UNIX prompt type: cd /cdrom 53

65 Chapter 4: Installing the HAHTsite Application Server (UNIX) The subdirectory structure on the CD is as follows: solaris/sparc hpux/version_number aix/version_number (where version_number is the version of the operating system under which the release was built for example, aix/4.x). 3 Change directory to the appropriate subdirectory (above) and start the script by typing: setup.csh Following the installation script 1 The setup script displays the license agreement, with the following prompt: Do you accept all the terms of the license agreement[return=no]? Type yes to accept the agreement, or press Return to accept the default, no, and cancel the installation. 2 Setup displays a warning about unauthorized reproduction of this software, and prompts you to see if you want to continue the installation. Would you like to continue the installation of HAHTsite Application Server [RETURN=YES]: Press Return to accept the default, yes, or type no and press Return to cancel the installation. ######### Select installation location for HAHTsite ######### 3 Next, setup asks for the parent directory for the installation. The installation program will create a directory called HAHTsite under the specified directory. Enter parent directory to install HAHTsite. [RETURN=/default]: Press Return to accept the default, or type an alternate directory and press Return. If the specified directory does not exist, setup will create it for you. The parent directory /specified/ does not Info: HAHTsite parent directory 4 Setup now checks for any previous Application Server installations on this machine. If none are found, jump to Step 8. Otherwise, continue to the next step. 5 If setup finds a previous Application Server installation on this machine, you will see the following: 54

66 Chapter 4: Installing the HAHTsite Application Server (UNIX) #### A Previous Application Server Already Installed #### A previous Application Server installation has been found installed at /InstallDir/HAHTsite. Do you want to overwrite the previous installation[return=no]: Press Return to accept the default, No, or type y to overwrite the previous installation. If you choose to overwrite the previous installation, jump to Step 8. If you choose No, continue to the next step. 6 Enter the name that you would like to associate with this Application Server installation. #### Application Server Installation Name #### Please enter Installation and Initial Server Group Name. [RETURN=webapps]: Press Return to accept the default, webapps, or type a server group name and press Return. 7 Select a parent directory for the application server. The Application Server base directory /HAHTsite will be created within the parent directory you choose. #### Select Directory For Application Server #### Parent destination directory? [RETURN=/InstallDir/InstallName]: Press Return to accept the default, or type an alternate directory and press Return. If the specified directory does not exist, setup will create it for you. 8 Setup now checks to ensure there is enough space available on the disk for the installation. ###Checking for available disk space for HAHTsite#### When setup has verified sufficient disk space is available for the installation, it prompts you for your HAHTsite Application Server serial number, found on the CD jewel case. Enter serial number: Enter the serial number and press Return. If the serial number is accepted, continue on to the next step. 9 Choose the role(s) (control host, foreground host, background host) that you wish this server to play in the distributed configuration. If you are unfamiliar with the definitions of these roles, read the text displayed by the setup program prior to these prompts, or see Chapter 1, Planning Your Installation. 55

67 Chapter 4: Installing the HAHTsite Application Server (UNIX) Configure this server to be a Primary Control Server [RETURN=NO]: Configure this server to be a Foreground Server [RETURN=NO]: Configure this server to be a Background Server [RETURN=NO]: If you select No for Primary Control Server, you will also see the following prompt before the foreground and background prompts: Configure this server to be a Backup Control Server [RETURN=NO]: Enter Y for each role that you want this server to play in the distributed configuration. Enter N if you don t want this server to play a particular role. 10 At this point setup provides information about firewall and port configuration. For more information about firewalls and ports, read Chapter 1, Planning Your Installation. At the end of the information, setup prompts you: Press RETURN or ENTER to continue: Read the information, and press Return when you are ready to select your firewall configuration. 11 Select the number that best describes the properties of this machine with respect to your network and firewall configuration. Enter 1 if your network does not use a masquerading firewall, or all Application Server host machines reside on one side of the firewall. Jump to Step 13, Distributed Application Server Setup. Enter 2 if this machine will reside inside the masquerading firewall, and one or more hosts will reside outside the firewall. Enter 3 if this machine will reside outside the masquerading firewall, and one or more hosts will reside inside the firewall. Jump to Step 13, Distributed Application Server Setup. Please select one of the above options 1-3 [RETURN=1]: 12 Specify the public address of your firewall. Enter Public Firewall network name or IP address: Enter the public address of your firewall and press Return. If you are not sure what your public firewall address is, consult your network administrator before continuing with the installation. 13 Provide administrative host information for this installation. Setup will provide the most likely default values for this machine. The Administrative Host Name is used to identify the host in the HAHTsite 56

68 Chapter 4: Installing the HAHTsite Application Server (UNIX) Administration Tool. The Host Name or IP address is the Network Name or address used to locate this host. Enter HAHTsite Administrative name for this host. Administrative Host Name[RETURN=machinename]: Enter Host Name or IP address [RETURN=machinename.domain.com]: Press Return to accept the default for each prompt or type in an alternate value and press Return. If you are installing a primary control server, continue to the next step. Otherwise, jump to Step If you are installing the primary control server, you will also see this prompt: Enter the Primary Control Server s service port [RETURN=9090]: Press Return to accept the default port number (9090) or type in an alternate port number and press Return. If you are installing a foreground or background server, continue to the next step. Otherwise, jump to Step If you are installing a foreground or background server but not a control server, you will see these prompts: Enter the Control Server s Host Name or IP address: [RETURN=machinename.domain.com]: Enter the Primary Control Server s service port [RETURN=9090]: Enter a value for each prompt and press Return. 16 If you specified that this server is a foreground or control host, setup reminds you at this point that you will need specific information about your Web server before you continue. You will need to know the following: The directory path where your web server is installed (Setup will attempt to automatically configure your Web server when given the Web server s installation directory. If setup is successful, you will not need to supply the remaining items.) The directory path used by your web server for the CGI-BIN alias The directory path used by your web server for the static or primary document root The URL to the Web server (Example: If you don t have the information available, setup lets you exit the instatllation at this time. Would you like to continue the installation of the HAHTsite Application Server [return=yes]: 57

69 Chapter 4: Installing the HAHTsite Application Server (UNIX) Press Return to accept the default of yes. Or, if you do not have the information ready, type no and press Return to cancel the installation. If you are installing a background server, continue to the next step. Otherwise, jump to Step At this point, if you specified that this server is a background host, the installation program will try to detect ODBC in your system. If setup successfully detects ODBC, jump to Step 26. If it fails to detect ODBC, setup prompts you to install it. Note - You must be logged in as root in order to install ODBC in the standard location (/opt/odbc). Otherwise, the default in Step 1 will be your home directory. 18 Determine whether you currently have Open DataBase Connectivity (ODBC) drivers for database access installed. Do you currently have ODBC installed [RETURN=NO]? Answer yes if ODBC is already installed (but was not detected). You will be prompted for a pathname. Type the pathname for your ODBC drivers, and press Return. Jump to Step 30. Accept the default of no if ODBC is not currently installed. Setup will prompt you to install it in the following steps. 19 Specify the full path where you want to install ODBC. The standard location for the installation of ODBC is /opt/odbc. Note - You must be root to install ODBC in the standard location. Otherwise, the default is your home directory. HAHTsite is shipped with 30-day ODBC drivers from INTERSOLV, Inc. During the installation, you will be prompted to read and accept a license agreement for the software. Enter parent directory for ODBC [RETURN= /opt]-> Press Return to accept the default, or type another directory and press Return. 20 Provide registration information for the ODBC installation. Please enter the following information for proper registration. Name: Company: Serial Number: IPE Key: 58

70 Chapter 4: Installing the HAHTsite Application Server (UNIX) Respond to each of the four prompts, giving your INTERSOLV license serial number and IPE Key. For trial installations, enter EVAL for Serial Number and leave the IPE Key blank. 21 Specify the user who will own the Application Server code. The setup program will not complete the installation unless you set the user ownership of these files. ### Selecting User and Group Ownership of installed code ### Enter the Username of the owner for HAHTsite. [RETURN=root]-> Press Return to accept root as the user owner of the files, or type another user name and press Return. 22 Specify the group that will own the Application Server code. The setup program will not complete the installation unless you set the group ownership of these files. Enter the Group owner for HAHTsite. [RETURN=other]-> Press Return to accept other as the group owner of the files, or type another group owner and press Return. 23 Specify the User ID that is used to start the Application Server so that it can interact with the Web server. The User ID should not have security privileges that could compromise your system. Most systems are already configured with the User ID nobody for this purpose. You can type the numeric UID or ASCII text. Enter the User ID to be used to run the HAHTsite Application Server. [RETURN=nobody]-> Press Return to accept nobody as the default, or type another User ID and press Return. 24 Specify the Group ID that is associated with the User ID in Step 23. The Group ID should not have security privileges that could compromise your system. Most systems are already configured with the Group ID nobody for this purpose. You can type the numeric GID or ASCII text. Enter the Group ID to be used to run the HAHTsite Application Server. [RETURN=nobody]-> Press Return to accept nobody as the default, or type another Group ID and press Return. 25 Specify whether you want the Application Server to start up automatically at system start-up. If you answer yes, the default is to start up all server 59

71 Chapter 4: Installing the HAHTsite Application Server (UNIX) groups at boot time. Refer to Chapter 2 of the HAHTsite Application Server Administration Guide to limit the server groups that the system auto-starts. If you answer no, you will have to start and stop the Application Server manually every time you start up your system. Do you want HAHTsite to auto start at system start-up (Default is yes]: Press Return to accept yes as the default, or type no and press Return. 26 If you specified that this server is a foreground or control host, you will see this prompt: Please enter the installation directory for your Web server: Enter the pathname of the installation directory for your Web server. ###### How to start & stop the HAHTsite Application Server ##### When you press Return, setup responds provides a brief description of how to start and stop the Application Server, then begins the installation process. ##### Starting installation of HAHTsite Application Server ##### If you are installing the Application Server on Solaris 2.6, jump to Step 28. For Solaris 2.5.1, proceed to the next step. 27 On Solaris 2.5.1, setup now installs the Sun Java VM 1.x. 28 On Solaris 2.6, setup prompts you to determine which Sun Java VM you want the Application Server to use. The HAHTsite Application Server can be configured to work with either Sun's Java VM 1.x or 2.x. Select the number for the Sun Java VM you want to use for this Application Server. [RETURN=2]: Press Return to use the Sun Java VM 2.x, or type 1 and press Return to use the Sun Java VM 1.x. Setup displays the following while working: Configuring JRE for HAHTsite 29 Specify whether you want to install the VisiBroker CORBA Object Request Broker (ORB). Setup prompts you with the following: This component consists of all files necessary to use CORBA with HAHTsite Applications. Do you wish to install the VisiBroker components[return=no]:y Press Return to accept yes as the default, or type no and press Return. If you selected yes, setup prompts you for the following additional information needed to configure the Visibroker ORB: 60

72 Chapter 4: Installing the HAHTsite Application Server (UNIX) Master administrator name for control host: Master administrator password: Domain (for NT control hosts only]: Backup Control Host Public Port: Type the requested information at each prompt, and press Return. 30 At this point, if setup detects a previous Application Server installed at this location, setup gives you the option of reconfiguring the existing installation or preserving the current configuration. A previous Application Server installation has been found installed at /InstallDir/InstallName. Do you want to preserve this Application Server configuration? [RETURN=YES]: Press Return to preserve the existing configuration, or type n to reconfigure the previously installed Application Server. 31 Specify an installation name for this server group, or accept the default, webapps (see page 52 for a description of server groups). The name you type can be anything, but note that server group names are case sensitive. You can use the administration utility to configure additional server groups after the installation. Please enter Initial Server Group Name. [RETURN=webapps]: Press Return to accept the default, webapps, or type a server group name and press Return. 32 Set up a Master Administrator with a valid login account. The Master Administrator is the name of the user account that initially administers the Application Server with the Administrator utility. The Master Administrator has all privileges to administer all server groups. Other users are able to administer a given server group if the Master Administrator grants the user permission. After the installation, the Master Administrator can use the Administrator utility to change the Master Administrator. The name should not be root or an account with any security access privileges. Please enter the user name that will be Master Administrator [RETURN=value]: Type a name and press Return. 61

73 Chapter 4: Installing the HAHTsite Application Server (UNIX) Note - Steps 21 through 33 are only for root installations. If you are logged in as a user other than root, and you are installing a control or background host, but are not installing as root, jump to Step 34. If you are not logged in as root and are installing a foreground host, jump to Step Specify whether you want to use the operating system to authenticate logins to the Administrator utility. If you need help deciding, see User Account Authentication in Chapter 2 of the Application Server Administration Guide. If you are installing as root, you will see this prompt: ### Notice: Configure HAHTsite Admin Tool Authentication Method ### Do you wish to use the native operating-system authentication [RETURN=NO]? Press Return to accept the default, or type yes and press Return. In this case, the Master Administrator account specified in Step 32 must be a valid UNIX login account. Starting HAHTsite Application Server Group server_group_name. If you answered no, the setup program configures HAHTsite authentication. After the installation, start the Administrator, log in, and set an initial password for the master administrator account whose name is specified above: see Chapter 2 of HAHTsite Application Server Administration Guide. If you are installing a foreground host, jump to Step control and background hosts only. Verify that you want the setup program to configure your relational database environments. During this this part of the installation, setup configures your database(s). One or more of the prompts described may appear, depending on the relational database software that setup finds on your system. These prompts let you verify or correct the directory parameters for each relational database product found. You need to correct the parameters if you installed a database product in a location other than the default login directory. The setup program uses the responses to create a configuration file (.dbenv.conf) that the Application Server loads and reads. 62

74 Chapter 4: Installing the HAHTsite Application Server (UNIX) If you do not know a response, ask your database administrator. You can edit your responses later or add entries for any relational database vendors not included in the setup program (see Editing.dbenv.conf on page 73). Would you like to configure any relational database environments for the Application Server (y/n)?[y] Press Return to accept the setting. At this point, software-specific prompts appear that apply to the relational database software on your system. Or, type no and press Return. In this case, no further prompts appear for this part of the installation procedure. Jump to Step Set the ORACLE_HOME environment variable that Oracle uses to locate its own binary files and the correct instance of Oracle. Please correct if the following directory is not the base directory for oracle. Is this the correct setting for ORACLE_HOME=[/databases/Oracle]:(y/n)[y]? Press Return to accept the default setting, or type no and press Return to be able to type in the correct setting. If you accept the default setting, the next database prompt (if any) appears. 36 Set the SYBASE environment variable to the home directory where SQL Server/System 10 is installed. Please correct if the following directory is not the base directory for Sybase. Is this the correct setting for SYBASE = [/databases/sybase]:(y/n)[y]? Press Return to accept the setting, or type no and press Return to be able to type in the correct setting. Once you have accepted the setting (or entered a new one), the next database prompt (if any) appears. 37 The INFORMIXDIR environment variable must be set to the home directory where INFORMIX is installed. Please correct if the following directory is not the base directory for Informix. Is this the correct setting for INFORMIXDIR=[/databases/Informix]:(y/n)[y]? Press Return to accept the setting, or type no and press Return to enter the correct setting. 38 Set the INFORMIXSERVER variable to the server name. This is a required variable. ### Relational Database Configuration Notes ### Please enter a valid value for INFORMIXSERVER: 63

75 Chapter 4: Installing the HAHTsite Application Server (UNIX) Type a valid value and press Return. If the value is not valid, a warning message informs you that you can add the value later to the configuration file (.dbenv.conf). 39 Set the II_SYSTEM variable to the server name. Please correct if the following directory is not the base directory for Ingres. Is this the correct setting for II_SYSTEM = [/databases/ingres]:(y/n)[y]? Press Return to accept the setting, or type no and press Return to enter the correct setting. Once you have accepted the setting (or entered a new one), the next database prompt (if any) appears. 40 Foreground and control hosts only. Select the Web server to be configured for use with HAHTsite. For example, the standard installation directory for Netscape is /usr/ns-home. Under this directory, you have multiple Web server configuration directories such as https-yourdomain or httpd The prefix of the identifier is associated with the version of Netscape. The suffix is the identifier. In the above example, the identifiers would be yourdomain and During this this part of the installation, the setup program tries to configure your Web server. Note that in the UNIX installation, you must have a Web server installed, although you can reconfigure the Web server later, or add other Web servers, by using the utility WSUtil. See Starting Web Server Utility on page 81. The setup program uses the following file-naming convention for the new configuration files: filename.conf.bak.pid where: filename.conf is the original filename (such as obj.conf). PID is the process ID of the installer setup. This convention ensures that the original configuration file remains intact. Setup looks in your Web server installation directory and tries to detect possible Web servers. Setup can auto-configure only a limited subset of the possible Web servers. However, you can specify another Web server for manual configuration. Do you wish to configure the server with an identifier of Webserver-identifier [RETURN=YES]? 64

76 Chapter 4: Installing the HAHTsite Application Server (UNIX) Press Return to accept the default, yes, and configure the Web server. Proceed to Step 41. Or, type no and press Return. In this case, setup repeats the prompt, showing the next Web server in the directory, until you select one or the list is exhausted. At that point you are asked Do you wish to configure another Web server? If setup did not auto-detect the Web server you want to configure, then say yes. You will be asked for the following information: the directory path used by your Web server for the CGI-BIN alias the directory path used by this Web server for the static or primary document root the URL to this Web server the CGI alias assigned to this Web server 41 NSAPI, the API for Netscape, is a high-performance CGI access method. If your Web server supports NSAPI, you will see this prompt: Do you wish to configure this server to use NSAPI [RETURN=NO]? Press Return to accept the default. Jump to Step 44. Or, type yes and press Return. The following text appears: NSAPI configuration will be performed. 42 Specify whether you want the setup program to configure standard CGI as a backup to NSAPI or as an alternative access method. Do you wish to also configure the standard CGI [RETURN=NO]? Press Return to accept the default. This text appears: NSAPI will be the only option configured. If you selected no, jump to Step 46. Or, type yes and press Return. This text appears: Request: CGI alias selection. 43 To use the NSAPI access method, you must set up a CGI alias to use in URLs to refer to NSAPI. For example, if you assign your-bin to be your CGI alias for NSAPI, the URL form would be similar to: Each CGI alias must be unique. Enter NSAPI CGI alias to be assigned [RETURN=/cgi-bin]: Type a name for the CGI alias and press Return. 44 Enter the standard CGI alias. 65

77 Chapter 4: Installing the HAHTsite Application Server (UNIX) Enter standard CGI alias to be used by the Web server [RETURN=/cgi-bin]: Type the fully qualified path and press Return. Note - If you press Return without typing anything, the prompt in Step 42 reappears. The prompt gives you the opportunity to type no as the response. One of the following messages appears: Notice: Web server has a CGI alias already configured. If this message appears, proceed to Step 45. Notice: Web server restart. If this message appears, jump to Step The setup program informs you if the Web server CGI alias is already assigned to InstallDir/cgibin. Then setup asks you to choose one of the following methods of configuring CGI access to HAHTsite: 1. Install the HAHTsite binaries into the current CGI alias /cgi-bin directory at InstallDir/cgibin for use by Standard CGI. 2. Change the current /cgi-bin alias to point to the HAHTsite product directory at InstallDir/cgibin exclusively using Fast NSAPI CGI. 3. Create a new CGI alias that maps to the HAHTsite product directory InstallDir/cgibin using Standard CGI. Please select one of the above options 1-3 [RETURN=1]: Type an option number and press Return. 46 The setup program changed your Web server s configuration. You must restart the Web server for the changes to take effect. ### Notice: Web server needs restarting ### Do you want to restart this Web server [RETURN=YES]? Press Return to accept the default, which restarts the Web server, or type no and press Return. A message reminds you to restart the Web server after the installation. 47 Setup offers to check the installation s publish access paths to help prevent any problems with publishing HAHTsite projects to this machine. (This is highly recommended.) Would you like to check the publish path[return=yes]: Press Return to accept the default, and allow the check, or type no and press Return. 66

78 Chapter 4: Installing the HAHTsite Application Server (UNIX) 48 Next, setup needs to test the publisher's login ID used by the IDE's ftp agent. This test verifies the publish path used by the HAHTsite IDE during project publishing, and also checks this login ID's group access to let you know whether other login ID's within the same group have the same access rights during project publishing. Enter the Login ID to be used during project publishing. (return=currentlogin)-> Press Return to accept the default, or type another login ID and press Return. 49 Indicate whether this Web server will be used for the HAHTsite Administrator utility. Do you wish to configure the HAHTsite admin tool to use this Web server (return = YES]?: Press Return to accept the default, yes. Type no and press Return if you want to use a different Web server. If you enter yes, the following text is displayed: Do you wish to configure another Web server? (return = NO] If you answer yes, setup will return you to the Step 1 prompt, allowing you to configure one or more additional Web servers. Note - If you are installing the Application Server using a nonroot account that does not own the Web server software, setup will not have the necessary access to update the Web server s configuration file. Setup generates the new configuration file anyway, puts it in /tmp/filename.conf, and prints a message. (For Netscape, filename is obj.conf; for NCSA or Apache, filename is srm.conf.) To complete the configuration of your Web server, you need to become root or the owner of the Web server software, and copy /tmp/filename.conf to your Web server s configuration directory. Then restart your Web server. License information This this part of the installation occurs if you are installing the control host. At the end of the Application Server installation, setup displays information about extending the user license count. By default, the Application Server is 67

79 Chapter 4: Installing the HAHTsite Application Server (UNIX) set up to allow only five concurrent users. In order to increase this number, you must contact HAHT Software, Inc. to request a new license key. For more information about using the Administration utility, requesting a license key, and upgrading your user license count, see the HAHTsite Application Server Administration Guide. What s next? The following table identifies any setup tasks that you still need to perform and directs you to a procedure for each task. If... Then You Need to... Go to This Section You plan to debug Java projects on Solaris. You plan to debug Java projects on HP/UX. You plan to debug Java projects on AIX. You use HAHTsite authentication for Administrator utility logins. ODBC is not installed on your system. You plan to use flat-file drivers such as dbase with HAHTsite. Set the LD_LIBRARY_PATH environment variable. Set the SHLIB_PATH environment variable. Set the LIBPATH environment variable. Set an initial password for the Master Administrator s account. Set up connectivity to an ODBC data source. Increase the default number of file descriptors for flat-file drivers such as dbase. Java debugging setup for Solaris on page 71 Java debugging setup for HP/UX on page 71 Java debugging setup for AIX on page 71 See HAHTsite Application Server Administration Guide, Chapter 2. Start the Administrator as explained in section Getting Started with the Administrator, then see Setting the Initial Master Administrator Password. Connecting to an ODBC data source on page 72. Using the flat-file ODBC drivers on page

80 Chapter 4: Installing the HAHTsite Application Server (UNIX) If... Then You Need to... Go to This Section Your Web server was not installed when you installed the Application Server - or - You plan to use more than one Web server with HAHTsite. You were unsure of a value for a relational database s environment variable when you installed the Application Server. - or - Your relational database vendor was not included in the part of the installation that configures the database environment. You allow HAHTsite IDE and/or IP users on client systems to publish applications to the Application Server. Set up the interface between your Web server and the HAHTsite Application Server. Edit the configured environment variables for relational databases. Make sure the following directories are accessible via either file sharing, FTP, or HTTP transfers. The installation directory of the Application Server. The Web server document root or doctree directory A default site definition is created by the installation process. You may need to customize and verify the site to ensure that all IDE and/or IP clients can publish successfully. Configuring your Web server after the installation on page 75. Editing.dbenv.conf on page 73. Chapter 3, Web Server and Database Configuration in the HAHTsite Application Server Administration Guide. 69

81 Chapter 4: Installing the HAHTsite Application Server (UNIX) If... Then You Need to... Go to This Section You installed a Background Host in a Distributed Application Server configuration. You installed the Application Server on AIX or HP/UX, and would like to enable your HAHTsite applications to use server-side Java. Configure one or more Distributed Server Groups to run on the Background Host. The Distributed Server Group(s) must be explicitly included on each Background Host. Also, the paths or URLs to use to publish dynamic components to the Server Group must be defined for each Background Host. Install JDK 1.1.2, which is available from IBM for AIX, and from HP for HP/UX. The JDKs for these platforms can be downloaded from p.html or respectively (as of the writing of this document). After installing JDK 1.1.2, run the script installjava.csh on the HAHTsite Application Server CD. This script will prompt your for the location of the JDK installation directory, and copy files from the JDK installation directory to the HAHTsite installation directory. Chapter 2, Maintaining Server Groups in the HAHTsite Application Server Administration Guide. 70

82 Chapter 4: Installing the HAHTsite Application Server (UNIX) If... Then You Need to... Go to This Section You may also want to use the HAHTsite Application Server Administrator to customize the Java Class Path that the Application Server will use when starting the Java Virtual Machine. Java debugging setup for Solaris Set the LD_LIBRARY_PATH environment variable within the shell in which the background server processes are started as follows: JDK1 setenv LD_LIBRARY_PATH $JDKHOME/lib JDK2 setenv LD_LIBRARY_PATH $JDKHOME/jre/lib/sparc Java debugging setup for HP/UX Set the SHLIB_PATH environment variable within the shell in which the background server processes are started as follows: JDK1 setenv SHLIB_PATH $JDKHOME/lib/PA_RISC/green_threads JDK2 setenv SHLIB_PATH to the appropriate library directory for HP/UX Java debugging setup for AIX Set the LIBPATH environment variable within the shell in which the background server processes are started as follows: JDK1 setenv LIBPATH $JDKHOME/lib JDK2 setenv LIBPATH to the appropriate library directory for AIX 71

83 Chapter 4: Installing the HAHTsite Application Server (UNIX) Connecting to an ODBC data source Perform this task if you plan for any of your HAHTsite applications to access databases via Open DataBase Connectivity (ODBC) drivers. If you plan to use the native database drivers provided with the HAHTsite Application server, or to only use flat-file ODBC drivers, you do not need to perform this task. The setup program installs ODBC and configures the database environment for you. You will, however, not have database connectivity until you connect to an ODBC data source on both the client and the server side. To connect to an ODBC data source, you modify the ODBC configuration file (.odbc.ini). The setup program cannot configure the file for you because the file must contain configuration information that is specific to your database. The installation script installs.odbc.ini into two locations for you: The Application Server s installation directory the INTERSOLV driver manager looks in the current home directory for.odbc.ini. The HAHTsite start-up script sets the current home directory to the Application Server s installation directory, so the INTERSOLV driver can find the file. The login directory of the user (UID) who is running the Application Server the Visigenics driver manager will only look for the.odbc.ini file in the login directory of the user (UID) who is running the Application Server. The HAHTsite start-up script loads Visigenics first by default. Unless you change the sequence, this.odbc.ini file is the file that will be used. You can modify either version of the file, but copy whatever changes you make in one file to the other file; do not keep two versions of the file on your system. The copy of odbc.ini that the setup program installs in the above locations is a skeleton version. The file has some default settings, but you must modify the system-specific settings such as the database settings, server name, and password fields. If you do not know how to modify.odbc.ini, use the help files that ship with the Application Server software. These files are located in the odbc directory in a sub-directory called doc. The help files are in.pdf format, and you must have Adobe Acrobat Reader to view them. Note - The INTERSOLV drivers are shipped on a 30-day trial basis. After the 30-day period expires, the drivers will stop. Contact INTERSOLV to get a license if you want to continue using the drivers. 72

84 Chapter 4: Installing the HAHTsite Application Server (UNIX) Using the flat-file ODBC drivers Note - This information applies to Solaris installations only. For other operating systems, contact HAHT technical support for assistance. Perform this task if you are going to use the flat-file ODBC drivers with HAHTsite. The setup script sets the number of file descriptors to match your system default, but you probably need to increase this number in order to use the drivers with HAHTsite. The number of file descriptors that you need depends on the amount of database activity that you expect and whether the database uses indexes. Here is an example of the number of file descriptors used: the dbase log file uses one descriptor, and the Application Server uses approximately five. If an application opens one database table that has an index, that operation uses two file descriptors. If you have 29 concurrent users (29 unique StateIds running) who are all accessing database tables with indexes, then you ve used approximately 64 file descriptors. The procedure for increasing the number of file descriptors follows. 1 Open the HAHTsite start-up script in the bin subdirectory of the Application Server s installation directory. 2 Locate the following line: #DESCRIPTORS=number (where number is the number of descriptors for your current system setting). 3 Remove the pound sign (#) in front of the Descriptors label and type a number based on your requirements. A sample entry follows: DESCRIPTORS=1012 Your new setting overrides the system default setting. If you ever see a message saying out of file handles, you need to increase the number again. The maximum number allowed is Editing.dbenv.conf The file.dbenv.conf contains the configured environment variables for relational database vendors. The file is generated during the installation. This section describes how to edit the file in case you left a value blank during the installation or you need to change a value. You can add entries to the file if 73

85 Chapter 4: Installing the HAHTsite Application Server (UNIX) your relational database vendor was not included in the part of the installation that configures the database environment. The file contains an entry for each environment variable that your system requires regardless of whether you supplied a value during the installation. If you did not supply a value for an environment variable, the variable is commented out. To edit.dbenv.conf 1 Open the file.dbenv.conf in the Application Server s installation directory. 2 Remove the pound sign (#) in front of the appropriate entry and type the correct value. A sample of the file follows. The sample has the entries for INFORMIXSERVER (shown in boldface type) commented out. # Vendor Specific Configuration for oracle ORACLE_HOME=/databases/Oracle export ORACLE_HOME # Define Shared Library Search Order LD_LIBRARY_PATH=${LD_LIBRARY_PATH:- ""}${LD_LIBRARY_PATH:+":"}:${ORACLE_HOME}/lib export LD_LIBRARY_PATH # Vendor Specific Configuration for sybase SYBASE=/databases/Sybase export SYBASE # Define Shared Library Search Order LD_LIBRARY_PATH=${LD_LIBRARY_PATH:- ""}${LD_LIBRARY_PATH:+":"}:${SYBASE}/lib export LD_LIBRARY_PATH # Vendor Specific Configuration for informix INFORMIXDIR=/databases/Informix export INFORMIXDIR # Define Shared Library Search Order LD_LIBRARY_PATH=${LD_LIBRARY_PATH:- ""}${LD_LIBRARY_PATH:+":"}:${INFORMIXDIR}/lib export LD_LIBRARY_PATH #INFORMIXSERVER= #export INFORMIXSERVER Viewing the site definition page This setup program uses the configuration settings from this installation to provide a static HTML page that contains the site definition that you need to 74

86 Chapter 4: Installing the HAHTsite Application Server (UNIX) connect the HAHTsite IDE to your Web server and the Application Server. You can view this HTML page from your Web browser using the following URL: URL: p_name/initial_server_group_name where: server_domain_name is the name by which the machine is known on the Web or intranet. port_num is the port number of the host s communication port. initial_server_group_name is the name entered for the initial server group during setup. Here is an example: URL: tml Note that if you accepted the default server group (webapps) as the initial server group to configure during the installation, the URL is: Configuring your Web server after the installation The script webautoconfig configures your Web server for use with the Application Server and copies the Application Server s binaries to the correct place. You can use this script if you are adding a Web server to your system or if you want to reconfigure an existing Web server. The program configures the Web server by determining the Web server s setting for the following values: the directory path that is used for the CGI alias the static or primary documentation directory root path the Web server s URL If the default CGI alias, CGI-BIN, has not been assigned, the script maps the alias to the Application Server s CGI binaries. If your Web server supports NSAPI, the script gives you the option of configuring NSAPI for use with HAHTsite. The script also lets you configure standard CGI. Running the script To run the script, change directory to the bin subdirectory of the Application Server s installation directory, and type webautoconfig. 75

87 Chapter 4: Installing the HAHTsite Application Server (UNIX) Note - To use the script, you must be able to supply the directory location where your Web server is installed. The script is straightforward, and you need only follow its prompts. If you need help, the same prompts are listed istarting with Step 40 of the installation procedure. Verifying the installation During the installation, you would have known if the installation failed for any reason because an error message would have appeared immediately after the error occurred. After the installation, you can check the installation log file for messages. The log file is located in the Application Server s installation directory in install.log. If the installation was successful, you can start the Application Server now. If you set up the Application Server to start automatically at system start-up, you can reboot your system to start the Application Server. Otherwise, you can start or stop the Application Server directly from the UNIX command line using the start-up script, HAHTsite, as described below. You also can use the HAHTsite Application Server Administrator (see the HAHTsite Application Server Administration Guide) to start the Application Server. Starting and stopping the Application Server from the command line Here s how to use the HAHTsite start-up script to start and stop the Application Server: 1 Go to the bin subdirectory of the Application Server s installation directory. 2 Use the following syntax to type a command to run the script:./hahtsite [-bcf] start The optional switches, -b, -c, and -f are used to start the Background, Control, and Foreground processes in a Distributed Application Server installation. If none of these switches is supplied, all installed components are started. For start operations, a password prompt appears if you are not already logged in under the defined startup account. 3 Type the password of the user account under which the Application Server is to run. 4 To stop the process, type./hahtsite [-bcf] stop 76

88 Chapter 4: Installing the HAHTsite Application Server (UNIX) The following table shows examples of usage. Action Start the Standalone HAHTsite Application Server (including all Server Groups defined to start automatically when the Application Server is started. Stop the Standalone HAHTsite Application Server (including all running Server Groups). Start the Foreground processes in a Distributed Application Server installation. Stop the Background processes, including all running Distributed Server Groups on a Background Host. Use this command./hahtsite start./hahtsite stop./hahtsite -f start./hahtsite -b stop Removing the Application Server from your system There are three stages to removing the Application Server software from your system: Removing the application directories Removing the installation directory Removing the Application Server s CGI-BIN files The following sections describe each stage. Before you start, use the Application Server Administrator or the HAHTsite script (described in Starting and stopping the Application Server from the command line on page 76) to stop the Application Server. Removing the application directories Use this procedure to remove the application directories. Note - If you remove the application directories, you cannot restore them by performing a reinstall. 1 For each server group, determine the directory path to the application and user data dictionaries. The paths are listed in the configuration files, 77

89 Chapter 4: Installing the HAHTsite Application Server (UNIX) server_group_name.conf (where server_group_name is the name of the server group) in the fields labeled CurrentDir and AppRootDir. 2 Type rm -r on each directory to remove the directory and all of its subdirectories. Removing the installation directory If you decided to keep the application and user directories, and they are located under the installation directory, you must remove the following directories individually: bin cgibin conf hsadmin logs lib Otherwise, type rm -r HAHTsite from the shell to remove the installation directory and all of its subdirectories. Removing the Application Server s CGI-BIN files You can leave the Application Server s executable files in the Web server s CGI- BIN directory without harming anything. If you want to remove them, the files are: hsrun hsmsgs30.en_us Either hsrunns.so (for Solaris and AIX) or hsrunns.sl (for HP) HS_comm.html HS_map.html HS_server.html HS_url.html 78

90 Web server configuration (UNIX) 5 Using the Web Server Utility...80 Starting Web Server Utility...81 WSUtil s main menu...81 [A]dd...82 [M]odify...84 [D]elete...86 [L]ist...87 [C]onfigure...87 [Q]uit

91 Chapter 5: Web server configuration (UNIX) Using the Web Server Utility When you install a HAHTsite Application Server on a machine, the HAHTsite installation program creates site-configuration files that describe the interface between the Application Server and a Web server. The Application Server side of this interface includes information about where the HAHTsite IDE/IP should publish static pages (to the Web server s staticpage directory) and an alias to the Web server s CGI directory (which contains the Application Server s hsrun program files). When the installation program runs, among other operations it: Locates the Web server s static-page directory (the place where the Web server looks for static pages) and copies the pages needed by the HAHTsite Application Server Administrator utility to that directory. Locates the Web server s CGI directory (the place where the Web server looks for executable programs) and copies the hsrun program files to that directory. Configures the URL Path to the Web server s CGI directory. Sets up methods for transferring files from the IDE to the Web server and the Application Server. This information is stored in the site-configuration files listed in the following table. File Type CGI Alias (.hca) Docroot (.hdr) Server group (.hsg) Site definition (.hst) Description Contains information on how to build a URL pointing to hsrun. (This is the program that the Web server executes to route requests for dynamic pages to a HAHTsite Application Server.) Describes how to publish static pages to a Web server, and the URL needed to browse the pages. Created and updated by the Application Server Administrator utility. Created and updated by IDE/IP site management dialogs. These files store references to the.hca,.hdr, and.hsg files. The site-configuration files listed in the above table are located in a host machine s HAHTsiteInstallDir/sites directory. 80

92 Chapter 5: Web server configuration (UNIX) As shown in the table,.hsg files are managed by the Application Server Administrator utility, and.hst files are managed by IDE/IP site management dialogs. You should edit.hca and.hdr files with the HAHTsite Web Server Utility (WSUtil). Here are some situations where you would want to use Web Server Utility: You installed a new Web server after installing a HAHTsite Application Server. You made changes to the configuration of the Web server you use with the Application Server. You want to customize the interface between a Web server and the Application Server, or remove an interface to a Web server that you no longer use. Starting Web Server Utility You can start Web Server Utility from a Unix shell: cd HAHTsiteInstallDir/bin (or add this to your path) and enter the command: wsutil WSUtil s main menu is displayed. WSUtil s main menu WSUtil s main menu displays the following: Operation ([A]dd, [M]odify, [D]elete, [L]ist, [C]onfigure, [Q]uit): Note - You must enter a value for Web Server Configuration Path: under the Configure option before your Web server s settings can be auto-detected by WSUtil. The following sections describe the functions of the utility s five main menu items and sub menu items. 81

93 Chapter 5: Web server configuration (UNIX) [A]dd Pressing A for Add presents a menu with the following choices: Item Add Auto- Detected Add Web Server Add HSrun Description To add an autodetected Web server, do one of the following: Enter l to redisplay the list. Enter the index number of the displayed detected Web server configuration to add a site configuration (Docroot or CGI Alias) for that entry. Or press Enter to return to the Add menu. Set the following to create a Docroot file (or press Enter to return to the Add menu): Name Logical Name for the Docroot file WebServer Type Type of Web server represented by this site. Choose 'default' if desired type is not listed. Browse URL URL pointing to Web server's static (doctree) directory. (e.g. You will also be asked to input the following information to create a Transfer Information Entry: Protocol Method used to transfer files between the Web server and the Application Server. URL Path or Transfer URL ( or ftp://) where the Web server looks for HTML files. (e.g. ftp://foo/docs) OS Web server host's operating system Set the following to create a CGI Alias file (or press Enter to return to the Add menu): Name Logical Name for the CGI Alias file WebServer Type Type of Web server represented by this site. Choose 'default' if desired type is not listed. Browse URL URL pointing to Web server's CGI scripts directory. (e.g. cgi-bin Directory Pathname of the Web server's CGI scripts directory. (e.g. /usr/local/httpd/cgi-bin) 82

94 Chapter 5: Web server configuration (UNIX) Item Add Site Definition Add Transfer Information Entry Description Set the following to create a Site Definition file: Name Logical Name for the Site Definition file WebServer Site WebServer (Docroot) site configuration file HSrun Site HSrun (CGI Alias) site configuration file Server Group Name Server Group (.HSG) file name (without.hsg extension) Maintain State ID by URLs or Cookies Whether the Web server will pass StateID information via URLs or Cookies. Server Side Java Location Directory for Server Side Java classes Subdirectory Subdirectory under the static and dynamic roots to which static and dynamic pages are published. Note - Typically the HAHTsite IDE/IP should be used to create Site Definition files. The functionality in wsutil for generating a Site Definition file is limited by the restriction that the Web Server Site, HSrun Site and Server Group files must all reside on the local machine. Operation Enter 'l' to redisplay the list -or- Press Enter to return to the Add menu. -or- Enter the index number of the displayed Docroot site configuration file to contain the Transfer Information Entry to be added. You will now be asked to input the following information to create a Transfer Information Entry: Protocol Method used to transfer files between the Web server and the Application Server. URL Path or Transfer URL ( or ftp://) where the Web server looks for HTML files. (e.g. ftp://foo/docs) OS Web server host's operating system A final choice exists to return to the main menu. 83

95 Chapter 5: Web server configuration (UNIX) [M]odify The Modify operation presents a menu with choices for adding a Web Server (Docroot) file, HSrun (CGI Alias) file, Site Definition file or a Transfer Information Entry from a Docroot file. There is also a choice to return to the main menu. Menu Item Modify Web Server Description Press Enter to return to the Modify menu. -or- Enter 'l' to redisplay the list -or- Enter the index number of the displayed Docroot site configuration file to be modified. The following Docroot attributes may be modified: Name Logical Name for the Docroot file WebServer Type Type of Web server represented by this site. Choose 'default' if desired type is not listed Browse URL URL pointing to Web server's static (doctree) directory. (e.g. After setting these attributes, the Docroot file has now been modified, and wsutil presents the option of modifying a Transfer Information Entry. Press Enter to return to the Modify menu. -or Enter 'l' to redisplay the list -or- Enter the index number of the Transfer Information Entry to modify and set/default the following: Protocol Method used to transfer files between the Web server and the Application Server. URL Path or Transfer URL ( or ftp://) where the Web server looks for HTML files. (e.g. ftp://foo/docs). OS Web server host's operating system 84

96 Chapter 5: Web server configuration (UNIX) Menu Item Modify HSrun Modify Site Definition Description Press Enter to return to the Modify menu. -or- Enter 'l' to redisplay the list -or- Enter the index number of the displayed CGI Alias site configuration file to be modified. The following CGI Alias attributes may be modified: Name Logical Name for the CGI Alias file WebServer Type Type of Web server represented by this site.choose 'default' if desired type is not listed Browse URL URL pointing to Web server's CGI scripts directory (for example, cgi-bin Directory Pathname of the Web server's CGI scripts directory (for example, /usr/local/httpd/cgibin). Note: Typically the HAHTsite IDE/IP should be used to modify Site Definition files. The WSUtil facility for modifying Site Definition files is much more limited in scope. Operation: Press Enter to return to the Modify menu. -or- Enter 'l' to redisplay the list -or- Enter the index number of the displayed Site Definition configuration file to be modified. The following Site Definition attributes may be modified: Name Logical Name for the Site Definition file WebServer Site WebServer (Docroot) site configuration file HSrun Site HSrun (CGI Alias) site configuration file Server Group Name Server Group (.HSG) file name (without.hsg extension) Maintain State ID by URLs or Cookies Whether the Web server will pass State ID information via URLs or Cookies. Server Side Java Location Directory for Server Side Java classes Subdirectory Subdirectory under the static and dynamic roots to which static and dynamic pages are published. 85

97 Chapter 5: Web server configuration (UNIX) Menu Item Modify Transfer Information Entry Description Operation: Enter 'l' to redisplay the list -or- Press Enter to return to the Modify menu. -or- Enter the index number of the displayed Docroot site configuration file to contain the Transfer Information Entry to be added. You will now be asked to input the following information to create a Transfer Information Entry: Protocol Method used to transfer files between the Web server and the Application Server. URL Path or Transfer URL ( or ftp://) where the Web server looks for HTML files. (e.g. ftp://foo/docs) OS Web server host's operating system [D]elete The Delete operation presents a menu with choices for deleting a Web Server (Docroot) file, HSrun (CGI Alias) file, Site Definition file or a Transfer Information Entry from a Docroot file. There is also a choice to return to the main menu. Menu Item Delete Web Server Delete HSrun Delete Site Definition Description Operation: Enter the index number of the displayed Docroot site configuration file to be deleted -or- Enter 'l' to redisplay the list -or- Press Enter to return to the Delete menu. Operation: Enter the index number of the displayed CGI Alias site configuration file to be deleted -or- Enter 'l' to redisplay the list -or- Press Enter to return to the Delete menu. Operation: Enter the index number of the displayed Site Definition configuration file to be deleted -or- Enter 'l' to redisplay the list -or- Press Enter to return to the Delete menu. 86

98 Chapter 5: Web server configuration (UNIX) Menu Item Delete Transfer Information Entry List... Description Note: Deleting the last Transfer Information Entry for a Docroot file is not allowed and will generate a warning message. Operation: Enter 'l' to redisplay the list -or- Press Enter to return to the Delete menu. -or- Enter the index number of the displayed Docroot site configuration file containing the Transfer Information Entry to be deleted. A new list appears (assuming there are two or more Transfer Information entries in the selected Docroot site) with the indices of the Docroot site's Transfer Information Entries. Now: Enter 'l' to redisplay the list -or- Press Enter to return to the Delete menu. -or- Enter index of the Transfer Information Entry to deleted. Display the CGI Alias, Docroot, and Site Definition site configuration files available on the local host. Operation: Enter the index number of the displayed site configuration file to see detailed information about the file - or- Enter 'l' to redisplay the list -or- Press Enter to return to the main menu. [L]ist Display the site configuration files (CGI Alias, Docroot, and Site Definition) available on the local host. Enter the index number of the displayed site configuration file to see detailed information about the file or Enter l to display the list again or Press Enter to return to the main menu. [C]onfigure At each prompt, enter a new value or press Enter to accept the current value to display and permit the modification of the current wsutil configuration parameters: HAHTsite Installation Path The root directory for the HAHTsite installation. (e.g. /opt/hahtsite) 87

99 Chapter 5: Web server configuration (UNIX) Sites Path The root directory for the site configuration files. (e.g. /opt/hahtsite/sites) Web Server Configuration Path Where HAHTSite looks for Web server configuration files when auto-detecting Web servers (e.g. /usr/local/httpd/conf). You must give the path to your Web server s configuration file directory. Copy HSrun files to WebServer CGI-Bin Indicates whether wsutil should copy the hsrun files from the HAHTsite cgibin directory to the cgi-bin directory of a detected Web server when adding that Web server. [Q]uit Select Quit to exit the Web Server Utility. 88

100 Database configuration 6 Introduction...90 Connecting to an ODBC data source (Windows NT)...90 Connecting to an ODBC Data Source (UNIX)...94 Editing environment variables for relational databases (UNIX)...96 Increasing the number of file descriptors for flat-file ODBC drivers (Solaris)

101 Chapter 6: Database configuration Introduction This chapter describes procedures that may be required to configure the HAHTsite Application Server with databases used at your site. Connecting to an ODBC data source (Windows NT) The setup program installs ODBC, but you will not have database connectivity until you connect to an ODBC data source on both the client and the server side. This section provides an example of how to set up an ODBC data source. Note - The specific steps you take to establish an ODBC data source depend on the Operating System and database that you are using. The steps in the following example are for the Windows NT 4.0 operating system and the Microsoft Access database. 1 Click the Control Panel s ODBC icon. The Data Sources dialog appears. 2 Select the System DSN tab. 90

102 Chapter 6: Database configuration 3 In the System Data Sources dialog, click Add... The Add Data Source dialog appears. 4 In the Add Data Source dialog, click the type of ODBC driver that you want to use, and click Finish. The ODBC setup dialog for the type of database that you selected appears. 91

103 Chapter 6: Database configuration 5 In the ODBC setup dialog: Enter a name for the data source. This is the name that will appear in the list of ODBC data sources and in the HAHTsite Connection Manager. Optionally, enter a description of the data source. Click Select. The Select Database dialog appears. 6 In the Select Database dialog, select the database that you want to use as a source. Be sure that the database you select is the same type as the ODBC driver you chose in Step 4. For example, if you selected Access in Step 4, select Access here. 7 Click OK to return to the ODBC setup dialog. 92

104 Chapter 6: Database configuration 8 Optionally, in the ODBC setup dialog, click Advanced. The Set Advanced Options dialog appears. Type login information (username and password). You can use a database widget s connection string properties to send the username and password from a Web page to the database. In the Options list, change the values of the listed parameters. Click OK to return to the ODBC setup dialog. 9 In the ODBC setup dialog, click OK. The System Data Sources dialog appears. The name of new data source is now in the list of data sources. 93

105 Chapter 6: Database configuration The new HAHT_Intro40 data source 10 Click Close to display the Data Sources dialog. 11 In the Data Sources dialog, click Close to exit the ODBC Administrator. Connecting to an ODBC Data Source (UNIX) HAHTsite requires Open DataBase Connectivity (ODBC) drivers to access databases. The setup program installs ODBC, but you will not have database connectivity until you connect to an ODBC data source on both the client and the server side. To connect to an ODBC data source, you modify the ODBC configuration file (.odbc.ini). The setup program cannot configure the file for you, because the file must contain configuration information that is specific to your database. The installation script installs.odbc.ini in two locations for you. Having two locations lets both of the driver managers that are shipped and installed with the Application Server (INTERSOLV and Visigenics) find the file. Here are the locations where you can find a copy of.odbc.ini: 94

106 Chapter 6: Database configuration The Application Server s installation directory the INTERSOLV driver manager looks in the current home directory for.odbc.ini. The HAHTSITE start-up script sets the current home directory to the Application Server s installation directory, so the INTERSOLV driver can find the file. The login directory of the user (UID) who is running the Application Server the Visigenics driver manager will only look for the.odbc.ini file in the login directory of the user (UID) who is running the Application Server. The HAHTSITE start-up script loads Visigenics first by default. Unless you change the sequence, this.odbc.ini file is the file that will be used. You can modify either version of the file, but copy whatever changes you make in one file to the other file; do not keep two versions of the file on your system. The copy of odbc.ini that the setup program installs in the above locations is a skeleton version. The file has some default settings, but you must modify the system-specific settings such as the database settings, server name, and password fields. If you do not know how to modify.odbc.ini, use the man pages that ship with the Application Server software. The Following table contains a list of the available man pages: Driver INTERSOLV driver manager 1 Visigenics driver manager 1 DBF Informix 5 Informix 7 Oracle 7 Oracle 6 SQL Server Sybase Text driver Filename odbc_ini.4 vsbasics.1 qedbf.4 qeinf5.4 qeinf7.4 qeor7.4 qeora.4 qess.4 qesyb.4 qetxt.4 1. This man page also contains general information on configuring.odbc.ini. Here s how to access the man pages: 95

107 Chapter 6: Database configuration 1 Run one of the following scripts to establish your environment so that you can look at the man pages: For Csh shell, type % source./odbc_install_dir/.odbc.csh For Bourne or Korn shell, type %./odbc_install_dir/.odbc.sh Instead of odbc_install_dir, type the installation directory for ODBC. Note - Only source the above scripts, if you want to read the man pages or plan to do ODBC development outside the HAHTsite environment. Do not source the above scripts and then run the HAHTSITE start-up script. If you do, you will change the order in which the HAHTSITE start-up script loads the driver managers. 2 Type the following to list the man pages: % ls odbc_install_dir/man/man4 sed 's/\.4//' 3 Type the following to open the appropriate file: % man pagename Editing environment variables for relational databases (UNIX) The file.dbenv.conf contains the configured environment variables for relational database vendors. The file is generated during installation. You can edit the file if you need to change a value. You can also add entries to the file if you add a relational database to your system. A sample of the file follows. # Vendor Specific Configuration for oracle ORACLE_HOME=/databases/Oracle export ORACLE_HOME # Define Shared Library Search Order LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-""} _ ${LD_LIBRARY_PATH:+":"}:${ORACLE_HOME}/lib export LD_LIBRARY_PATH # Vendor Specific Configuration for sybase SYBASE=/databases/Sybase export SYBASE # Define Shared Library Search Order LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-""} _ ${LD_LIBRARY_PATH:+":"}:${SYBASE}/lib export LD_LIBRARY_PATH 96

108 Chapter 6: Database configuration # Vendor Specific Configuration for informix INFORMIXDIR=/databases/Informix export INFORMIXDIR # Define Shared Library Search Order LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-""} _ ${LD_LIBRARY_PATH:+":"}:${INFORMIXDIR}/lib export LD_LIBRARY_PATH #INFORMIXSERVER= #export INFORMIXSERVER Increasing the number of file descriptors for flat-file ODBC drivers (Solaris) The setup script sets the number of file descriptors to match your system default. However, it is recommended that you increase this number in order to use the drivers with HAHTsite. The number of file descriptors that you need depends on the amount of database activity that you expect and whether the database uses indexes. Here is an example of the number of file descriptors used: the dbase log file uses one descriptor, and the Application Server uses approximately five. If an application opens one database table that has an index, that operation uses two file descriptors. If you have 29 concurrent users (29 unique StateIds running) who are all accessing database tables with indexes, then you ve used approximately 64 file descriptors. The procedure for increasing the number of file descriptors follows. 1 Open the file.envinfo.conf in the Application Server s installation directory. 2 Locate the following line: #DESCRIPTORS=number (Instead of number, the number of descriptors for your current system setting appears.) 3 Remove the pound sign (#) in front of the DESCRIPTORS label and type a number based on your requirements. A sample entry follows: DESCRIPTORS=1012 Your new setting overrides the system default setting. If you ever see a message saying out of file handles, you need to increase the number again. The maximum number allowed is

109 Chapter 6: Database configuration 98

110 Setting up NSAPI, ISAPI, and the Oracle Cartridge A Introduction Setting Up NSAPI Windows NT UNIX Setting Up ISAPI Setting Up ISAPI for IIS Setting Up the Oracle Web Application Server Configuring the Administrator as an NSAPI, ISAPI, or Oracle application

111 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge Introduction This appendix describes how to configure the HAHTsite Application Server for use with three standard (or compliant) Web servers: the Netscape Server Application Program Interface (NSAPI), the Microsoft Internet Server Application Program Interface (ISAPI), and the Oracle Cartridge. The appendix also explains how to configure the Administrator utility to work with NSAPI, ISAPI, and the Oracle cartridge. Note - The procedures in this appendix explain how to configure the Application Server so that it will work with an NSAPI, ISAPI, or Oracle Web Server. The site definition that an application is published to must also specify one of these options: otherwise, the application will run as a CGI application. Site definitions are explained in the chapter About Sites in the HAHTsite IDE and IP User Guide and in the section Using the Web Server Utility in Chapter 3 of the HAHTsite Application Server Administration Guide. Setting Up NSAPI Setting up NSAPI is slightly different on Windows NT and UNIX. This section contains a procedure for each set up. Windows NT This procedure assumes that you ve installed the Netscape server and configured its CGI-BIN directory. Note - You must use a forward slash (/) in the filename strings. 1 Go to the Netscape server s config subdirectory. For example, if the Netscape server software is in c:\programs\netscape\server, and the default server is https-httpd-80, you would go to c:\programs\netscape\server\https-httpd-80\config. 2 Open obj.conf for editing. 3 Find this line: Init fn="load-types" mime-types="mime.types" 100

112 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge 4 After the above line, add the following two lines: Init fn="load-modules" funcs="hsmsgsdummyinit" shlib= _ "drive:/hahtsiteinstalldir/cgibin/hsmsgs40.dll" Init fn="load-modules" funcs="pfx2hsrun,run-hsrun" _ shlib="drive:/hahtsiteinstalldir/cgibin/hsrunns30.dll" where drive is the drive where you installed the Application Server and HAHTsiteInstallDir is the Application Server s installation directory. Note - If you are running a Netscape version 3.5 or 3.6 Web server, add the above line to your obj.conf file, substituting hsrunns35.dll for hsrunns30.dll. These lines load the messages DLL and the NSAPI DLL version of hsrun. 5 In the section <Object name="default">, find this line: NameTrans fn="pfx2dir" from="/cgi-bin" dir="path_to_cgi" name="cgi" 6 Before the above line, add: NameTrans fn="pfx2hsrun" from="/cgi-bin" _ dir="drive:/hahtsiteinstalldir/cgibin" _ name="hsrunns30.dll" hsrun="hsrun.hse" where drive is the drive where you installed the Application Server and HAHTsiteInstallDir is the Application Server s installation directory. Note - If you are running a Netscape version 3.5 or 3.6 Web server, add the line as above, substituting hsrunns35.dll for hsrunns30.dll. This line causes hsrun to look for its special signature before looking for general CGI scripts. The Application Server returns not found errors if the NSAPI filter line is placed after the CGI filter line. hsrun translates /cgi-bin/hsrun.hse to the path drive:/hahtsiteinstalldir/cgibin/hsrunns30.dll and sets an internal object type to hsrunns30.dll, which tells the Application Server to perform further processing using the object section of that name. 7 At the end of the file (right after the cgi object section), add a new object section as follows: <Object name="hsrunns30.dll"> ObjectType fn="force-type" type="magnus-internal/hsrunns30.dll" Service fn="run-hsrun" </Object> 101

113 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge Note - If you are running a Netscape version 3.5 or 3.6 Web server, add the object section as above, substituting hsrunns35.dll for hsrunns30.dll. This section forces the MIME type to a special internal type that goes with the NSAPI DLL. This section also specifies the service function to process the request. UNIX Note - When you install the Application Server, the UNIX setup script performs the configuration described in this section. The information is provided here as reference. This procedure assumes that you ve installed the Netscape server and configured its CGI-BIN directory. Note - The shared-library extensions differ among UNIX platforms (e.g., on HP, the extension is.sl ). This procedure uses Solaris as an example. 1 Go to the Netscape server s config subdirectory and open obj.conf for editing. 2 In the section that contains the load-modules lines, find this line: Init fn="load-types" mime-types="mime.types" 3 After the above line, add the following line: Init fn="load-modules" funcs="hsrun-init,pfx2hsrun,run-hsrun" _ shlib="/hahtsiteinstalldir/cgibin/hsrunns.so" where HAHTsiteInstallDir is the Application Server s installation directory. This line loads the hsrun NSAPI shared library. 4 In the section that contains the "init" functions, add the following line: Init fn="hsrun-init" hsrun-path="/hahtsiteinstalldir/cgibin" where HAHTsiteInstallDir is the Application Server s installation directory. This routine initializes the hsrun code and specifies the location of the messages file, which is read as a regular file. 5 In the section <Object name="default">, find this line: NameTrans fn="pfx2dir" from="/cgi-bin" dir="path_to_cgi" name="cgi" 6 Before the above line, add: 102

114 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge NameTrans fn="pfx2hsrun" from="/cgi-bin" _ dir="/hahtsiteinstalldir/cgibin" name= _ "hsrunns.so" hsrun="hsrun.hse" where HAHTsiteInstallDir is the Application Server s installation directory. This line causes hsrun to look for its special signature before looking for general CGI scripts. The Application Server returns not found errors if the NSAPI filter line is placed after the CGI filter line. hsrun translates /cgi-bin/hsrun.hse to the path HAHTsiteInstallDir/cgibin/hsrunns.so and sets an internal object type to hsrunns.so, which tells the Application Server to perform further processing using the object section of that name. 7 At the end of the file (right after the cgi object section) add a new object section as follows: <Object name="hsrunns.so"> ObjectType fn="force-type" type="magnus-internal/hsrunns.so" Service fn="run-hsrun" </Object> This section forces the MIME type to a special internal type that goes with the Application Server s NSAPI DLL. This section also specifies the service function to process the request. Setting Up ISAPI This section contains a procedure for setting up ISAPI for use with the Application Server. This procedure assumes that you ve installed your IIS server and configured its CGI-BIN directory (usually the scripts subdirectory under your install directory). Note - IIS 4.0 requires a different procedure for setting up ISAPI. If you are running IIS 4.0, see Setting Up ISAPI for IIS 4.0 on page Copy hsrunisa.dll and hsmsgs40.dll and hslib40.dll to the scripts subdirectory. 2 Run regedt32. 3 Select HKEY_LOCAL_MACHINE\System\CurrentControlSet\ Services\W3SVC\Parameters. 4 If the key ScriptMap is not present, use Edit..Add Key to create a new key with the name ScriptMap. 103

115 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge 5 Select the ScriptMap key. 6 Use Edit..Add Value to add: A REG_SZ type value whose name is.hse (the filename extension associated with the Application Server s ISAPI extension module) A value that is the full path to hsrunisa.dll for example, c:\msiis\scripts\hsrunisa.dll Setting Up ISAPI for IIS 4.0 This section contains a procedure for setting up ISAPI on IIS 4.0 for use with the Application Server. This procedure assumes that you ve installed your IIS server and configured its CGI-BIN directory (usually the scripts subdirectory under your install directory). 1 Start the Microsoft Console Manager. From the Windows Start menu, select Windows NT Option Pack -> Microsoft Internet Information Server -> Internet Service Manager. 2 Right-click on the cgi alias and select Properties. The CGI Properties dialog appears. 3 Click the Configuration button. 104

116 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge The Application Configuration dialog appears. 4 Click the Add button. The Add/Edit Application Extension Mapping dialog appears. 5 Click Browse... The Open dialog appears. 6 Select All Files from the Files of Type menu at the bottom of the dialog. 7 Locate the HAHTsiteInstallDir\cgibin directory, and select the file, hsrunisa.dll. 105

117 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge 8 Click the Open button. The path to hsrunisa.dll is added to the Executable field in the Add/Edit Application Extension Mapping dialog. 9 Type.hse in the Extension field. 10 Click OK to add the mapping. 11 Click OK in the Application Configuration dialog. 12 Click OK in the Properties dialog. Your CGI alias is now set up to use ISAPI when communicating with the HAHTsite Application Server. Setting Up the Oracle Web Application Server This procedure assumes you've installed and have some familiarity with the Oracle Web Application Server (Revision 2.1 or higher). 106

118 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge 1 Copy the following files into the ows (Oracle Web Server) lib directory: Windows NT hsrunora.dll, hsmsgs40.dll Solaris hsrunora.so, hsmsgs40.en_us 2 Use the Oracle WebServer Manager to configure hsrun as an Oracle Web Application Server Cartridge in the Oracle Web Request Broker. Go to the Web Request Broker Administration page of the Oracle WebServer Manager and create a new Cartridge setting the parameters as follows: Set Application Name to HSRUNORA or whatever name you'd like. Set the Object Path to the path of the hsrunora.dll (or.so) file as copied in Step 1. Set the Entry Point name to hsrun_entry. Set the Thread Model to P for Process. Take the default values for the Min and Max number of Cartridge instances (or customize these values if you would like). 3 Create a virtual path, /hsrunora, that points to the directory to which you copied the files in Step 1. 4 Use the Web Server Utility (WSUtil) to add an hsrun entry for the Oracle version of hsrun by choosing Oracle Web Request Broker Cartridge for Web Server Type. The Browse URL should not include an alias such as cgibin. 5 Create a site that includes the hsrun configuration added in Step 3, and publish your application to that site. Configuring the Administrator as an NSAPI, ISAPI, or Oracle application By default, the HAHTsite Administrator utility runs as a CGI application. If your site uses an NSAPI, ISAPI, or Oracle Cartridge Web server, you can improve Administrator performance by configuring the Application Server to use the same version of hsrun as other applications. Here s how. (If you have a distributed configuration, perform this procedure on the control host.) 1 Configure the Application Server for an NSAPI, ISAPI, or Oracle Web server as explained previously. 107

119 Appendix A: Setting up NSAPI, ISAPI, and the Oracle Cartridge 2 Go to the /hsadmin subdirectory of your Web server s document tree. 3 Make a backup copy of hsadmin.html. (Should something go wrong, revert to the backup file.) 4 Open hsadmin.html and replace hsrun.exe with either: hsrun.hse (NSAPI or ISAPI) hsrunora (Oracle Cartridge) 5 Save and exit. 108