PreviousForm Validation Introduction to the World Wide WebNext

Chapter 12: Deploying Your Application

This chapter is about deploying your application on a Web server for production use on either an intranet or the Internet. It also covers using Web servers other than Solo for debugging during development.

12.1 Overview

Deploying your application means putting it on a Web server so that it can be used either through the Internet or an intranet. While you are developing a Net Express application with Form Designer and the Internet Application Wizard, using Solo as your Web server, the environment, Web shares and URLs are all set up so that everything works without you ever needing to make Web server configuration changes.

Once you deploy your application onto a production Web server, you need to check the following:

This chapter covers the procedure for deploying your application in detail. It also covers converting CGI programs into ISAPI or NSAPI programs. We advise that you develop all server-side programs as CGI programs, and then convert them to ISAPI or NSAPI when you are ready to deploy them.

Before deploying your application on a Web server, you must read the licensing conditions for distributing applications. Licensing conditions are in the End User License Agreement in the ReadMe Help. You can access the ReadMe Help from your Start menu.

12.1.1 Debugging with Other Web Servers

You can also debug programs with Web servers other than Solo. While you are debugging, we recommend that you set up Web shares of COBOL and CGI-BIN on your Web server, as this simplifies debugging while you are still making changes to an application. The differences between deployment and debugging on Web servers other than Solo are summarized in the section Deployment and Debugging Guide.

12.1.2 Worked Examples

To help you understand the information in this chapter, we have included some worked examples of debugging and deploying under different Web servers in the appendix Deployment and Debugging Examples.

12.2 Supported Servers

You can build applications with Net Express that conform to the CGI, ISAPI or NSAPI interfaces for Web programs. You should be able to run Net Express applications on any Web server that fully conform to one of these interfaces. At the time of publication, we have tested Net Express applications on the servers and operating systems listed below.

On Windows NT:

On UNIX:

12.3 Deployment and Debugging Guide

The next three sections summarize the steps needed to get an application running on a Web server other than Solo and are then followed by sections which explain each of the steps in detail. Some parts apply only when you deploy an application onto a production Web server; other parts apply only if you are debugging an application; these are clearly marked. The following are the key differences between deployment on a production Web server, and debugging on a Web server other than Solo:

The next three sections summarize the steps for either deployment or debugging with a different Web server:

12.3.1 Step-by-Step Deployment Guide (Windows Servers)

This section is an overview of the steps to follow when you deploy your application onto a production Web server. It assumes that when you are deploying onto a production Web site you want the option to use Web shares other than the Net Express defaults of COBOL and CGI-BIN.

  1. Choose the run-time system you want to use.

    The default run-time system for applications developed with Form Designer and the Internet Application Wizard is the dynamically bound shared single-threaded run-time system. For some application types it is either desirable or necessary to use a different run-time system.

    See the section Choosing a Run-time System.

  2. Set up the Web server shares and permissions.

    This is a once-only step, and is essentially part of setting up your Web server and Web site. However, the choices you make here affect what you do when you deploy your Net Express applications on that server.

    See the section Setting up the Web Server.

  3. Make a deployment copy of all the Net Express files for your application.

    Depending on the Web server you are using, the Web share names you have chosen, and the way in which you want to build your application, you might have to make minor changes to COBOL source files, and HTML files. It is better to make these changes on a copy separate from your development sources.

    See the section Making a Deployment Copy.

  4. Change application URLs as needed for your Web share names.

    Net Express assumes Web shares of COBOL and CGI-BIN in all the code it generates for you. If you use different Web share names, you must update COBOL and HTML code accordingly.

    See the section Changing Application URLs.

  5. If your application uses the server-side state mechanism documented in the chapter Server-Side Programming, you need to add the sstate module to your CGI. All Data Access Wizard generated applications use this mechanism.

    See the section Adding sstate to a Deployed Application

  6. Choose a server API and rebuild the application for your target Web server.

    You need to rebuild the application to pick up any changes made in step 4. You also have the option at this stage of rebuilding your application to use the ISAPI or NSAPI server APIs instead of CGI.

    See the section Rebuilding the Application.

  7. Install the application on the Web server.

    See the section Deploying Your Application.

  8. For ISAPI applications which use Object COBOL object-orientation functionality, you need to make configuration changes to the Net Express run-time system. You may also need to configure server permissions on Windows NT.

    See the section Deploying Object COBOL applications on ISAPI .

  9. For NSAPI applications only, you need to modify some of the Netscape server configuration files.

    See the section Before Running NSAPI Applications.

12.3.2 Step-by-Step Deployment Guide (UNIX Servers)

This section is an overview of the steps to follow when you deploy your application onto a production Web server running under UNIX. It assumes that when you are deploying onto a production Web site you want the option to use Web shares other than the Net Express defaults of COBOL and CGI-BIN.

  1. Install Micro Focus COBOL for UNIX V4.1 or later on the UNIX server.

  2. Install SCP on the UNIX server (see your UNIX Option User's Guide for details).

  3. Setup the Web server shares and permissions.

    This is a once-only step, and is essentially part of setting up your Web server and Web site. However, the choices you make here affect what you do when you deploy your Net Express applications on that server.

    See the section Setting up the Web Server.

  4. Make a deployment copy of all the Net Express files for your application.

    Depending on the Web server you are using, the Web share names you have chosen, and the way in which you want to build your application, you are likely to need to make minor changes to COBOL source files and HTML files. It is better to make these changes on a copy separate from your development sources.

    See the section Making a Deployment Copy.

  5. If your application uses the server-side state mechanism documented in the chapter Server-Side Programming, you need to add the sstate module to your CGI.

    See the section Adding sstate to a Deployed Application

  6. Change application URLs as needed for your Web share names.

    Net Express assumes Web shares of COBOL and CGI-BIN in all the code it generates for you. If you use different Web share names, you must update COBOL and HTML code accordingly. In addition, the executable files have different extensions on UNIX, and you must also consider issues of case-sensitivity.

    See the section Changing Application URLs.

  7. Publish the application to the Web server.

    See the section Publishing Your Application to UNIX.

12.3.3 Step-by-Step Debugging Guide

This section is an overview of the steps to follow if you are developing the application on a Web server other than Solo. It assumes that while you are developing and debugging an application you are happy to use the Net Express default Web shares of COBOL and CGI-BIN, as this saves work as you develop new forms and programs.

  1. Choose the run-time system you want to use.

    The default run-time system for applications developed with Form Designer and the Internet Application Wizard is the single-threaded shared run-time system. For some application types it is either desirable or necessary to use a different run-time system.

    See the section Choosing a run-time system.

  2. Set up the Web server shares and permissions.

    You need two shares: COBOL for your forms and HTML pages, and CGI-BIN for your programs.

    See the section Setting up the Web Server.

  3. Choose a server API and rebuild the application for your target Web server.

    You have the option at this stage of rebuilding your application to use the ISAPI or NSAPI server APIs instead of CGI. You can use Net Express to debug your application whichever of these APIs you use. We advise that you do your initial development with CGI , because if you get a protection fault in an ISAPI or NSAPI you usually have to close your Web server down and reboot it.

    See the section Rebuilding the Application.

  4. For ISAPI applications which use Object COBOL functionality, you need to make configuration changes to the Net Express run-time system. You may also need to configure server permissions on Windows NT.

    See the section Deploying Object COBOL applications on ISAPI .

  5. For NSAPI applications only, you need to modify some of the Netscape server configuration files.

    See the section Before Running NSAPI Applications.

Once you have been through this process, you can go through the edit/build/debug cycle for your application, using your own Web server instead of Solo to run the server-side programs.

12.3.4 Choosing a Run-time System

Applications created with Form Designer and the Internet Application Wizard default to using the dynamically bound shared single-threaded run-time system. This means that the executable file links dynamically to the shared run-time system when it is started, and that the executable is single-threaded. The executable locates the run-time system through the Windows registry.

You must change the way your executable files are built if:


Note: You can write CGI applications to use multi-threading, if this is likely to be an advantage. In this case, link with the shared or static multi-threaded run-time system. This option is covered in sections Building a Shared Run-time System CGI Application and Building a Static Run-time System CGI Application.


12.3.5 Setting up the Web Server

This section is about setting up your Web server to run Internet Applications. The exact method for doing this differs from server to server, so you need to consult your server documentation for exact instructions on how to do this.

Because there are some differences in setting up a server for deployment and for debugging, the instructions are split into two separate sections:

Setting Up the Web Server for Deployment

This section does not cover UNIX Web servers; although the information about Web shares applies to all operating systems, information about Application Server is specific to Windows NT and Windows 95. For more information about deployment on UNIX, see the Unix Option User's Guide.

To set up your Web Server for deployment:

  1. If you are going to deploy your application using the shared run-time system, install Application Server on the target machine. This sets up a run-time system for any Net Express applications you want to run on the machine.

    Note: On UNIX servers you must install Object COBOL for UNIX V4.1.


  2. Start the administration tool for your Web server (consult the Web server documentation if you don't know how to do this).

  3. Set up the Web shares listed in the table below. A Web share is a mapping of a URL to an actual directory or folder on the Web server.

    This table shows the default names used by Net Express for shares for each of the different types of resource. If you use Web shares with names different to Net Express defaults, you will have to edit the files in your application as explained in Changing Application URLs. If you are deploying an ISAPI or NSAPI application, or to a UNIX server, you will have to do this anyway, as the names of the executable files are slightly different.

    Web share
    Net Express Default name
    Permissions
    Description
    bin-share /CGI-BIN/ Execute Put the executables (.exe and .dll files on Windows) for your application in this share.
    form-share /COBOL/ Read-only Put the forms and HTML pages (.htm files) for your application in this share.
    image-share /COBOL/ Read-only If your application has lots of images, you can put them in a separate share to make application maintenance easier.

    You need to change the Image Source property of any HTML Images or Picture Path property of any ActiveX Image Controls.


Notes:


If you are using the default Net Express Web share names, you aren't changing run-time system options, and you aren't deploying using ISAPI or NSAPI, you can now jump straight to the section Deploying Your Application.

Setting Up the Web Server for Debugging

To set up your Web Server for debugging with Net Express:

  1. Start the administration tool for your Web server (consult the Web server documentation if you don't know how to do this).

  2. Set up the Web shares listed in the table below. A Web share is a mapping of a URL to an actual directory or folder on the Web server.

    This table shows the default names used by Net Express for shares for each of the different types of resource. If you use Web shares with names different to Net Express defaults, you will have to edit the files in your application as explained in Changing Application URLs.

    Web share name
    Permissions
    Location
    /CGI-BIN/ Execute The executable directory (.exe and .dll files) for your Net Express project. This a subdirectory of the source directory. The default Net Express subdirectories are debug and release, for Debug and Release build types.
    /COBOL/ Read-only The source directory for your project.

  3. If your Web server is running on NT as a service, disallow anonymous logons to your Web server. If your Web server runs logged as a user account, ensure that the user account it uses has admin privileges and "logon as service" permissions.

    Web servers usually run with anonymous logons as default, which enables any user to access the server across an intranet or the Internet without providing a name and password. With an anonymous logon, the Web server has very limited rights and cannot start the debugger.

    When you disallow anonymous logons, you prevent other users from connecting to your Web server without giving a user name and password, but when you connect to the server locally (from the same machine it is running on), you give it the same user rights you have, enabling it to start Animator (the Net Express debugger).

12.3.6 Making a Deployment Copy


Note: Skip this step if you are setting your application up for debugging.


You need to make a copy if any of the following apply:

Rather than change the original files you used to develop the application, we strongly recommend that you make a copy and edit that instead. Create a new directory on your development machine for the deployment copy, and copy all the files in your project directory to it. Close the project in Net Express if you have it open; you can't copy the .app file (the project file) when it is open in Net Express.

12.3.7 Changing Application URLs


Note: Skip this step if you are setting your application up for debugging.


The applications generated by Net Express assume that HTML pages (.htm files) are to be found in Web share COBOL, and that executable files are in CGI-BIN. If you are using other Web share names, you need to change the references to the following:

To change CGI references, follow the steps below for each form which is input to a CGI program:

  1. Load the page into Form Designer by right-clicking on the .htm file in the left-hand pane of the Project window, and clicking Edit on the context menu.

  2. Click the Action property, and amend it to read:
    /binshare/program.ext

    where the parameters are:

    bin-share The Web share for executable files
    program The filename of the program
    ext The file extension for the program. This is .exe for a CGI program on a Windows platform. It is .dll if you plan to deploy the application as an ISAPI program, and a user-defined extension for an NSAPI program.

    On UNIX servers, the CGI is run from a shell script, which has the extension .sh.

To change the image paths, load each page with images into Form Designer and carry out the following steps for each image:

  1. Click on an image.

  2. Click on the Image Source property (HTML images) or the Image Path property (ActiveX image controls) and change it to:
    /image-share/image.ext

    where the parameters are:

    image-share The Web share for executable files
    image The filename of the image.
    ext The file extension for the image.

To change the paths for HTML forms output by the DISPLAY verb:

  1. Locate each IS EXTERNAL FORM IDENTIFIED BY clause in your COBOL source code.

  2. Amend the filename to read:
    "fullpath\htmlfile.htm" 

    where fullpath is the full physical path to the location on the Web server where the .htm file is to be installed, not the Web share name.

12.3.8 Adding sstate to a Deployed Application

The server-side support mechanism documented in the chapter Server-Side Programming uses a module called sstate, which is not part of the COBOL run-time system (the sources are provided for you to make changes if needed). Consequently, whenever you deploy an application which uses sstate you need to link it into your CGI, ISAPI or NSAPI executables. Skip this section if your application does not use this mechanism.


Note: All data access Internet Application Wizard generated applications use this mechanism.

This section describes what you need to do on Windows and UNIX platforms separately.


Windows

On Windows, you can link sstate.obj directly into the executable program:

  1. Right-click on the main executable file for the CGI (an .exe 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. Select Category > Advanced.

  4. Enter sstate in Link with these OBJ's and click OK.

UNIX

To deploy on UNIX, add sstate.int to your Net Express project, and when you publish it with the UNIX option, it will be linked into the CGI automatically:

  1. Select Project > Add Files to Project.

  2. In the Open dialog, go to folder \Program Files\MERANT\Net Express\unix\cgi-sup (this folder is only available if you have installed the UNIX Option).

  3. Select File type > All Files and then select sstate.int from the list.

  4. A message box appears, warning you that this file is in a different directory to your project directory. Click OK to copy it to your project directory.

12.3.9 Rebuilding the Application

This section describes how you should rebuild the programs in your application for deployment on the target machine. You need to rebuild the application if any of the following apply:

The following sections explain how you build your application in different ways:

Building a Static Run-time System CGI Program

You are only recommended to use the static run-time system if you are going to have one or two COBOL CGI programs running on your Web server, and don't want the overhead of the COBOL run-time system files on the server.

To build a static run-time system CGI program:

  1. Right-click on the main executable file for the CGI (an .exe 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. Select Static and Single-threaded.

  4. Rebuild the application.

To link the application with the multi-threaded run-time system instead, click the Multi-threaded radio button in step 3 above. Only do this if you have written your CGI application to take advantage of multi-threading. For more information, click Help Topics on the Net Express Help menu and look up Multi-threading in the Index.

Building a Shared Run-time CGI System Program

If you build your CGI linked with the shared run-time system, you must install Net Express Application Server on the machine where you are going to deploy the application, as this provides the run-time system files.

When you create applications using Form Designer and the Internet Application Wizard, they are always linked using the dynamically bound shared run-time system. If you have changed the default link settings, you can change them back using the Build Settings dialog box:

  1. Right-click on the main executable file for the CGI (an .exe 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. Select Shared and Single-threaded.

    You can link with the multi-threaded run-time system (by selecting Multi-threaded) if you have written your CGI application to take advantage of multi-threading. For more information, click Help Topics on the Net Express Help menu and look up Multi-threading in the Index.

  4. Check Dynamic.

    This enables your executable to find the Application Server or Net Express run-time system by looking it up in the Windows registry.

  5. Rebuild the application.

Building a Shared Run-time System ISAPI or NSAPI Program

You need to make the following changes to your Net Express project to build an ISAPI or NSAPI program:


Notes:


To build the program as a .dll executable file:

  1. Right-click on the .exe in the left-hand pane of the Project window, and select 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. Select all the .obj files that were linked together to build the original .exe program, in the left-hand pane of the Project window, right-click 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 change compiler and build settings:

  1. Set the compiler directives for ISAPI or NSAPI as described in the table below.

    You can ensure these are set every time the program is compiled by including a $SET statement at the top of your program:

    For example:

    $set webserver(nsapi,myentry) case reentrant(2)

    The dollar sign ($) must appear in column 7 of your source code unless you have set directive SOURCEFORMAT(FREE), in which case it can appear in any column. For more information on setting compiler directives, click Help Topics on the Net Express Help menu, and from the Contents tab, click Reference, Compiler Directives.

    Directives for ISAPI and NSAPI programs:

    Directive
    Description
    WEBSERVER(ISAPI) Tells the compiler that this program is an ISAPI application.

    Only apply this directive to the main .dll for your application - the one which is started to run the application. Do not apply it to any submodules called by the main .dll or you will get run-time errors.

    WEBSERVER(NSAPI, entry_point_name) Tells the compiler that this program is an NSAPI application. The value entry_point_name is a user defined name, which you can set to an arbitrary value. The compiler creates a hidden entry point with entry_point_name to enable the NSAPI web server to start your program. Don't use any hyphens in entry_point_name. The entry_point_name must be different to the name in your program's PROGRAM-ID header.

    Only apply this directive to the main .dll for your application - the one which is started to run the application. Do not apply it to any submodules called by the main .dll or you will get run-time errors.

    CASE Prevents external symbols (including names of called programs) from being converted to upper case. If you don't do this, when an end-user attempts to run the program they see a "not found" message on their Web browser.
    REENTRANT(2) Ensures that it is safe to have multiple copies of this program running.
    SQL(THREAD=ISOLATE) Only needed for Open ESQL applications (including any data access applications created with the Internet Application Wizard). Ensures that thread resources and transactions are not shared between threads.

    For Open ESQL applications (such as data access applications generated by the Internet Application Wizard), the following directive can improve performance

  2. Change the Build Settings for the project:

    1. Right-click on the .dll file for the ISAPI or NSAPI 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. Click Link Wizard. When you go through the wizard, select choices for a server-side program, which is multi-threaded. This sets up the program to use the shared dynamically bound multi-threaded run-time system.

Now rebuild the project to create ISAPI or NSAPI .dll programs.


Note: For ISAPI programs, you need to change the Action property on any form which starts the ISAPI to start program.dll instead of program.exe (see the section Changing Application URLs). You also need to change the Action property for NSAPI programs, but to point to a new MIME type. The extra changes needed for NSAPI programs are covered in the section: Before Running NSAPI Applications.


12.3.10 Before Running NSAPI Applications

This section outlines two extra steps you need to take before you deploy or debug an NSAPI server-side program.

When you have carried out both these steps, and deployed the files on your Web server machine, you have to shut the server down and restart it to load the NSAPI program.

Set up the accnsapi Module

Your server-side program needs an accnsapi.dll module to transfer data to and from the NSAPI Web server. You need to build a version of this to match the Web server you are using, because different Netscape servers use different entry point names.

To build and set up accnsapi:

  1. The accnsapi module needs to know a set of entry point names so that it can communicate with the Netscape server. These are provided by Netscape in a .lib file supplied with the server:

    These files are in a subfolder of the one containing your Netscape server software: \server\nsapi\examples. Copy the appropriate file to your \Program Files\MERANT\Net Express\base\lib directory (this ensures that the linker can find it when you rebuild the file.

  2. Different versions of accnsapi.obj are supplied with Net Express to work with different Netscape servers :

  3. Start a Net Express command prompt (from the Windows Start menu, select Programs, MERANT Net Express, Net Express Command Prompt).

  4. From your \Program Files\MERANT\Net Express\base\lib directory run the following command:
    cbllink -d -j accnsapi.obj netscape.lib

    where netscape.lib is either libhttpd.lib or httpd.lib (see step 1 above).

  5. Copy accnsapi.dll from \Program Files\MERANT\Net Express\base\lib to \Program Files\MERANT\Net Express\base\bin.

12.3.10.1 Modifying the NSAPI Server Configuration Files

The modifications in this section are for Netscape's Fasttrack server; if you are using a different server consult the documentation supplied with it.

The modifications are needed to set up the following:

You need to update the following configuration files:

Make the following changes to obj.conf:

  1. Add the following line to load your server-side program when the server is started:
    Init fn="load-modules" shlib="executable_file.dll"
        funcs="entry-point-name"

    where the parameters are:

    Parameter
    Description
    executable_file The physical path and name of the server-side program.

    Note: Use forward-slashes "/", not back-slashes "\" in the path, even when deploying on Windows platforms.


    entry-point-name The entry-point name you specified when compiling the program, in directive WEBSERVER(NSAPI,entry-point-name). See the section Building a Shared Run-time System ISAPI or NSAPI Program.

  2. 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:
    Service fn="entry-point-name" method="(GET|POST)"
    type="magnus-internal/new-type"

    where the parameters are:

    Parameter
    Description
    new-type A name for a new MIME type to be associated with the program.
    entry-point-name The entry-point name you specified above.

Make the following changes to mime.types:

  1. Add the following line to associate the new MIME type you defined above with an extension:
    type=magnus-internal/new-type exts=extension

    where the parameters are:

    Parameter
    Description
    new-type The MIME type name you associated with the program above.
    extension A file extension for your program. Note that you are not limited to three-character extensions.

Changing the Action Property

Your NSAPI program is started whenever the Browser requests the new MIME type you defined in the previous section. You need to change the Action property on any forms which call this program to request the new MIME type.

To change the Action property:

  1. Load the page into Form Designer.

  2. Select each form on the page, click on the Action property, and change it to read:
    program.extension

    where program is the entry-point for your program, and extension is the extension for the new MIME type defined in the previous section.

  3. Save the page, and deploy the new version of the .htm file.

12.3.11 Deploying Object COBOL applications on ISAPI

You can use Object COBOL to write object-oriented ISAPI applications, but there are some extra steps you need to take when deploying these. Using OO features also enables you to use OLE automation in your ISAPI applications.

Before running any Object COBOL ISAPI application, you must disable Object COBOL's default exception handling mechanism. The default exception handler responds to an OO exception by displaying an error message and closing down the process. This is undesirable as ISAPI applications run in the same process as the Web server. To disable the default handler:

  1. Create an ASCII text file called cobopt.cfg.

  2. Add the line:
    set signal_regime(0)=1

    to the file.

  3. Put this file in the Application Server run-time system files directory (by default \program files\micro focus\appserver).

OLE and ISAPI

Consult your Distributed Computing online book for more information about OLE automation.

An ISAPI .dll runs under Windows NT as a service, and does not include settings or user permissions which apply to specific user accounts. This is important when you use OLE from inside an ISAPI .dll.

If you want to use an in-process OLE server, then as long as the server .dll file is loadable, your application can access it.

If you want to use an OLE local server, then you must ensure you have the correct permissions to both access and launch the server executable.

To do this:

  1. Ensure there is a registry entry for the OLE server.

    If the OLE server is from third party software, it will either register itself when you install it, or you may need to consult the product documentation to find out how to register the server.

    If the OLE server is one you have written using Object COBOL, then you need to register it yourself. Click OLE Registry File Generator on the Net Express Tools menu, click the Help button on the OCREG dialog box, and then follow the instructions.

  2. Run regedit.exe (Windows 95) or regedt32.exe (Windows NT) and add an APPID setting for the server:

    1. Work your way down the registry tree until you get to HKEY_CLASSES_ROOT\CLSID.

    2. Right-click CLSID in the left-hand pane, and click New, Key on the context menu. Enter the UUID for the server as the new key.

      The UUID is the value generated when you create a registry entry for an OLE server. Load the .reg file created in step 1 above into a text editor, copy the long hex value which appears repeatedly in the file - include the braces "{}" - rename the key and paste in the value from the clipboard.

    3. Right-click the new key, and select String > New on the context menu. Type APPID into the new Name column in the right-hand pane.

    4. Double-click on the APPID entry and paste in the UUID as the value again.

Now you can set up the account permissions to run the server:

  1. Run dcomcnfg.exe and set the identity of the account you want to run the server:

    1. Select the server application from the list and display its properties.

    2. Select the Identity tab.

    3. Select The User.

    4. Enter the user name and password of the account you want this application to run under.

      This determines the security permissions the application has when it is running.

  2. Use dcomcnfg.exe to ensure the user account you selected above has launch permissions to start the server:

    1. Select the application from the list and display its properties.

    2. Select the Security tab, and verify that the user account selected above, or one of the groups it belongs to, has permissions to start the server.

      If Default is selected, dismiss the Application Properties window, click Default Security on the main window and click Edit Default.

      If the default settings do not include the required user, add the user by going back to the application's Security tab, selecting Use Custom Launch Permissions, clicking Edit and adding the user to the list.

  3. Ensure the folder that contains the server has the correct permissions for the user specified to execute the server:

    1. Select the folder in Windows Explorer.

    2. Display the Properties dialog for the folder.

    3. Select the Security tab, and click Permissions.

Once the permissions are set correctly, you should be able to connect to the local server via OLE from within your ISAPI .dll file.

12.4 Deploying Your Application

Read this section if you are deploying your application on a Web server on another machine.

Once you have worked through the Web server setup and application changes described in Deployment and Debugging Guide, you are ready to deploy your application on a different Web server machine.

Copy the files in your project as follows:

The Web shares are the ones you set up in section Setting up the Web Server for Deployment.

The following subsections provide extra information which only applies to certain types of application:

12.4.1 Locating Dependencies in ISAPI and NSAPI Applications

This section outlines extra steps you need to take if you are deploying an ISAPI or NSAPI application which meets either of these criteria:

Unlike CGI programs, ISAPI and NSAPI programs won't find any files they depend on if you simply put them in the same directory as the main program itself. Because an ISAPI or NSAPI application runs as a thread inside the Web server process, its current working directory is always set to the current working directory of the Web server, rather than the directory where the main .dll program is located.

Locating Subprograms from ISAPI/NSAPI applications

To enable an ISAPI or NSAPI application locate any separate .dll files it calls, carry out the following steps on each machine where the application is deployed:

  1. Copy all the .dll files to a single directory.

    You can use the same directory you are using for the main ISAPI or NSAPI .dll files.

  2. Add the directory location to the Net Express or Application Server path for the machine:

    1. Start the Registry Editor from a command prompt (use regedit on Windows 95 and regedt32 on Windows NT).

    2. Locate the following key:

      HKEY_LOCAL_MACHINE/SOFTWARE/Micro Focus/3.0/COBOL/3.0/Environment

    3. Concatenate the location of your .dll directory to the PATH value.

Locating HTML files from ISAPI/NSAPI applications

To enable an ISAPI or NSAPI application locate any HTML files it outputs through the extended DISPLAY syntax carry out the following steps on each machine where the application is deployed:

  1. Copy all the HTML files to a single directory.

  2. Add the directory location to the Net Express or Application Server COBDATA path for the machine:

    1. Start the Registry Editor from a command prompt (use regedit on Windows 95 and regedt32 on Windows NT).

    2. Locate the following key:

      HKEY_LOCAL_MACHINE/SOFTWARE/Micro Focus/3.0/COBOL/3.0/Environment

    3. If there isn't a COBDATA value displayed, add one.

    4. Set the value to:
      ;;%COBDIR%;html-dir

      where html-dir is the directory where your HTML files are located. The two semicolons at the start are important and must not be omitted.

12.4.2 Using ODBC Data Sources

If your application uses an ODBC data source, you need to ensure that the source is visible to the server-side programs. Server-side programs usually inherit the same user permissions as the Web server which starts them. To ensure that the Web server can access the ODBC data:

12.5 Publishing Your Application to UNIX

Once you have carried out the setup and application changes outlined in Step-by-Step Deployment Guide (UNIX servers), you can publish your application to a UNIX server.

  1. Open the deployment copy of your application inside Net Express.

  2. On the UNIX server, create a directory to hold all the files for the application.

  3. Click Setup on the UNIX menu, and set the server options for your application.

    See your UNIX Option User's Guide for details.

  4. Click Publish on the UNIX menu to send the project files to the server and to build the executables on the server.

  5. Create a shell script to run each CGI program in your application.

    The shell script is needed to set up the COBOL environment before running the COBOL program:

    1. Create a script like this:
      #!/bin/sh
      ./mfenv.sh cginame
    2. Save it is as cginame.sh

  6. Copy the files in the directory you published to as follows:

    The Web shares are the ones you set up in section Setting up the Web Server for Deployment.

12.6 Debugging Your Application

Read this section if you are debugging your application on a Web server other than Solo on your development machine.

Once you have worked through the Web server setup and application changes described in Deployment and Debugging Guide, you are ready to start debugging your application. The procedures for debugging CGI programs and ISAPI/NSAPI programs are slightly different, so they are described separately in the following two sections.

12.6.1 Animating CGI Programs

The instructions in this section assume you have already carried out the Web server setup and application changes described in Deployment and Debugging Guide. CGIs are the easiest programs to animate on a Web server other than Solo. To animate CGI programs you need to make some changes to the project in the Net Express IDE, and then you can begin debugging.

To set up your project for animation:

  1. Right-click on the .exe file for your CGI and select Build Settings on the context menu. Click the Link tab and ensure that the .exe is built as a Character application, rather than a Graphical application. Change the setting and rebuild if necessary.

  2. Click Execute on the Net Express Options menu to display the Animator Execution Options dialog box.

  3. Uncheck Use the Solo webserver for CGI projects and click OK.

    Note: This setting applies to this project and any others you subsequently load. To revert to using Solo, change the option back.


  4. Click Settings on the Net Express Animate menu to display the Animate Settings dialog box.

  5. Check Wait for animatable attachment.

  6. Enter the URL to start your application in Start animating at. This is in the form:
    http://machinename.domain/COBOL/inputform.htm

    or

    http://machinename.domain/CGI-BIN/program.exe

    where:

    Parameter
    Description
    machinename.domain Specifies where your machine can be found on the intranet or Internet. For example, www.merant.com, or dev1.slithy.com.
    inputform The name of the page containing the form which starts your application.
    program The name of the program which starts your application.

To animate the program:

12.6.2 Animating ISAPI and NSAPI Programs

The instructions in this section assume you have already carried out the Web server setup and application changes described in Deployment and Debugging Guide, including the changes needed to rebuild your programs as ISAPI or NSAPI programs. You can't run or debug ISAPI or NSAPI programs using Solo, so if you want to debug these programs you have to use a Web server that supports one of these APIs. To debug ISAPI and NSAPI programs, you need to make a change to your Net Express IDE settings and add a statement to the start of each ISAPI or NSAPI program.

To set up your project for animation:

  1. Select Execute on the Net Express Options menu to display the Animator Execution Options dialog box.

  2. Uncheck Use the Solo webserver for CGI projects and click OK.

    Note: This setting applies to this project, and any others you subsequently load. To revert to using Solo, change the option back.


  3. Add the following statement to the start of each of your ISAPI or NSAPI programs:
    call "CBL_DEBUGBREAK"

    When executed, this statement starts Net Express and begins the debugger.

  4. Rebuild the project.

    If your Web server has already loaded the .dll file for your application, it will be locked and can't be overwritten. If the Web share is set to point to the directory where the file is built, you have to shut down your Web server before Net Express can rebuild the project properly. If the Web share is in a different directory, you have to shut down your Web server before you can copy over the rebuilt .dll file.

To animate your application:

  1. If you are using an NSAPI Web server, stop it and restart it to load the NSAPI .dll program.

  2. Start a Web browser and enter the URL of the page or program which starts your application.

    Once an ISAPI program executes the statement CALL "CBL_DEBUGBREAK", you are prompted by a message box asking you if you would like to invoke the debugger.

  3. Click Yes.

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

  4. Click Browse and use the Open dialog box to locate the .idy file for the program. Net Express creates this in the same directory as the executable files for your application. The executable files are usually in the debug or release (depending on the build type) subdirectory of your source files (project) directory.

    You can now debug the program.


Notes:



Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousForm Validation Introduction to the World Wide WebNext