PreviousIntroduction to the World-Wide Web

Appendix B: Deployment and Debugging Examples

This appendix consists of a set of worked examples for debugging and deployment of NetExpress developed applications on different Web servers.

B.1 Overview

This appendix contains some worked examples, showing you how to deploy and debug one of the sample applications supplied with NetExpress on different Web servers. It is a supplement to the information in the chapter Deploying Your Application.

Even if the Web server you want to use is not covered in this chapter, the general principles are the same on all servers, and following through one of the worked examples might be helpful.

B.1.1 ISAPI Deployment on Microsoft Internet Server

This section contains a worked example which shows you how to deploy one of the sample Form Designer applications included in NetExpress. The example shows you how to:

You can take a simpler route when deploying applications. For example, if you used the default NetExpress Web share names, you wouldn't need to modify the share names used by the application. And if you didn't want to use ISAPI or the shared run-time, you wouldn't need to rebuild the application.

This example shows you how to deploy the one of the sample applications included with NetExpress as an ISAPI on Microsoft Internet Server.

B.1.1.1 Setup the Web Shares on Internet Server

In this section you create separate Web shares for all the parts of your application.

  1. Use the Windows Explorer to create a new folder, called netxapps.

  2. Create four subfolders of netxapps:

  3. Start the Internet Service Manager.

  4. Double-click on the WWW process in the Microsoft Internet Service Manager window.

  5. Click the Directories tab on the WWW Service Properties dialog box.

  6. Create a new Web share, nx-bin, for storing the binary files:

    1. Click the Add button.

    2. Enter x:\netxapps\nx-bin in the Directory field, where x is the drive you created the folder in step 1.

    3. Enter nx-bin in the Alias field.

    4. Set the Access properties to Execute only (uncheck the Read checkbox and check the Execute checkbox).

    5. Click the OK button.

  7. Create two more shares, both with Read permission only:

B.1.1.2 Create a Deployable Version of the Application

First copy the application sources into a deployment directory on your development machine.

  1. Change the Action property on the input form:

    1. Right-click on bevord_h.htm in the left-hand pane of the Project window, and click Edit on the context menu.

    2. Select the form on the page, click the Action property, and amend it to read: 
      /nx-bin/bev_h.dll

  2. Save bevord_h.htm, and quit Form designer.

Rebuild the application as an ISAPI:

  1. Change the executable file from an .exe to a .dll:

    1. Right-click on bev_h.exe in the left-hand pane of the Project window, and click Remove from Build Type on the context menu.

    2. On the Remove from Build Structure dialog, uncheck Remove the whole build structure, and select Remove this target from all build types, then click the Delete button.

    3. Right-click on bev_h.obj in the left-hand pane of the Project window, and click Package Selected Files, Dynamic Link Library on the context menu.

    4. Click the Create button on the Define New Dynamic Link Library dialog box.

  2. Change the Build Settings for the program:

    1. Right-click on bev_h.dll in the left-hand pane of the Project window, and click Build Settings on the context menu.

    2. Click the Link tab, and select the Shared and Multi-threaded radio buttons, and make sure the Dynamic checkbox is checked. .

    3. Click the Close button.

  3. Add a SET statement to compile this program for ISAPI:

    1. Right-click on bev_h.cbl in the left-hand pane of the Project window, and click Edit on the context menu.

    2. Add the following statement to the top of the program, after the $SET PREPROCESS directive (preprocessor directives must be in the first SET statement in a program): 
      $set webserver(isapi) case reentrant(2)

      The $ character must be in column 7.

    3. Save the changes and close the file.

  4. Rebuild the program.

B.1.1.3 Deploy the application

You can now deploy the application on the Web server:

  1. Copy the .dll file to x:\netxapps\nx-bin
  2. Copy bevord_h.htm and bevsum_h.htm to x:\netxapps\nx-html

Now run the application:

B.2 Debugging on Different Web Servers

The next three subsections are worked examples showing you how to animate one of the supplied example programs on different Web servers. The examples show you how to:

All of these examples were written using Windows NT Server as the operating system.

B.2.1 Animating a CGI on Microsoft Internet Server

The instructions below show you how to animate the HTML beverage application in NetExpress, using Microsoft Internet Server running on Windows NT Server.

To reconfigure Internet Server:

  1. Start the Microsoft Internet Service Manager.

  2. Select the WWW service and click Service Properties on the Properties menu to display the WWW Service Properties dialog box.

  3. On the Service tab, deselect the Allow Anonymous checkbox.

Note: This forces users accessing this Web server from other machines to supply a password and user name. You need to disallow anonymous logons so that the Web server has sufficient permission to run the animator.

Depending on how your operating system and Web server have been set up, you may also have to select either the NT Challenge/Response, or Basic (Clear Text) check box. Use NT Challenge/Response if your Web browser is Microsoft Internet Explorer; Basic if your Web browser is Netscape Navigator.

Do this if after following these instructions your CGI runs, but doesn't animate.

  1. Click the directories tab on the WWW Service Properties dialog box.

  2. Remove any existing COBOL and CGI-BIN shares (click on share and click Remove button).

  3. Add a share for COBOL, pointing to the source directory for the application:

    1. Click the Add button to display the Directory Properties dialog box.

    2. In the Directory field, enter: 
      x:\netexpress\base\demo\bevord_h

      where x: is the drive where you installed NetExpress.

    3. In the Alias field, enter: 
      COBOL
    4. Set the Access permissions to Read.

    5. Click OK.

  4. Add a share for CGI-BIN, pointing to the source directory for the application:

    1. Click the Add button to display the Directory Properties dialog box.

    2. In the Directory field, enter: 
      x:\netexpress\base\demo\bevord_h\debug

      where x: is the drive where you installed NetExpress. If you haven't built this project before, this directory won't yet exist, causing a server error when you apply these changes. If this is the case, use Windows Explorer to create a debug folder in the location given above, before you click OK below to apply these changes.

    3. In the Alias field, enter: 
      CGI-BIN
    4. Set the Access permissions to Execute.

    5. Click the OK button.

  5. Click OK to apply the changes to the Web server.

Rebuild and animate the application:

  1. Start NetExpress and load the bevord_h.app demo.

  2. Reconfigure NetExpress not to use Solo:

    1. Click Execute on the Options menu.

    2. Deselect Use the Solo Webserver for CGI projects checkbox.

    3. Click the OK button.

  3. Change the URL to start the application from the one used by Solo to the one needed by the Web server:

    1. Click Properties on the Project menu.

    2. Change the contents of the Start Animating At field to: 
      http://servername/COBOL/bevord_h.htm

      where servername is the name you use to access this Web server.

    3. Click the OK button.

  4. Click Rebuild on the Project menu to build the application.

  5. Click Start Animating on the Animate menu to run the application.

  6. Click the Brew it! button on your Web browser, to run the CGI. This starts the animator.

B.2.2 Animating an ISAPI Program on Microsoft Internet Server

The instructions below show you how to animate an ISAPI version of the HTML beverage application in NetExpress, using Microsoft Internet Server V3.0 running on Windows NT. This is split into the following stages:

To configure the Web server:

  1. Start the Microsoft Internet Service Manager.

  2. Select the WWW service and click Service Properties on the Properties menu to display the WWW Service Properties dialog box.
  3. On the Service tab, deselect the Allow Anonymous checkbox.

    This disallows anonymous logons; it means that users attempting to access this Web server from another machine must supply a user name and password. You need to do this or the Web server is unable to start the NetExpress debugger.

    Depending on how your operating system and Web server have been set up, you may also have to select either the NT Challenge/Response, or Basic (Clear Text) check box. Use NT Challenge/Response if your Web browser is Microsoft Internet Explorer; Basic if your Web browser is Netscape Navigator.

    Do this if after following these instructions your CGI runs, but doesn't animate.

  4. Click the Directories tab on the WWW Service Properties dialog box.

  5. Remove any existing COBOL and CGI-BIN shares (click on share and click Remove button).

  6. Set up the NetExpress source directory as a Web share named COBOL:

    1. Click the Add button to display the Directory Properties dialog box.

    2. In the Directory field, enter: 
      x:\netexpress\base\demo\bevord_h

      where x: is the drive where you installed NetExpress.

    3. In the Alias field, enter: 
      COBOL
    4. Set the Access permissions to Read.

    5. Click the Apply button.

  7. Set up the NetExpress executable directory as a Web share named CGI-BIN:

    1. If you haven't built this project before the executable directory won't yet exist. Use Windows Explorer to browse folder x:\netexpress\base\demo\bevord_h\ (where x: is the drive where you installed NetExpress). If this does not contain a subfolder, named debug, use Windows Explorer to create a new folder named debug.

    2. Click the Add button to display the Directory Properties dialog box.

    3. In the Directory field, enter: 
      x:\netexpress\base\demo\bevord_h\debug

    4. In the Alias field, enter: 
      COBOL
    5. Set the Access permissions to Read.

    6. Click the Apply button.

To rebuild the program as an ISAPI .dll:

  1. Load the project bevord_h.app into the NetExpres IDE.

  2. Change the project build information to create bev_h.dll instead of bev_h.exe:

    1. Right-click on bev_h.exe in the left-hand pane of the Project window, and click Remove from Build Type on the context menu.

    2. On the Remove from Build Structure dialog, uncheck Remove the whole build structure, and select Remove this target from all build types, then click the Delete button.

    3. Right-click on bev_h.obj in the left-hand pane of the Project window, and click Package Selected Files, Dynamic Link Library on the context menu.

    4. Click the Create button on the Define New Dynamic Link Library dialog box to add bev_h.dll to the project list.

  3. Change the Build Settings for the .dll file to use the shared multi-threaded run-time system:

    1. Right-click on bev_h.dll file on the left-hand pane of the NetExpress Project window, and click Build Settings on the context menu.

    2. Click the Link tab.

    3. Click the Shared and Multi-Threaded radio buttons, and make sure the Dynamic checkbox is checked.

    4. Click the Close button.

  4. Add compiler directives to build this program as an ISAPI. Add the following statement to the top of bev_h.cbl, following the $SET statement which is already there: 
    $set webserver(isapi) case reentrant(2)

    The dollar sign ($) must be in column 7 of your source code.

  5. Add the statement to start the debugger when the program is executed:

    1. Double-click bev_h.cbl in the project window to load it into a text edit pane.

    2. Locate the program's Procedure Division.

    3. Add the following statement to the start of the Procedure Division: 
      call "CBL_DEBUGBREAK"

  6. Click Rebuild on the Project menu to build the ISAPI program.

  7. Modify the input form's Action property so that it calls bev_h.dll instead of bev_h.exe:

    1. Double-click on bevord_h.htm to start Form Designer and load the page.

    2. Select the form, click on the Action property and change it to: 
      CGI-BIN/bev_h.dll
    3. Save the page and quit Form Designer.

  8. Quit the NetExpress IDE.

Now you can animate the program:

  1. Start your Web browser.

  2. Enter the URL for the first page in the application: 
    http://machinename/cobol/bevord_h.htm

    where machinename is the name of your machine used by the Web server.

  3. Click the Brew It! button on the form.

    A dialog box appears, asking you whether or not you want to debug the application.

  4. Click the Yes button.

    The IDY File Error dialog box appears, because the debugger does not know where to find the .idy files needed for debugging.

  5. Click the Browse button, and use the Open dialog box to locate bev_h.idy file for the program. NetExpress creates this in the same directory as the executable files for your application.

    You can now debug the program.

If you stop the debugger, you also stop the Web server and must restart it. When you step through an exit program statement, the NetExpress IDE remains open, but the debugger stops operating until you execute the program again. Because the server keeps the .dll file open while running, you have to shut down the Web server to rebuild it.

B.2.3 Animating an NSAPI Program

The instructions below show you how to animate an NSAPI version of the HTML beverage application in NetExpress, using Netscape FastTrack running on Windows NT. The process is split into the following stages:

To configure the server:

  1. Click Netscape, Administer Netscape Servers on the Windows Start menu.

  2. Add a COBOL share to the Web server:

    1. Click Content Mgmt in the top frame.

    2. Click Additional Document Directories in the left-hand frame.

      This displays the Additional Document Directories form.

    3. Enter COBOL in the URL field

    4. Enter the full path to your project's source code directory in the Alias field.

    5. Click the OK button.

      This displays the Save and Apply changes page.

    6. Click the Save and Apply button on the Save and Apply page.

    Note: For NSAPI applications, you don't need to add a CGI-BIN share for the NSAPI program to be found. NSAPI programs are loaded when the Web server starts, using an explicit path set up in the server configuration files.

  3. Modify the server's configuration files to load your NSAPI program, and to define a new MIME type for it.
    1. Locate the Netscape server file obj.conf, and load it into a text editor.

      This file is in \netscape\server\httpd-name\config where name is the server name for your machine.

    2. Add the following line to load your server-side program when the server is started: 
      Init fn="load-modules" shlib="x:/netexpress/base/demo/debug/bev_h.dll"
         funcs="beverage"

      where x is the drive where you installed NetExpress.

    3. Between the <OBJECT name="default"> and <OBJECT> tags, add the following line to associate the entry-point for your program with a new MIME type, which we will call bev: 
      Service fn="beverage" method="(GET|POST)" type="magnus-internal/bev"

  4. Edit mime.types (this is in the same directory as obj.conf) to associate the new MIME type you have just defined with an extension. Add the following line to mime.types: Define the extension for magnus-internal/bev as cobolcgi. 
    type=magnus-internal/bev exts=cobolcgi

    A Browser request for beverage.cobolcgi will now start bev_h.dll running.

  5. Click the Apply button on the top frame of the Netscape Server Administration browser.

    This displays the Apply Changes field.

  6. Click the Load Configuration Files button.

To rebuild the program as an NSAPI:

  1. Load the project bevord_h.app into the NetExpres IDE.

  2. Change the project build information to create bev_h.dll instead of bev_h.exe:

    1. Right-click on bev_h.exe in the left-hand pane of the Project window, and click Remove from Build Type on the context menu.

    2. On the Remove from Build Structure dialog, uncheck Remove the whole build structure, and select Remove this target from all build types, then click the Delete button.

    3. Right-click on bev_h.obj in the left-hand pane of the Project window, and click Package Selected Files, Dynamic Link Library on the context menu.

    4. Click the Create button on the Define New Dynamic Link Library dialog box to add bev_h.dll to the project list.

  3. Change the Build Settings for the program to use the shared multi-threaded run-time system, and to link in the modules and libraries needed for NSAPI:

    1. Right-click on bev_h.dll file on the left-hand pane of the NetExpress Project window, and click Build Settings on the context menu.

    2. Click the Link tab.

    3. Click the Shared and Multi-Threaded radio buttons, and make sure the Dynamic checkbox is checked.

    4. Select Advanced from the Category drop-down.

    5. Type accnsapi.obj in the Link with these OBJ's field.

      Three different versions of this file are supplied - you need to use different versions to go with different Netscape Servers.

      • FastTrack

        The default version of accnsapi.obj is set up for FastTrack, so you don't need to change it.

      • Commerce Server

        Rename the default version of accnsapi.obj (in your \netexpress\base\lib directory) so that you can keep a backup, and then rename accnscs.obj toaccnsapi.obj .

      • Enterprise Server

        Rename the default version of accnsapi.obj (in your \netexpress\base\lib directory) so that you can keep a backup, and then rename accenter.obj to accnsapi.obj .

    6. Type libhttpd.lib in the Link with these LIB's field (you would use httpd.lib for Commerce Server).

  4. Copy libhttpd.lib to a location where it can be found by the NetExpress compiler.

    This file is in a subdirectory of the one your Netscape server software is installed: \server\nsapi\examples. Copy libhttpd.lib from here to x:\netexpress\base\bin (where x: is the drive where you installed NetExpress).

  5. Add compiler directives to build this program as an NSAPI. Add the following statement to the top of bev_h.cbl, following the $SET statement which is already there: 
    $set webserver(nsapi,beverage) case reentrant(2)

    The dollar sign ($) must be in column 7 of your source code.

  6. Add the statement to start the debugger when the program is executed:

    1. Double-click bev_h.cbl in the project window to load it into a text edit pane.

    2. Locate the program's Procedure Division.

    3. Add the following statement to the start of the Procedure Division: 
      call "CBL_DEBUGBREAK"

  7. Click Rebuild on the Project menu to build the ISAPI program.

  8. Modify the input form's Action property so that it calls bev_h.bdll instead of bev_h.exe (we defined .bdll as the extension for a new MIME type when setting up the server):

    1. Double-click on bevord_h.htm to start Form Designer and load the page.

    2. Select the form, click on the Action property and change it to: 
      beverage.cobolcgi
    3. Save the form and quit Form Designer.

  9. Quit the NetExpress IDE.

  10. Load the program into the Netscape server. To do this, shut the server down and restart it from Netscape Server Administration.

Now you can animate the program:

  1. Start your Web browser.

  2. Enter the URL for the first page in the application: 
    http://machinename/COBOL/bevord_h.htm

    where machinename is the name of your machine used by the Web server.

  3. Click the Brew It! button on the form.

    A dialog box appears, asking you whether or not you want to debug the application.

  4. Click the Yes button.

    The IDY File Error dialog box appears, because the debugger does not know where to find the .idy files needed for debugging.

  5. Click the Browse button, and use the Open dialog box to locate bev_h.idy file for the program. NetExpress creates this in the same directory as the executable files for your application.

    You can now debug the program.

If you stop the debugger, you also stop the Web server and must restart it. When you step through an EXIT PROGRAM statement, the NetExpress IDE remains open, but the debugger stops operating until you execute the program again. Because the server keeps the .dll file open while running, you have to shut down the Web server to rebuild it.

Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousIntroduction to the World-Wide Web