| Form Validation | Introduction to the World-Wide Web | |
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.
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 NetExpress 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 a plain text file license.txt. To read this, use Windows Explorer to view the contents of folder \netexpress\base\bin, and double-click on license.txt. This opens it inside Notepad.
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.
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.
You can build applications with NetExpress that conform to the CGI, ISAPI or NSAPI interfaces for Web programs. You should be able to run NetExpress applications on any Web server that fully conforms to one of these interfaces. At the time of publication, we have tested NetExpress applications on the servers and operating systems listed below.
On Windows NT:
On UNIX:
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:
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 NetExpress defaults of COBOL and CGI-BIN.
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.
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 NetExpress applications on that server.
See the section Setting up the Web Server.
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.
NetExpress 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.
See the section Adding sstate to a Deployed Application
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.
See the section Deploying Your Application.
See the section Deploying Object COBOL applications on ISAPI .
See the section Before Running NSAPI Applications.
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 NetExpress defaults of COBOL and CGI-BIN.
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 NetExpress applications on that server.
See the section Setting up the Web Server.
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.
See the section Adding sstate to a Deployed Application
NetExpress 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.
See the section Publishing Your Application to UNIX.
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 NetExpress default Web shares of COBOL and CGI-BIN, as this saves work as you develop new forms and programs.
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.
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.
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 NetExpress 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.
See the section Deploying Object COBOL applications on ISAPI .
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.
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:
ISAPI and NSAPI programs must be multi-threaded. Link them as described in section Building a Shared Run-time System ISAPI or NSAPI Application.
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.
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:
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:
Note: On UNIX servers you must install Object COBOL for UNIX V4.1.
This table shows the default names used by NetExpress for shares for each of the different types of resource. If you use Web shares with names different to NetExpress 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
|
NetExpress 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 NetExpress 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.
To set up your Web Server for debugging with NetExpress:
This table shows the default names used by NetExpress for shares for each of the different types of resource. If you use Web shares with names different to NetExpress 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 NetExpress project. This a subdirectory of the source directory. The default NetExpress subdirectories are debug and release, for Debug and Release build types. |
| /COBOL/ | Read-only | The source directory for your project. |
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 NetExpress debugger).
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 NetExpress if you have it open; you can't copy the .app file (the project file) when it is open in NetExpress.
Note: Skip this step if you are setting your application up for debugging.
The applications generated by NetExpress 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:
Internet Application Wizard generated applications do not use DISPLAY, so you only need to do this if you have been using the DISPLAY verb as described in the chapter Server-Side Programming.
To change CGI references, follow the steps below for each form which is input to a CGI program:
/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:
/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:
"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.
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.
On Windows, you can link sstate.obj directly into the executable program:
To deploy on UNIX, add sstate.int to your NetExpress project, and when you publish it with the UNIX option, it will be linked into the CGI automatically:
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:
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:
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 NetExpress Help menu and look up Multi-threading in the Index.
If you build your CGI linked with the shared run-time system, you must install NetExpress 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:
You can link with the multi-threaded run-time system (by clicking the Multi-threaded radio button) if you have written your CGI application to take advantage of multi-threading. For more information, click Help Topics on the NetExpress Help menu and look up Multi-threading in the Index.
This enables your executable to find the Application Server or NetExpress run-time system by looking it up in the Windows registry.
You need to make the following changes to your NetExpress project to build an ISAPI or NSAPI program:
Notes:
To build the program as a .dll executable file:
To change compiler and build settings:
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 NetExpress 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 performa
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.
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.
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:
These files are in a subfolder of the one containing your Netscape server software: \server\nsapi\examples. Copy the appropriate file to your \netexpress\base\lib directory (this ensures that the linker can find it when you rebuild the file.
The default version of accnsapi.obj is set up for FastTrack, so you don't need to change it.
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 to accnsapi.obj .
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 .
cbllink -d -j accnsapi.obj netscape.lib
where netscape.lib is either libhttpd.lib or httpd.lib (see step 1 above).
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:
Init fn="load-modules" shlib="executable_file.dll"
funcs="entry-point-name"
where the parameters are:
| 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. |
Service fn="entry-point-name" method="(GET|POST)" type="magnus-internal/new-type"
where the parameters are:
| 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:
type=magnus-internal/new-type exts=extension
where the parameters are:
| 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. |
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:
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.
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:
set signal_regime(0)=1
to the file.
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:
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 NetExpress Tools menu, click the Help button on the OCREG dialog box, and then follow the instructions.
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.
Now you can set up the account permissions to run the server:
This determines the security permissions the application has when it is running.
If the Default radio button is selected, dismiss the Application Properties window, click the Default Security tab on the main window, and click the Edit Default button.
If the default settings do not include the required user, add the user by going back to the application's Security tab, selecting the Use Custom Launch Permissions radio button, clicking the Edit button and adding the user to the list.
Once the permissions are set correctly, you should be able to connect to the local server via OLE from within your ISAPI .dll file.
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:
If a page is always output by EHTML from one of your server-side programs, you don't need to copy it across to the Web server as it is embedded in the executable code for the program. All Internet Application Wizard generated code uses EHTML to output forms.
These files contain JavaScript for functions such as setting and retrieving cookies, and client-side validation functions.
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:
Read this subsection if you are deploying an ISAPI or NSAPI application.
Read this subsection if you are deploying a SQL application which uses an ODBC data source (this includes data access applications generated by the Internet Application Wizard).
This section outlines extra steps you need to take if you are deploying an ISAPI or NSAPI application which meets either of these criteria:
See the subsection Locating Subprograms from ISAPI/NSAPI applications
See the subsection Locating HTML files from ISAPI/NSAPI applications
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.
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:
You can use the same directory you are using for the main ISAPI or NSAPI .dll files.
HKEY_LOCAL_MACHINE/SOFTWARE/Micro Focus/3.0/COBOL/3.0/Environment
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:
HKEY_LOCAL_MACHINE/SOFTWARE/Micro Focus/3.0/COBOL/3.0/Environment
;;%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.
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:
The Web server will not be able to access a user data source.
Working with user DSNs is possible, but setting up the correct access permissions can be difficult.
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.
See your UNIX Option User Guide for details.
The shell script is needed to set up the COBOL environment before running the COBOL program:
#!/bin/sh ./mfenv.sh cginame
You don't need to copy across forms which are always output by EHTML from server-side programs. EHTML embeds output forms in the executable code for the program. All Internet Application Wizard generated programs use EHTML to output forms.
The Web shares are the ones you set up in section Setting up the Web Server for Deployment.
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.
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 NetExpress IDE, and then you can begin debugging.
To set up your project for animation:
Note: This setting applies to this project, and any others you subsequently load. To revert to using Solo, change the option back.
http://machinename.domain/COBOL/inputform.htm
or
http://machinename.domain/CGI-BIN/program.exe
where:
| machinename.domain | Specifies where your machine can be found on the intranet or Internet. For example, www.microfocus.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:
This starts the default Web browser, and loads the start page or program for your application. As soon as a CGI program starts executing, NetExpress starts animating, with the first line highlighted for execution. You can now debug the program.
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 NetExpress IDE settings, and add a statement to the start of each ISAPI or NSAPI program.
To set up your project for animation:
Note: This setting applies to this project, and any others you subsequently load. To revert to using Solo, change the option back.
call "CBL_DEBUGBREAK"
When executed, this statement starts NetExpress, and begins the debugger.
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 NetExpress 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:
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.
The IDY File Error dialog box appears, because the debugger does not know where to find the .idy files needed for debugging.
You can now debug the program.
Notes:
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Form Validation | Introduction to the World-Wide Web | |