Six Cool Things You can do with IBM HTTP Server for AS/400

By Craig Pelkie

One of the things you notice when you configure IBM HTTP Server for AS/400 using the browser-based administration and configuration program is that there are a lot of options. Although you only need to use a few forms in the configuration program to get a working Web server up and running on your AS/400 system, you may be wondering what some of the other features are that are available to you.

In this article, we’ll look at six features that were added to IBM HTTP Server for AS/400 at V4R3. The features are also available in the V4R4 version of the Web server:

Server-side includes
User directories
Automatic browser detection
Automatic language detection
Local cache
Error message customization

Although you may not have an immediate use for any of these features, it is useful to know that the features are available, should you decide to use them.

Server-side Includes

Server–side includes (SSI) enable the server to do some processing of Web pages before the server sends the page to a client. For example, the server can insert the following information into the HTML that is sent:

· Current date

· Size of the file

· Last change date of a file

You can also invoke CGI programs or Java servlets using server–side includes.

SSI and HTML Request Flow

The primary difference between an SSI–oriented request and an HTML request is that the server has to process the SSI request in addition to the HTML request. Typically, when a client requests a Web page, a static document is retrieved by the server and passed back to the browser

With SSI enabled, the server responds to requests for SSI documents by parsing the document SSI directives that are in the HTML document. When those directives are encountered, the server performs the additional work required before sending anything to the browser.

Configuring IBM HTTP Server for AS/400 to use SSI

The Basic form, shown in Figure 1, is used to configure SSI options. You get to the form by first selecting your Web server configuration, then by clicking Basic. There are two groups of options for SSI on the form.

Figure 1: Configure server-side includes on the Basic form.

Server-side includes

You can select one of the options to enable or disable SSI on your server. The options are:

· Disable — SSI processing is not enabled on your server. This is the default setting.

· Enable for CGI scripts only — SSI processing is enabled only for the output from CGI scripts.

· Enable for files only — SSI processing is enabled only for Web pages retrieved from your server.

· Enable for both CGI scripts and files — SSI processing is enabled for both the output from CGI scripts and for Web pages retrieved from your server.

Server side include options

You can select one of the options to indicate the Multipurpose Internet Mail Extensions (MIME) document type/subtype that will be parsed for server–side includes. The options are:

· text/x–ssi–html only — The server will only parse documents with this MIME type/subtype for SSI directives.

· text/html also — The server will parse documents with this MIME type/subtype and the text/x–ssi–html MIME type/subtype for SSI directives.

The directive associated with these options is Imbeds.

MIME Types Used with SSI

If you select the text/html MIME type option on the Basic form, there is nothing more you need to do to configure the server to use server–side includes. Every HTML document with a file name extension of .htm, .html and .htmls will be parsed for server–side include directives (the server is already configured to process those file name extensions; the .htmls extension is included so that if you use "legacy" server–side include documents you do not need to change their file name extension to .htm or .html.)

By selecting the text/x–ssi–html MIME type, you indicate to the server that you will differentiate files containing SSI directives by their file name extensions. The two commonly used file name extensions for SSI are .htmls and .shtml. You don’t have to use those file name extensions; they are simply the conventional extensions used for this purpose. You can associate whatever file name extensions you want with the text/x–ssi–html MIME type.

If you select the text/x–ssi–html option, you need to add the MIME types to your server configuration to use those file name extensions. You use the MIME types form shown in Figure 2 to enter the file name extensions and MIME type. You get to the form by clicking Languages and Encoding, then MIME types. On the MIME types form, enter the file extension, type and subtype. Leave the encoding and quality options set to their default values. If you want to enable server–side include processing for both the .htmls and .shtml file name extensions, you need to enter two MIME types.

Figure 2: Use the MIME types form to associate file name extensions with a MIME type/subtype.

Selecting the SSI Option to Use

If you have only a few Web page files that use SSI directives, it is probably best, for performance reasons, to use the text/x–ssi–html option and assign the file name extension .htmls or .shtml to those files.

If most of your Web page files include one or more SSI directives (for example, to output the last–modified date for the file), it may be more convenient to select the text/html option. When you select that option, every HTML file will be parsed to determine if it contains any SSI directives, but you will not have to remember to assign the .htmls or .shtml file name extension to the file.

Using SSI Directives in HTML Documents

SSI directives are included in HTML files as HTML comments. The directive is embedded in the comment. When the server processes the HTML file, it parses each directive in order and substitutes the generated HTML at the point of the comment. When a directive is successfully parsed, the original comment is removed from the resulting HTML that is sent to the browser. The reason for putting server–side include directives in comments is so that if server–side include processing fails, there are no extraneous tags or data sent to the browser.

The actual comment in HTML code looks like the following:

The initial characters <!--# are important, since the server parses the document for that sequence to locate SSI directives. The quotes around value are required only if there are embedded spaces in the entry.

The SSI directives supported by IBM HTTP Server for AS/400 are shown in Table 1. The HTTP Server for AS/400 Webmaster’ s Guide (GC41-5434) includes complete information about all of the options supported for each directive.

SSI Directive	Description
config	Used to control file processing. Tags include: cmntmsg – specify message appended to the beginning of text. errmsg – specify error message sent to client. sizefmt – specify file size format. timefmt – specify time and date format.
echo	Display the value of environment variables.
exec	Include the output of a CGI program in the HTML.
cgi	Specify the URL to a CGI program, the program name and parameters to the program.
flastmod	Display the date and time the file was last modified.
fsize	Display the file size.
global	Define global variables for use in this file or other included files.
include	Include another document in the output.
set	Set the value of a variable.

Table 1: SSI Directives

Examples of SSI Directives

The SSI directives in this example set the time and date format, then write the last–modified date of the file into the generated HTML:

As an example, this is generated into the HTML (and displayed in the browser):

14:14:17 09/27/99

This SSI directive is used to include the contents of the copyright.inc file in the generated HTML:

SSI Considerations

Some of the issues you should consider before deploying SSI are:

· Performance — SSI processing can impose a significant performance penalty, compared with serving files that do not use SSI. If your Web page development and maintenance strategy is to use the modular technique supported by SSI and if performance is not adequate, you may need to consider recoding your Web pages.

· Security — There are potential security exposures when users are allowed to process commands or CGI programs using SSI. Be very careful when deciding which directories contain files with SSI directives, especially the exec directive.

User Directories

The User Directories feature of IBM HTTP Server for AS/400 lets you assign a common directory name that will be included in the home directory associated with an AS/400 system user profile. Users can publish their private Web documents into that directory. The documents can then be accessed by using a URL such as the following:

http://myas400/~QPGMR/homepage.html

You do not have to configure Map or Pass directives to serve Web pages from the user directory.

The User directories form

The user directory option is set on the User directories form, shown in Figure 3. You get to the form by clicking Directories and Welcome Page, then User directories.

On the User directories form, enter the name of the directory that will be contained within the user’s home directory. You will need to add the directory name you enter to each user’s home directory, if they will be using the user directory capability.

Although you can enter a path for this entry (for example, dir1/dir2), you will probably find it best to limit the entry to a simple directory name. If you enter a path, you will need to create that path structure in each user’s home directory.

The directive associated with this form is UserDir.

Figure 3: The User directories form is used to set the name of the commmon user directory that will be in each user's home directory.

Configure AS/400 User Profile

You configure the user’s home directory using the Create User Profile (CRTUSRPRF) or Change User Profile (CHGUSRPRF) command, HOMEDIR parameter, as shown in Figure 4. The home directory is not created when you use the CRTUSRPRF or CHGUSRPRF commands. You must create the home directory for each user in the AS/400 system IFS. You can use the Create Directory (CRTDIR) command or use the Windows 95/NT Explorer program or Operations Navigator to create the user’s home directory.

The user’s home directory does not have to be on the root path of the IFS. You should avoid creating a user home directory in either the QDLS or QOpenSys file systems because of the file naming rules imposed by those file systems.

You must also add the user directory to the user’s home directory. For example, if the user directory is specified as www (see Figure 3), you must use the CRTDIR command or the Windows 95/NT Explorer or Operations Navigator to add that directory to the user’s home directory.

Figure 4: Use the HOMEDIR parameter on the Create User Profile or Change User Profile command to set the user's home directory.

User Directory Process Flow

When the server receives a URL request that includes /~username/ (substitute the name of the user, for example ~qpgmr), it looks for the requested object in the user subdirectory of the user's home directory. For example, suppose www is specified on the User directories form. If the user profile on the AS/400 system has a HOMEDIR value of /dirname/, the server looks in the /dirname/www directory and returns the requested document.

Automatic Browser Detection

The Automatic browser detection form shown in Figure 5 is used to enter a list of file extensions that you want to associate with particular browser user–agent headers. By using this capability, you can create files that use features supported by recent versions of browsers. For example, you can use browser detection to determine the level of support you provide in your documents for:

· HTML

· DHTML

· XML

· JavaScript

· VBScript and ActiveX

You get to the form by clicking Languages and Extensions, then Automatic browser detection.

Figure 5: Use the Automatic browser detection form to create a list of file extensions to be associated with a particular browser.

The options you can set on the Automatic browser detection form are:

· File extension — Enter the file extension (preceded by a period) that will be associated with files for a particular browser type. You include the extension in the name of the files that you create for that browser type. It does not matter which order the extension is in. For example, if you specify a value for this field of .NSC (for Netscape Navigator clients), you can create HTML files with either of these names:

Homepage.NSC.html

Homepage.html.NSC

Whichever convention you adopt should be used for all browser–specific files on your server for ease of maintenance.

· User agent header — Enter the user–agent string or partial string that identifies a browser. You can use the asterisk (*) character as a wildcard in this field. The wildcard can be used multiple times. You cannot have any embedded blanks in the field; you must specify the wildcard character as a placeholder for blanks. The user–agent header field you specify is case sensitive and must match the string sent from the browser for all positions that you are using for the comparison.

You can enter a list of several file extensions and user–agent headers. The order of the list is important, since the first matching user–agent header is used to determine the file extension that will be used.

The directive associated with this form is AddClient.

Examples of the User agent header field

You can specify as much or as little of the user–agent header field as you want to match. For example, to specify the user–agent header to detect some of the Netscape Navigator browsers you can enter the user–agent header like this:

Mozilla/*Nav*

If you want to match to a specific version of the Netscape Navigator browser, you need to include more match characters:

Mozilla/3.*

Mozilla/4.*Nav*

A user–agent header to detect Microsoft Internet Explorer version 4.0 looks like this:

Mozilla/*MSIE*4.0*

About the User–agent Header Data Sent from the Browser

It is very difficult to determine what the possible user–agent header fields are that you might encounter. A search on the Internet for a comprehensive list of browsers, their versions and their user–agent header field yields only small fragments of information.

The content of this field is not governed by any Internet standard; it is vendor–specific. It is also possible for users to override or reprogram their browsers so that the browser reports ("masquerades") a different user–agent header than that assigned by the vendor.

Before you invest too much time and effort in creating browser–specific documents, you may want to review the agent logs for your site. Those logs contain the first 32 bytes of the user–agent header field, which can help identify the browsers being used to access your system. Unfortunately, some of the information you need to make an exact determination of the browser is located beyond the first 32 bytes of the user–agent header field.

You can review the exact user–agent header field that your server received in the server trace logs. You indicate to the server that it is to produce a server trace log by entering the -vv server instance parameter when you start the HTTP server instance. The log is an AS/400 system spooled output file. You can scan that spool file for the string User-Agent. Using the server trace log for this purpose is quite impractical, since the log can be enormously long, but the log can be used to get the exact user–agent data after you have collected the initial data from the agent log.

automatic Language Detection

The Languages form shown in Figure 6 is used to associate a particular file extension with a national language code. When the client browser sends a request to the server, it indicates which national languages it prefers (set by the user). The server can access the list of preferred languages and serve a language–specific file to the user, if one is available on your server.

Figure 6: Use the Languages form to associated a file extension with a national language type.

You use a file extension to indicate the different file versions. For example, to serve an HTML file that has an English version for the United States and another for Great Britain, you might have these two files on your server:

About.html.engb

About.html.enus

You associate the .engb and .enus extensions with the language code sent from the browser using this form. You get to this form by clicking Languages and Encoding, then Languages.

The options you set on the Languages form are:

· File extension — Enter the file extension that you want to associate with a particular language identifier sent from the browser. You can specify multiple file extensions for the same language identifier if required.

· Language — Enter the language identifier that is sent from the browser. You can view the lists of language identifiers that are sent in the browser configuration dialogs. You must enter the language identifier in this field exactly as it is shown in the browser. Note that the browsers use different characters for the same language, for example, English (British) is en-GB in Netscape Navigator but en-gb in Microsoft Internet Explorer. If you intend to serve the same language–specific pages to the users of those browsers, you need to create an entry for each language.

The directive associated with this form is AddLanguage.

Serving Language Specific Files

When a user configures their browser, they will usually set the language preferences so that their native version of the language is listed first, then the "generic" version. For example, a browser user in England would select English/United Kingdom as their first preference, then English.

You can provide as many language specific files as you require. Most of the national languages have several national versions, then the "generic" version of the language.

For example, assume you have the following three documents on your server:

About.html.engb

About.html.en

About.html

If the user’s browser is configured to look for British English first, then English, the About.html.engb document would be served.

If the user’s browser is configured to look for Australian English first, then English, the About.html.en document would be served, since that is the best match.

Finally, if the user’s browser is configured to look for German documents, the About.html document would be served.

Local Cache

IBM HTTP Server for AS/400 provides an option to cache files that are located on your server. You can specify a list of files to load into the cache or simply enable the cache and allow files to be cached as they are requested. You will probably find it beneficial to load frequently requested files on your site, such as welcome files and their associated graphics, into the cache.

You configure the local cache using the Local caching form shown in Figure 7. You get to the form by clicking System Management, then Local caching.

Figure 7: Use the Local caching form to list files on your server to be cached.

The options you can set on the local caching form include:

· Files to be cached — You can add files to the list of files to be loaded into the local cache at server start–up time. You can specify as many files as you want, within the limit of the maximum memory and maximum number of files to cache. You must specify the directory and file name.

· Maximum memory for file caching — This option is used to set the maximum amount of memory the Web server can use for caching files. You can specify a memory cache up to 32,767 MB in either kilobytes (K) or megabytes (M). The default setting is 2M. Memory allocated to the cache is unavailable for other applications running on the server.

· Maximum number of files to cache — This option is used to indicate the maximum number of files to be stored in the cache. If this number is set to a higher number than the number of files that are cached when the server starts, the server can continue to add files to the cache as they are requested, until either the limit specified in this option is reached or the maximum amount of memory is used. The default setting for this option is 200.

· Update cache when a file is modified — This option is used to indicate to the server whether or not it should check for a more recent version of a file before serving the file from the cache. By default, this option is not checked, meaning that if an HTML document is updated on disk, the new page is not available to be served until the server is restarted. If you want all changes to be immediately available, you need to check this option.

If you do check this option, files cannot be served as quickly, since the server has to check the file on disk to see if it is more recent before serving the file from the cache. If the file on disk is more recent, the file in the cache is removed from the cache and the most recent version (from disk) is served. If the cache is still within the limits of the maximum memory and number of files, the more recent version of the file may be cached.

The directives associated with this form are CacheLocalFile, CacheLocalMaxBytes, CacheLocalMaxFiles and LiveLocalCache.

Error Message Customization

When an error occurs in response to a request from a client, IBM HTTP Server for AS/400 returns an error message to the browser. The error messages use standard HTTP error message numbers and descriptions. Unfortunately, the error messages are not very descriptive and usually do not help the user understand why the problem occurred and what, if anything, they can do to resolve the problem.

IBM HTTP Server for AS/400 lets you assign customized HTML files for error messages. When the error occurs, your customized error message is returned to the browser, rather than the server–provided error message. You configure customized error messages using the Error message customization form shown in Figure 8. You get to the form by clicking the Error message customization link.

Figure 8: You can assign a custom error message on the Error message customization form.

To assign a customized error message, select the error condition from the list displayed on the form, then enter the URL that points to the location of the error message HTML file. You can create a customized error message HTML file for as many of the error messages as you want. Although you need to assign an error message file to each error condition that you want to customize, you can assign the same error message file to multiple error conditions if your customized error message is applicable to multiple conditions.

The error message file is processed according to the mapping rules defined in the configuration file of the server. The error message file must be in a location that can be reached through the mapping rules defined by the Map, Pass, or Redirect directives. At a minimum, you need a Pass directive to allow the server to pass the error message file.

The directive associated with this form is ErrorPage.

Give it a try

Although you should only use these features if you need them, you should be aware of as many of the options provided with IBM HTTP Server for AS/400 as possible. At some point, knowing how to customize your Web server may give you Web serving functionality that would otherwise be very difficult to provide.

Craig Pelkie is a consultant based in Southern California. He has worked on a number of projects at IBM Rochester over the past year, including four Redbooks and two residencies about IBM HTTP Server for AS/400. In addition, he has recently completed authoring the course AS/400 Net.Data (course code S6178) for IBM Learning Services. His interests include AS/400 Web enablement, Enterprise Java Beans, and client/server programming for the AS/400. Craig is available for consulting and training engagements, and may be contacted at craig@web400.com.