Web Development

This chapter describes:

• The components of a Prolifics web application.

• How to set up the web application server

• How to create a new web application.

Web Application Components

A complete Prolifics web application has these components:

• Libraries that contain the application's screens, service components, reports, JPL modules, and graphics files.

• An initialization file that specifies the application's configuration settings.

• Server executables: requester, dispatcher, and Jserver.

• Prolifics libraries and configuration files that are required by the web application server.

These components, created during installation and with the web setup manager, are distributed among different directories. This section describes these components and their location.

Requester Program

Each Prolifics web application needs a copy of, or link to, the distributed requester executable in the HTTP server's program directory. Using the web setup manager to create your web application automatically copies the requester executable for your application.

There are three different versions of the requester program:

• CGI (Common Gateway Interface)—The default name is proweb or, for Windows, proweb.exe; the application's version is application-name[.exe]. This version uses the CGI protocol to pass the requester information to the Jserver.

• ISAPI (Microsoft's Internet Information Server API)—The default name is proweb.isa; the application's version is application-name.isa.

• NSAPI (Netscape's Web Server API)—The default name is proweb.nsa; the application's version is application-name.nsa.

Common names for the program directory on the HTTP server are cgi-bin or scripts.

Notes: For the O'Reilly HTTP server, use the directory specified for Standard CGI in the O'Reilly Administration dialog. Typically, this is cgi-bin or scripts, not cgi-win.

The application name, which is used in the file name for the initialization file as well as the requester executable, must be unique and follow the naming conventions for the operating system.

The permissions on the requester program must allow the program to be executed by the HTTP server.

Alternatively, the Panther web application can run as a Java servlet. For more information, refer to Appendix D, "Using Java Servlets."

Each Prolifics web application must have an initialization file whose file name matches the name of the requester executable in the format application-name.ini. The name of the distributed initialization file is proweb.ini and the name of the requester executable is proweb[.exe]. Using the web setup manager to create your web application will automatically create the initialization file for your application.

The location of the initialization file is different for Windows and UNIX:

• The UNIX installation creates an ini subdirectory in the home directory of the proweb user. The initialization files are located in that ini directory. Permissions on the initialization file must allow it to be read by the HTTP server. The permissions on the ini subdirectory and its parents must allow the directory to be read and executed by the HTTP server.

• The Windows installation copies the default initialization file proweb.ini to the \WINDOWS (or \WINNT) directory where Windows

• NT is installed.

For more information about initialization file settings, refer to Chapter 12, "Web Initialization Options." For instructions on using the web setup manager, refer to Appendix B, "Web Setup Manager."

Application Directory

The application directory contains the files and libraries for Prolifics screens and reports. All references to Prolifics files should be relative to this directory. This directory can also contain JPL modules, graphics files, and other files referenced by screens and reports. If these files are not in this directory, they must be in a directory specified by the Prolifics environment variable SMPATH.

The AppDirectory variable in the initialization file specifies the location of the application directory on your HTTP server. On startup, the Jserver changes its working directory to the application directory.

Prolifics opens files named in URLs relative to this directory and uses this directory as the basis for any relative path name references in Prolifics. For security purposes, Prolifics strips the parent directories from the pathname. This means that CGI variables, such as PATH_TRANSLATED, do not contain the absolute path specified in this variable.

Cache Directory

In order to preserve application values during a series of browser requests, Prolifics caches data whenever it transmits a screen that can be posted back to the web application server. Generally, the data is stored in a cache file on the web application server. The CacheDirectory variable determines the cache directory location; other variables determine how the cache files are removed.

On UNIX, the directory permissions must allow the HTTP server to read, write, and execute this directory.

Warning: When you create this directory, make sure that the period character (.) does not appear anywhere in the path name. (This restriction is imposed by the Grafsman software that manages Prolifics graphs.)

Configuration Directory

The application must know the location of smvars.bin in the config directory of the web application server distribution. Generally, the web application server determines the location of this file by looking at the setting for SMBASE, one of the application variables. If the directory specified in SMBASE, contains the config subdirectory, this is the only specification needed. Otherwise, the SMBASE, environment variable must specify the location of smvars.bin.

The initialization file can contain application-specific settings for any of the environment variables named in smvars.bin. The setting in the initialization file takes precedence.

Log Files

Errors occurring on the web application server are written to the log file set by the ErrorFile variable in the initialization file. Additional client and server information is written to the files specified by the ClientLog and ServerLog variables. In order to better track your web application server usage, you can specify that the ClientLog and ServerLog variables write information to the same file. Client logs contain information about the requester process. Server logs list configuration information and Jserver usage.

Note: Application errors are displayed in the browser and are not logged to the error file.

Using client and server logs does affect performance. You may choose to run client and server logs to test your web application, but not use them during deployment.

In three-tier applications, the time entered in the error logs is based on the server clock and will not correspond to the ULOG entries which are based on UTC (Coordinated Universal Time).

Logging Application Errors

In a Prolifics web application, errors can be logged to the web application server by calling sm_web_log_error in an error handler. The error messages are appended to the file named in the ErrorFile variable. Since the error message is not displayed to the user, you must make a separate call to sm_message_box, sm_femsg, or their JPL msg equivalents for any user messages.

The following error handler displays a message to the user and logs a separate message to the web error file:

proc error_def
	msg emsg "Error:  File not found"
	call sm_web_log_error ("Unable to find file.")
	return

---

Setting Up the Web Application Server

The Prolifics web application server must be installed on a machine that is running an HTTP server. After installing the software, the web application server must be configured.

Configuring the Requester Program

As discussed in previous sections, the Prolifics web application server has three components, requester, dispatcher, and Jserver, and there are three different versions of the requester program for the various protocols.

Since CGI uses a separate process for each request if the requests happen concurrently, the performance is slower for the CGI version of an application. Using the HTTP server's APIs, like ISAPI or NSAPI, will improve performance.

The requester executables distributed with the web application server are located at:

$SMBASE/util/proweb*

Copy the appropriate version to the HTTP server's program directory. Common names for the program directory are cgi-bin or scripts.

Using CGI

To use the CGI (Common Gateway Interface) version of the requester executable, copy proweb[.exe] to the program directory.

Using ISAPI

To use the ISAPI (Microsoft's Internet Information Server API) version of the requester executable, copy proweb.isa to the program directory.

Using NSAPI

To use the NSAPI (Netscape's Web Server API) version of the requester executable, you must configure the NSAPI server and copy proweb.nsa to the program directory. For more information, refer to Appendix C, "Setting Up an NSAPI Web Server."

Using Java Servlets

Alternatively, the Panther web application can run as a Java servlet. For more information, refer to Appendix D, "Using Java Servlets."

Configuring Middleware Access

In a three-tier processing model, the web application server acts as a client of the application server. The web application server can connect to the enterprise application either as a local or remote client:

• As a local client that resides on either the master or non-master machine, the web application server connects to the enterprise via the local environment's SMRBCONFIG setting.

• As a remote client, the web application server's Jserver component must use jserver.ws as its executable, set in the Web initialization file's Server variable; and the SMRBPORT and SMRBHOST variables, also in the Web initialization file, must be set to the application server's machine.

Configuring Library Access

In JetNet or BEA Tuxedo applications, you cannot open a remote library on startup using SMFLIBS= server_id!lib_name. If a client library cannot be placed on a shared file system, connect to the middleware on application startup using client_init and execute the Prolifics library function sm_l_open to open a remote library.

Configuring Database Access

For two-tier UNIX web applications, verify that:

• The user specified in the DBMS DECLARE CONNECTION statement is configured for database access.

• The web application's initialization file contains the environment variables needed for database access. (At runtime, the web application runs under an http process.)

For two-tier Windows web applications, verify that:

• The user that installs the web application as an NT service is configured for database access. That user can be specified as part of the monitor—install command or in the Services section of the NT Control Panel.

• The user specified in the DBMS DECLARE CONNECTION statement is configured for database access.

• The PC has the database vendor's client program installed.

• The web application's initialization file contains the environment variables needed for database access.

If the three-tier Windows application includes a web application client, the web application can be installed as an NT service. Verify that:

• The user that installs the web application as an NT service is configured for database access. That user can be specified as part of the monitor—install command or in the Services section of the NT Control Panel.

Verify that the NT service has database access by:

• Logging into the NT machine as the user (owner) of the NT service.

• Starting a database vendor's program.

Some database engines have special installation instructions. For example, Informix requires that you run setnet32 to add the NT service user and then run the demo login program to check that the user was added correctly.

Configuring a Windows NT Server

If you are using Windows NT as your Web application server, use NTFS as the disk file system, not FAT, to improve your system performance.

HTTP servers on Windows NT can start a web application as an NT service. For more information, refer to "Starting as an NT Service."

Creating a New Web Application

To create a new web application:

• Run the Web setup manager to create the initialization file and the requester program.

• Start the application using the monitor utility.

• For Windows NT servers, start the application as an NT service.

Using the Web Setup Manager

The Web setup manager utility creates the files necessary for a new web application and allows you to modify the settings of existing web applications.

To run the Web setup manager:

Start your Web browser and enter the following URL:

http://serverName/programDirectory/websetup

The Web setup manager consists of a series of screens; enter the information needed on each screen. You will need:

• The application name.

• The path of the application directory.

• The path of your Prolifics Web installation.

• The path of the HTTP server's program directory (usually called cgi-bin or scripts).

  Notes: For the O'Reilly HTTP server, use the scripts directory, not the cgi-win directory.

If the Web Setup Manager utility is unable to write the files to the correct directories, generally due to incorrect file permissions, it prompts for a temporary location, by default /tmp. At the end, the utility prompts you to move the files to their correct locations using provided script, application-name.cfg.

For step-by-step instructions in using the web setup manager, refer to Appendix B, "Web Setup Manager." For more information on web initialization options, refer to Chapter 12, "Web Initialization Options."

Starting Your Prolifics Web Application

You can start your web application (when it is not an NT service) with the monitor utility using the syntax:

monitor -start appname [appname ... ] 

and stop the web application using the syntax:

monitor -stop appname [appname ... ] 

On Windows NT, it is recommended that the Prolifics web application be installed as an NT server. Use the monitor command in conjunction with the -install option. The full syntax for that option is:

monitor -install application-name 
	[-display display-name] 
	[-{automatic|manual|disabled}] 
	[-user {\\domain\user|.\user}] 
	[-password password] 
	[[-depend service-name]...]

Once an application is installed as an NT service, monitor -start and monitor -stop must not be used to start and stop the web application. net start and net stop can be used for manual control, or use the Services section of the NT Control Panel.

It is also recommended that the services needed by the Prolifics web application start in a specific order:

• Database engine

• BEA Tuxedo IPC Helper (for JetNet and BEA Tuxedo applications)

• HTTP server

• Prolifics Web application

Accessing Your Prolifics Web Application

The type of requester program determines the syntax of the URL needed to access your application. The general syntax is:

http://serverName/programDirectory/applicationName/screenName

In the following URLs, the application name is inventory and the screen is main.scr.

To use the CGI executable to access the application:

• For Windows NT, copy proweb.exe to inventory.exe, start the application, and access the screen using the following URL:

  http://myhost.com/cgi-bin/inventory.exe/main.scr

• For UNIX, copy proweb to inventory, start the application, and access the screen using the following URL:

  http://myhost.com/cgi-bin/inventory/main.scr

To use the ISAPI executable to access the application, copy proweb.isa to inventory.isa, start the application, and access the screen using the following URL:

http://myhost.com/cgi-bin/inventory.isa/main.scr

To use the NSAPI executable to access the application, copy proweb.nsa to inventory.nsa, start the application using monitor or net start, and access the screen using the following URL:

http://myhost.com/prolifics/inventory.nsa/main.scr

Your HTTP server may support another syntax; refer to the HTTP server documentation.

If the web application is installed as a Java servlet, access the screen using the following URL:

http://myhost.com/proweb/inventory/main.scr

For more information on using Java servlets, refer to Appendix D, "Using Java Servlets."

Setting Web Browser Options

Caching should be enabled in the browser program. In Netscape Navigator, select Network PreferencesCache and set the Verify Documents option to Once per session or Every Time.

Firewalls

A firewall is the system that administers the access policy between two networks. The firewall determines which data is allowed network access and which data is blocked. A firewall lets users on your internal network access the global Internet, and prevents Internet users from accessing your internal network.

Prolifics is designed to work within whatever type of firewall that is implemented on your HTTP server. The security issues for Prolifics are the same issues encountered for all CGI programs. To be sure that your application operates within your company's firewall policy, check with your network or system administrator.

Your HTTP server vendor is the best source of information about how to set up the HTTP server to operate within a firewall and what security precautions are advised for CGI programs.

A Prolifics web application requires the CGI directory to contain the application's requester program. The remaining files in your application have configuration variables whose specifications are in the application's initialization file.

For example, the AppDirectory variable specifies the location of screens, reports, JPL modules, and graphics files. When Prolifics embeds the URL for the screen, it uses the relative path name based on the AppDirectory variable, not the absolute path name.