Chapter 13: Deployment and Debugging Examples

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

Overview

This appendix contains some worked examples, showing you how to deploy and debug one of the sample applications supplied with Net Express on different Web servers. It is a supplement to the information in the chapter Deploying Your CGI-based 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.

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 Net Express. The example shows you how to:

Set up new Web shares with different names to those of the Net Express defaults of COBOL and CGI-BIN
Modify your application to use the new Web share names
Rebuild the application as an ISAPI with the shared run-time
Copy the application to the Web server

You can take a simpler route when deploying applications. For example, if you use the default Net Express Web share names, you don't need to modify the share names used by the application. There is also no need to rebuild the application if you don't want to use ISAPI or the shared run-time, or if you created your application as an ISAPI using the Internet Application Wizard.

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

Setup the Web Shares on Internet Server

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

Use the Windows Explorer to create a new folder, called netxapps.
Create four subfolders of netxapps:
- nx-bin
- nx-html
- nx-images
Start the Internet Service Manager.
Double-click on the WWW process in the Microsoft Internet Service Manager window.
Click the Directories tab on the WWW Service Properties dialog box.
Create a new Web share, nx-bin, for storing the binary files:
1. Click Add.
2. Type x:\netxapps\nx-bin in Directory, where x is the drive you created the folder in step 1.
3. Type nx-bin in Alias.
4. Set the Access properties to Execute only (uncheck Read and check Execute).
5. Click OK.
Create two more shares, both with Read permission only:
- Alias nx-html, directory x:\netxapps\nx-html
- nx-img, directory x:\netxapps\nx-img

Create a Deployable Version of the Application

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

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
```
Save bevord_h.htm and quit Form designer.

If you created your application as an ISAPI using the Internet Application Wizard, it will already be built as an ISAPI and you should go to the section Deploy the Application. Otherwise you need to rebuild the application as an ISAPI:

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, select Remove this target from all build typesand click Delete.
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 Create on the Define New Dynamic Link Library dialog box.
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 Shared and Multi-threaded. Make sure that Dynamic is also checked.
3. Click Close.
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.
Rebuild the program.

Deploy the Application

You can now deploy the application on the Web server:

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

Now run the application:

Start a Web browser, and set the URL to:

http://machine.domain/nx-html/bevord_h.htm

Debugging on Different Web Servers

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

Debug a CGI on Microsoft Internet Server
Debug an ISAPI on Microsoft Internet Server
Debug an NSAPI on Netscape FastTrack

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

Debugging a CGI on Microsoft Internet Server

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

To reconfigure Internet Server:

Start the Microsoft Internet Service Manager.
Select the WWW service and click Properties > Service Properties to display the WWW Service Properties dialog box.
On the Service tab, deselect Allow Anonymous.

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 debugger.

Depending on how your operating system and Web server have been set up, you may also have to select either NT Challenge/Response, or Basic (Clear Text). 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 debug.

Click the directories tab on the WWW Service Properties dialog box.
Remove any existing COBOL and CGI-BIN shares (click on share and click Remove).
Add a share for COBOL, pointing to the source directory for the application:
1. Click Add to display the Directory Properties dialog box.
2. In Directory, type:
```
c:\Program Files\Micro Focus\Examples\Net Express IDE\bevord_h
```
  (If you didn't install Net Express to the default location, type the location you used instead of c:\Program Files.)
3. In Alias, type:
```
COBOL
```
4. Set the Access permissions to Read.
5. Click OK.
Add a share for CGI-BIN, pointing to the source directory for the application:
1. Click Add to display the Directory Properties dialog box.
2. In Directory, type:
```
c:\Program Files\Micro Focus\Examples\Net Express IDE\bevord_h\debug
```
  (If you didn't install Net Express to the default location, type the location you used instead of c:\Program Files.) 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 Alias, type:
```
CGI-BIN
```
4. Set the Access permissions to Execute.
5. Click OK.
Click OK to apply the changes to the Web server.

Rebuild and debug the application:

Start Net Express and load the bevord_h.app demo.
Reconfigure Net Express not to use Solo:
1. Click Options > Execute.
2. Deselect Use the Solo Webserver for CGI projects.
3. Click OK.
Change the URL to start the application from the one used by Solo to the one needed by the Web server:
1. Click Project > Properties.
2. Change the contents of Start Debugging At to:
```
http://servername/COBOL/bevord_h.htm
```
  where servername is the name you use to access this Web server.
3. Click OK.
Click Project > Rebuild to build the application.
Click Debug > Start Debugging to run the application.
Click Brew it! on your Web browser to run the CGI. This starts the debugger.

Debugging an ISAPI Program on Microsoft Internet Server

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

Configuring the Web server
Rebuilding the program as an ISAPI .dll
Debugging the program

To configure the Web server:

Start the Microsoft Internet Service Manager.
Select the WWW service and click Properties > Service Properties to display the WWW Service Properties dialog box.
On the Service tab, deselect Allow Anonymous.
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 Net Express 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 debug.
Click the Directories tab on the WWW Service Properties dialog box.
Remove any existing COBOL and CGI-BIN shares (click on share and click Remove).
Set up the Net Express source directory as a Web share named COBOL:
1. Click Add to display the Directory Properties dialog box.
2. In Directory type:
```
c:\Program Files\Micro Focus\Examples\Net Express IDE\bevord_h
```
  (If you didn't install Net Express to the default location, type the location you used instead of c:\Program Files.)
3. In Alias type:
```
COBOL
```
4. Set the Access permissions to Read.
5. Click Apply.
Set up the Net Express 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 Examples\Net Express IDE\bevord_h\. If this does not contain a subfolder, named debug, use Windows Explorer to create a new folder named debug.
2. Click Add to display the Directory Properties dialog box.
3. In Directory type:
```
c:\Program Files\Micro Focus\Examples\Net Express IDE\bevord_h\debug
```
  (If you didn't install Net Express to the default location, type the location you used instead of c:\Program Files.)
4. In Alias type:
```
COBOL
```
5. Set the Access permissions to Read.
6. Click Apply.

To rebuild the program as an ISAPI .dll:

Load the project bevord_h.app into the NetExpres IDE.
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 Delete.
3. Right-click on bev_h.obj in the left-hand pane of the Project window, and select Package Selected Files, Dynamic Link Library on the context menu.
4. Click Create on the Define New Dynamic Link Library dialog box to add bev_h.dll to the project list.
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 Net Express Project window, and select Build Settings on the context menu.
2. Click the Link tab.
3. Check Shared and Multi-Threaded and make sure Dynamic is checked.
4. Click Close.
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.
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"
```
Click Project > Rebuild to build the ISAPI program.
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.
Quit the Net Express IDE.

Now you can debug the program:

Start your Web browser.
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.
Click Brew It! on the form.
A dialog box appears, asking you whether or not you want to debug the application.
Click Yes.
The IDY File Error dialog box appears, because the debugger does not know where to find the .idy files needed for debugging.
Click Browse and use the Open dialog box to locate bev_h.idy file for the program. Net Express 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 Net Express 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.

Debugging an NSAPI Program

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

Configuring the Web server
Rebuilding the program as an NSAPI .dll
Debugging the program

To configure the server:

Select Netscape > Administer Netscape Servers on the Windows Start menu.
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. Type COBOL in the URL field
4. Type the full path to your project's source code directory in Alias.
5. Click OK.
  This displays the Save and Apply changes page.
6. Click Save and Apply 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.
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:/Program Files/Micro Focus/Net Express/base/demo/debug/bev_h.dll"
         funcs="beverage"
```
  where x is the drive where you installed Net Express.
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"
```
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 now starts bev_h.dll running.
Click Apply on the top frame of the Netscape Server Administration browser.
This displays Apply Changes.
Click Load Configuration Files.

To rebuild the program as an NSAPI:

Load the project bevord_h.app into the NetExpres IDE.
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 Delete.
3. Right-click on bev_h.obj in the left-hand pane of the Project window, and select Package Selected Files > Dynamic Link Library on the context menu.
4. Click Create on the Define New Dynamic Link Library dialog box to add bev_h.dll to the project list.
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 Net Express Project window, and click Build Settings on the context menu.
2. Click the Link tab.
3. Check Shared and Multi-Threaded and make sure Dynamic is checked.
4. Select Advanced from the Category drop-down menu.
5. Type accnsapi.obj in Link with these OBJ's.
  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 ofaccnsapi.obj (in your Net Express\base\lib directory) so that you can keep a backup, and then rename accnscs.obj toaccnsapi.obj .
  - Enterprise Server
    Rename the default version ofaccnsapi.obj (in your Net Express\base\lib directory) so that you can keep a backup, and then rename accenter.obj toaccnsapi.obj .
6. Type libhttpd.lib in the Link with these LIB's field (you would use httpd.lib for Commerce Server).
Copy libhttpd.lib to a location where it can be found by the Net Express 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:\Program Files\Micro Focus\Net Express\base\bin (where x: is the drive where you installed Net Express).
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.
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"
```
Click Project > Rebuild to build the ISAPI program.
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.
Quit the Net Express IDE.
Load the program into the Netscape server. To do this, shut the server down and restart it from Netscape Server Administration.

Now you can debug the program:

Start your Web browser.
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.
Click Brew It! on the form.
A dialog box appears, asking you whether or not you want to debug the application.
Click Yes.
The IDY File Error dialog box appears, because the debugger does not know where to find the .idy files needed for debugging.
Click Browse and use the Open dialog box to locate bev_h.idy file for the program. Net Express 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 Net Express 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.