Installing Duwamish Books, Phase 4

Brad Deputy
Microsoft Developer Network

August 1999

Summary: Provides instructions for setting up Phase 4 of the Duwamish Books sample application. (18 printed pages) Covers:

Introduction
Preparing SQL Server 7.0 Installation
Installing English Query
Before Starting the Setup Application
Installing the Database Layer
Installing the Data Access Layer
Installing the Business Logic Layer
Installing the Workflow Layer
"Smoke Testing" the Installation of Duwamish Books, Phase 4
Summary

Note   See "Duwamish Books, Phase 4 Setup and Source Code" to download the Setup files for Phase 4.

Introduction

This article describes the requirements and procedures for installing Duwamish Books, Phase 4 onto one or more servers.

As in Phase 3.5, Duwamish Books, Phase 4 middle-tier components are distributed using the Distributed Component Object Model (DCOM) and Microsoft® Transaction Server (MTS) technologies, enabling the distribution of components and transactions across multiple servers.

The Setup program installs and configures the following four component layers on up to four target servers (one server per layer):

System Requirements

Several prerequisites exist for the servers that host Duwamish Books, Phase 4.

The BLL and DAL servers require the following software:

The WFL requires the components just listed, plus:

The Database Layer only needs:

Note   We successfully installed Duwamish Books, Phase 4 on both Windows® 2000 Server Beta 3 and RC1 and on Windows NT 4.0 Server with Service Pack 5, but neither installation has been a focus of our testing.

Preparing SQL Server 7.0 Installation

If you plan to use an existing SQL Server 7.0 installation, you can use SQL Server's default character set, sort order, and Unicode collation settings to run Duwamish—it's not necessary to reconfigure SQL server for the custom settings. (If you are interested in reconfiguring the default character set, sort order, and Unicode collation settings for an existing installation, see http://msdn.microsoft.com/library/psdk/sql/2_002_5.htm).

To configure your custom settings in a new SQL Server 7.0 installation

If you are performing a new SQL Server installation, you can configure the custom settings from the SQL Server 7.0 Setup application, using the Character Set/Sort Order/Unicode Collation dialog box (as shown in Figure 1, and described next).

Figure 1. SQL Server 7.0 Character Set/Sort Order/Unicode Collation dialog box

  1. Click 850 Multilingual in the Character Set list. This will enable SQL Server to encode and decode Unicode characters displayed throughout Duwamish Books, Phase 4. If the server is operating with a code page that differs from the code pages used by the client programs, there will be code page translation issues. For more information on code pages and sort orders in SQL Server 7.0, see http://msdn.microsoft.com/library/psdk/sql/8_ar_da_10.htm.

  2. Click Dictionary order, case-sensitive in the Sort Order list.

SQL Server Client Access Licence issue

Another SQL Server consideration regards the licensing agreement utilized for the Duwamish Books, Phase 4 Web site. The easiest way to deal with this is by purchasing an Internet Connector License for each processor on the Database layer server (which will provide an unlimited number of concurrent connections). However, the Internet Connector License is not available for intranet deployment. The next easiest licensing model available for intranet deployment is per-server licensing. Unfortunately, per-server licensing is illegal for Web applications that employ database connection pooling (which Duwamish Books does courtesy of ADO). This means that per-seat licensing is the only licensing model available for intranet deployment. The easiest way to ensure you do not exceed the number of CAL purchased for your per-seat SQL Server installation in the Database layer is by limiting the maximum number of IIS connections on the Workflow Layer server. To do this, follow these steps:

  1. From the Start menu, select Programs. Select Windows NT 4.0 Option Pack, select Microsoft Internet Information Server, and then click Internet Service Manager. Open the Internet Information Server tree in the left-pane.

    Note   The location may vary if you do not accept Windows NT 4.0 Option Pack as the default during installation.

  2. Right-Click Default Web Site, click Properties, and then click the Web Site tab.

  3. On the Web Site tab, enter the number of CAL available into the Connections, Limited to: field.

Note   We ran into a recurring problem during performance testing, wherein warning messages would pop up in the middle of the long-running tests, destroying the test results and indicating the need to create additional CAL. We recommend that you confront this problem early, so as to save yourself time and effort later on.

For more information about licensing strategies, refer to http://www.microsoft.com/backoffice/basics/Licensing.htm and http://www.microsoft.com/sql/70/gen/pricing.htm.

Installing English Query

To install English Query, run the autorun.exe program from your SQL Server 7.0 install disc. Select Install SQL Server 7.0 Components and then select English Query.

Before Starting the Setup Application

Before beginning Setup you need to decide whether Duwamish Books, Phase 4 will be configured for one server or multiple servers. Installation onto a single server makes sense for the purpose of exploring the capabilities and general functionality of the application. On the other hand, for enhanced performance and scalability, the components can be installed onto many different servers. If you are interested in reproducing our scalability results, refer to "Performance Testing a Scalable Application" for setup details on the two-server configuration we used in our performance testing.

In order to facilitate installing each layer on a different server, the Setup application must run separately for each layer. For example, in order to install all the Duwamish Books, Phase 4 layers onto a single server, the Setup application is run once per layer.

Before beginning, the Duwamish Books, Phase 4 Setup files (see "Duwamish Books, Phase 4 Setup and Source Code") should be downloaded into a local "setup folder." Where the following instructions refer to running the Setup application, it is assumed the setup folder containing the Setup application is either physically located on each target server, or is available through a shared network location.

Note   You must rerun the Duwamish Setup application for each phase of the installation.

Installing the Database Layer

Choose the server where the Database layer will be installed and apply the following procedures on that server to install the Database layer.

Installing the Database Scripts

Run the Setup application to start the database script installation process. Setup begins by copying several temporary files. When the introductory dialog box appears, click OK and read the license agreement. You must "Agree" before continuing. Next, click the Setup button to start the main Setup dialog box (Figure 2).

Figure 2. Duwamish Books, Phase 4 main Setup dialog box (Install Database Scripts tab)

Click the Install Database Scripts button to copy the SQL scripts and the MS-DOS batch file that is used to populate the database.

Creating the Database

The SQL Server 7.0 Enterprise Manager application is used to create the Duwamish Books, Phase 4 database.

  1. From the Start menu, select Programs. Select Microsoft SQL Server 7.0, and then click Enterprise Manager.

    Note   The location may vary if you do not accept Microsoft SQL Server 7.0 as the default location during the SQL Server 7.0 installation.

  2. Right-click the Databases folder and then click New Databases...

  3. Create a new database called "DbP4Data" (note the database name is case sensitive) and accept the default values.

Populating the Database

This step populates the DbP4Data database with the various tables utilized by Duwamish Books, Phase 4. Refer to "Duwamish Books, Phase 4 Database Schema" for more information about the Duwamish Books, Phase 4 database structure.

An MS-DOS Command Prompt window should be started to run the MS-DOS format batch file that is provided with the database scripts.

  1. From the Start menu, click Run. Type "cmd" in the Open field of the Run dialog box to start a Command Prompt window.

  2. In the Command Prompt window, change to the Duwamish Books, Phase 4 directory that contains the database script files. (If you accepted the default installation directory for Duwamish Books, Phase 4 the script files will be located in the "C:\Program Files\Duwamish\phase4.0\database\scripts" folder, as shown in Figure 3.)

Figure 3. Command Prompt window showing Duwamish Books, Phase 4 database scripts default location

  1. In the Command Prompt window, type "build DbP4Data" (note the database name is case sensitive) and press ENTER to begin populating the Duwamish Books, Phase 4 database. This may take several minutes, depending on the speed and available memory of the Database layer server. When the scripts are finished executing (indicated by the blinking cursor on a new command prompt line), type "exit" in the Command Prompt window and press ENTER to close the window.

Setting Services to Automatic Startup

The Microsoft Distributed Transaction Coordinator (MSDTC) and Remote Procedure Call (RPC) Locator services must be configured to start automatically. These services may already be set to automatic startup. If so, you can ignore the following procedure.

To set the MSDTC and RPC Locater to automatic startup

  1. Click the Services icon in Control Panel to display the Services dialog box, and select MSDTC from the drop-down list.

  2. Click the Startup button, and then click Automatic to set the MSDTC service to start up automatically every time the server is restarted.

  3. Repeat steps 1 and 2 for the RPC Locator service.

  4. Restart the server(s) to start the MSDTC and RPC Locator services.

Installing the Data Access Layer

Choose the server where the DAL will be installed and apply the following steps on that server:

  1. From the main Setup dialog box (see Figure 2), click the Install Middle-Tier Components tab.

  2. Enter the name of the server that contains the Database layer in the Database Server Name field. (If Duwamish Books, Phase 4 is being installed onto a single server configuration, this field can be left blank.) If the default database name was used when installing the Database layer, the Database Name field may be left to its default value, "DbP4Data," otherwise use the Duwamish Books, Phase 4 database name created for the Database layer.

  3. Click the Install/Configure Data Access Layer button to install the files for the DAL.

Installing the Business Logic Layer

Choose the server where the BLL will be installed and apply the following steps on that server:

  1. From the main Setup dialog box (see Figure 2), click the Install Middle-Tier Components tab.

  2. Enter the name of the server where the DAL (not the BLL) was installed in the DAL Server Name field. (If Duwamish Books, Phase 4 is being installed onto a single server configuration, this field should be left blank.)

  3. Click the Install/Configure Business Logic Layer button to install the files for the BLL.

Installing the Workflow Layer

The Workflow Layer consists of the Workflow component and the Web components. Choose the server where the Workflow component and Web components will be installed and apply the following procedures on that server. This server will host the Duwamish Books, Phase 4 Web site.

Installing the Workflow Component

  1. From the main Setup dialog box (see Figure 2), click the Install Middle-Tier Components tab.

  2. Enter the name of the server where the BLL (not the WFL) was installed into the BLL Server Name field. (If Duwamish Books, Phase 4 is being installed onto a single server configuration, this field should be left blank.)

  3. Click the Install/Configure Workflow Layer button to start the install procedure.

Installing the Web Components

The Web components must be installed on the same server where the Workflow component was just installed.

  1. From the main Setup dialog box, click the Install Auxiliary Files tab (see Figure 4).

Figure 4. Install Auxiliary Files tab of Duwamish Books, Phase 4 main Setup dialog box

  1. Click the Install Web Components button to begin installing the Web and Cache component files. Due to the large number of files being installed, this step may take several minutes to complete.

Modifying the IIS Configuration of the Web Server

The following instructions should be applied on the Web server where the Workflow component and Web components were installed. The first part of this step (applying the security settings) is optional, whereas the second part (creating the virtual directories) is required.

Applying security settings to the Duwamish Books, Phase 4 Web pages

In order for the Duwamish Books, Phase 4 Web pages to function correctly when a user is not currently logged on to the Web server, the default security settings for the Duwamish Books, Phase 4 Web pages must be modified. The easiest way to accomplish this is by modifying the security settings for all the default Web pages, as described next. If it is preferable to apply these settings only to the Duwamish Web pages, skip directly to the section on "Creating the Duwamish Books, Phase 4 virtual directories," and then apply the security settings to each Duwamish Books, Phase 4 virtual directory.

To be clear, if a user with sufficient security credentials will always be logged on to the Duwamish Web server, it is not necessary to apply these security settings. The decision made at this juncture will determine whether the steps described later in the section "Optional Microsoft Transaction Server (MTS) settings" should also be applied.

  1. From the Start menu, select Windows NT 4.0 Option Pack (the default location offered during installation). Select Microsoft Internet Information Server, and then click Internet Service Manager. Open the Internet Information Server tree in the left-pane.

  2. Right-click Default Web Site and then click Properties.

  3. Click the Directory Security tab.

  4. Click the Edit button located under the "Anonymous Access and Authentication Control" heading to open the Authentication Methods dialog box.

  5. In the Authentication Methods dialog box, click the Edit button adjacent to the Allow Anonymous Access check box to open the Anonymous User Account dialog box.

  6. In the Anonymous User Account dialog box, enter a user name with sufficient privileges in the Username field, with DOMAIN first. For example, "brian" in the "COMPANY" domain must appear as "COMPANY\brian" (note these names are case sensitive). The privileges required of this user account include the ability to log on locally to the Web server, read-access permission to all files and folders in the Duwamish Books, Phase 4 Web pages, and the ability to execute files and scripts. (These permissions are included by default for all users included in the "Windows Guests user group.") For additional information, refer to the "About Authentication" topic in the IIS documentation (navigate to http://localhost/iishelp/ on the Web server).

  7. In the Anonymous User Account dialog box, enter the password for the indicated user name in the Password field and click OK. This action will open a Confirm Password dialog box. (Note that the Enable Automatic Password Synchronization check box should be cleared.)

  8. In the Confirm Password dialog box, reenter the password indicated in the Password field of the Anonymous User Account dialog box and click OK to return to the Authentication Methods dialog box.

  9. Click OK in the Authentication Methods dialog box to return to the Default Web Site Properties dialog box.

  10. Click OK in the Default Web Site Properties dialog box to return to Internet Information Manager.

Creating the Duwamish Books, Phase 4 virtual directories

  1. In the Internet Information Server, right-click Default Web Site, click New, and then click Virtual Directory to start the New Virtual Directory Wizard.

  2. Referring to the Alias and Directory values indicated in Table 1, use the New Virtual Directory Wizard to create each of the seven virtual directories in Duwamish Books, Phase 4. For each virtual directory, when asked to supply access permissions for these directories, check the Allow Execute Access check box (this check box will be cleared by default).

    Table 1. Duwamish Books, Phase 4 Virtual Directories
    Alias Directory (using default Web components location)
    D4_1 C:\Program Files\Duwamish\phase4.0\clients\web\app1
    D4_2 C:\Program Files\Duwamish\phase4.0\clients\web\app2
    D4_3 C:\Program Files\Duwamish\phase4.0\clients\web\app3
    D4_Graphics C:\Program Files\Duwamish\phase4.0\clients\web\graphics
    D4_Common C:\Program Files\Duwamish\phase4.0\clients\web\common
    D4_Payment C:\Program Files\Duwamish\phase4.0\clients\web\payment
    D4_Entry C:\Program Files\Duwamish\phase4.0\clients\web\entry

Optional Microsoft Transaction Server (MTS) Settings

Setup initializes the Duwamish Books, Phase 4 MTS packages for access by the "interactive user." This means a user with sufficient privileges must be logged on to the Duwamish Books, Phase 4 Web server in order for the MTS transactions, and therefore Duwamish Books, Phase 4 itself, to function properly.

If it is not desirable to require that an authorized user be logged on to the Duwamish Web server at all times, the steps described earlier in the section "Applying security settings to the Duwamish Books, Phase 4 Webs site" should be taken, followed by the steps to reconfigure the MTS packages for access by the security credentials of the indicated user, listed next.

Reconfiguring the MTS packages for security credentials

If you choose to reconfigure the MTS packages, you are required to do so on the WFL, BLL and DAL server(s). The following steps will modify the BLL package on the BLL server. These same steps should be applied for the "D4VbWFL" package on the WFL server and the "D4VbDAL" package on the DAL server.

  1. From the Start menu, select Programs. Select Windows NT 4.0 Option Pack (the default location offered during installation), select Microsoft Transaction Server, and then click Transaction Server Explorer. This will open the Microsoft Management Console.

  2. From the Console Root tree, open the Microsoft Transaction Server tree, then the Computers tree, and finally the Packages Installed tree.

  3. Right-click the "D4VbBLL" package and then click Properties.

  4. On the Identity tab, click the This user: option button and enter the same user account (excluding the DOMAIN) and password used in the procedure for applying the security settings discussed earlier.

  5. Restart the BLL server for the new settings. (If multiple layers are installed on a single server you can successfully change all the packages on that server before restarting.)

"Smoke Testing" the Installation of Duwamish Books, Phase 4

Here are some quick tests that can determine whether Duwamish Books, Phase 4 has been successfully installed.

Testing the BLL, DAL, and Database Layer

The "D4test.exe" smoke test application, located in the setup folder, can be used to test the DAL and BLL of Duwamish Books, Phase 4. A successful outcome of D4test.exe indicates the BLL and DAL have been installed correctly, and may be expected to function as required by the WFL.

Duwamish Books, Phase 4 is designed using a layered Windows DNA paradigm (see the introduction to the article "Workflow Design for a Web Commerce Application" for a discussion on this), where the successful functioning of each application layer is dependent on the successful operation of any lower layers. Thus, the WFL cannot be expected to function correctly if the BLL is not functioning. Likewise, the BLL cannot be expected to function correctly if the DAL is not installed correctly. And, of course, the DAL cannot be expected to function correctly if the Database layer is not functioning correctly.

Follow these steps to run the D4test.exe application:

  1. Start the D4test.exe application.

    Referring to Figure 5, note the two list fields and the two buttons below the fields labeled Test the Business Logic Layer and Test the Data Access Layer. Both list fields should initially be empty.

Figure 5. D4test.exe (indicating a successful BLL and DAL installation)

  1. Click the button labeled Test the Data Access Layer and verify the list field located above the button becomes populated (as indicated in Figure 5). If an error message appears, or the list field remains empty, either the DAL or the Database layer has not been installed correctly. (Note that it may take several seconds for this test to complete.)

    If the DAL test was successful, proceed to the BLL test (step 3).

  2. Click the button labeled Test the Business Logic Layer and verify the list field above the button becomes populated (as indicated in Figure 5). If an error message appears, or the list field is not populated, the BLL has not been installed correctly.

Testing the WFL

Once the BLL, DAL, and Database layer have passed muster, it is time to test the WFL for successful installation. The WFL is accessed by the Duwamish Books, Phase 4 Web components, thus the methodology used to smoke the WFL installation is simply to visit a representative range of Duwamish Books, Phase 4 Web pages.

The following steps should be applied on each of the three client approaches, using a range of browsers as necessary. In this article I describe testing client approach 3 using Internet Explorer 5. For a complete smoke test, these steps should also be followed using Internet Explorer 4.x for client approach 2, as well as the full set of client browsers required for client approach 1. Refer to the article "Three Approaches for Three Client Types" for more information about the three client approaches used in Duwamish Books, Phase 4. The screen shots representing the third client approach should look similar for all client approaches.

To test client approach 3 with Internet Explorer 5

  1. Open an Internet Explorer 5 window and navigate to http://localhost/D4_3 (where "localhost" indicates the name of the Web server where the WFL and Web components are installed). Verify the page looks similar to Figure 6.

Figure 6. Default page

  1. Click Categories in the navigation bar at the top of the page and verify the root Categories page appears (see Figure 7). The first time the Categories page is navigated will take several seconds due to the startup time needed to instantiate the Cache component. The Chinese, Korean, and Japanese Unicode characters will only display correctly if the computer hosting the Internet Explorer 5 window has installed these character sets. For information on downloading available language packs, refer to http://www.microsoft.com/Windows/ie/intlhome.htm.

Figure 7. Categories page

  1. Click the "English" category, verify there is a single "Books" item available for selection under the "Category: English" title, and then click Books.

  2. Verify the following items are available for selection under the "Category: Books" title, and then click Anthropology.

    Anthropology

    Art

    Biography

    Business

    Computers

    Cookbooks

    Essays

    Fiction

    History

    Literature Critiques

    Mythology

    Philosophy

    Poetry & Plays

    Psychology

    Reference

    Science

    Sports

    Travel

    Dewey Decimal Category

  3. Verify the following items are available for selection under the title "Category: Anthropology."

    Cannibals and Kings

    African Genesis

    Forest People, The

    Beyond Freedom and Dignity

  4. Click Cannibals and Kings and verify the resulting page looks similar to Figure 8.

Figure 8. Cannibals and Kings Book (identical in all three approaches)

  1. Click Add to Shopping Cart and verify the resulting page looks similar to Figure 9.

Figure 9. Cannibals and Kings Book added to shopping cart

  1. Click Advanced Search in the navigation bar at the top of the page and verify the resulting page looks similar to Figure 10.

Figure 10. Advanced Search page

  1. Enter "Tom" in the Author Keyword Search field and click the Go button located immediately to the right.

  2. Verify the following items are available for selection under the title "Search Text: Tom", and click Hunt for Red October, The.

    Hunt for Red October, The

    Another Roadside Attraction

    Rosencrantz and Guildenstern are Dead

    Canada

    Painted Word, The

  3. Verify the "Hunt for Red October, The" book record is displayed and add it to the shopping cart.

  4. Verify both the "Cannibals and Kings" and "Hunt for Red October, The" books are included in the shopping cart.

  5. Return to the Advanced Search page, enter "What books are on France" in the Natural Language Search field and click the adjacent Go button. (Note that this search can take several seconds to complete due to the performance of English Query.)

  6. Verify the following items are available for selection under the title "Search Text: What books are on France", and click Napoleon.

    Old Regime and the French Revolution, The

    Napoleon

  7. Verify the "Napoleon" book record is displayed, and add it to the shopping cart.

  8. Verify the "Cannibals and Kings", "Hunt for Red October, The", and "Napoleon" books are all included in the shopping cart.

  9. Click Proceed to Checkout and verify the resulting page looks similar to Figure 11.

Figure 11. Checkout page with three items in Order Summary

  1. At this point you will either click Select an existing customer account if you have not already created a customer account, or click Create a new customer account and enter new account information into the subsequent pages.

  2. After creating a new customer account, or selecting an existing one, verify the "Shipping" and "Order Summary" information is correct, and click Continue to Payments Site.

  3. Enter the indicated billing information and click the Submit button.

  4. Verify the "Order," "Shipping," and "Order Summary" information matches previous pages.

Summary

This article provided detailed information necessary to install the Duwamish Books, Phase 4 components on the server configuration of your choice. Additional information was included to help ensure the installation was successful.

While we cannot promise to answer every query, if installation problems are encountered during or after Duwamish Books, Phase 4 Setup, please e-mail us at duwamish@microsoft.com with a detailed description of the problems you encountered, including any error information provided as well as the server configuration selected.