Web Development

This chapter describes:

• The components of a Panther web application.

• How to set up the web application server

• How to create a new web application.

Web Application Components

A complete Panther 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.

• Panther 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 Panther 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 Apache HTTP server, use the directory specified for Standard CGI in the Apache 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 Panther 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 %WINDDIR% directory where Windows 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 Panther screens and reports. All references to Panther 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 Panther 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.

Panther opens files named in URLs relative to this directory and uses this directory as the basis for any relative path name references in Panther. For security purposes, Panther strips the parent directories from the path name. 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, Panther 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 Panther 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 SMVARS, 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 Panther 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 Panther 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 Panther 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 and Oracle 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 Panther 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 a 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 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 a service. Verify that:

• The user that installs the web application as a 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 Control Panel.

Verify that the service has database access by:

• Logging into the machine as the user (owner) of the 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 service user and then run the demo login program to check that the user was added correctly.

Configuring a Windows Server

HTTP servers on Windows can start a web application as a Windows service. For more information, refer to "Starting as a 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 servers, start the application as a Windows 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 Panther Web installation.

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

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 Panther Web Application

You can start your web application (when it is not a 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, it is recommended that the Panther web application be installed as a service. 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 a 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 Control Panel.

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

• Database engine

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

• HTTP server

• Panther Web application

Accessing Your Panther 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, 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/panther/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 Microsoft Internet Explorer, select ToolsInternet Options in the Browsing History Settings dialog, choose one of the Automatically or the Every time I visit the web page options.

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.

Panther is designed to work within whatever firewalls that are on your network. The security issues for Panther 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 Panther 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 Panther embeds the URL for the screen, it uses the relative path name based on the AppDirectory variable, not the absolute path name.