six cool things you can do with ibm http server for as/400 · six cool things you can do with ibm...

Six Cool Things you can do with IBM HTTPServer for AS/400By 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 onlyneed to use a few forms in the configuration program to get a working Web server up and runningon your AS/400 system, you may be wondering what some of the other features are that areavailable 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 thefeatures are available, should you decide to use them.

Server-side IncludesServer–side includes (SSI) enable the server to do some processing of Web pages before the serversends the page to a client. For example, the server can insert the following information into theHTML 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 FlowThe primary difference between an SSI–oriented request and an HTML request is that the server hasto process the SSI request in addition to the HTML request. Typically, when a client requests a Webpage, 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 SSIdirectives that are in the HTML document. When those directives are encountered, the serverperforms the additional work required before sending anything to the browser.

Configuring IBM HTTP Server for AS/400 to use SSIThe Basic form, shown in Figure 1, is used to configure SSI options. You get to the form by firstselecting your Web server configuration, then by clicking Basic. There are two groups of options forSSI 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 yourserver.

• Enable for both CGI scripts and files — SSI processing is enabled for both the output from CGIscripts 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/subtypefor SSI directives.

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

The directive associated with these options is Imbeds.

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

By selecting the text/x–ssi–html MIME type, you indicate to the server that you will differentiatefiles containing SSI directives by their file name extensions. The two commonly used file nameextensions for SSI are .htmls and .shtml. You don’t have to use those file name extensions; theyare simply the conventional extensions used for this purpose. You can associate whatever file nameextensions 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 serverconfiguration to use those file name extensions. You use the MIME types form shown in Figure 2 toenter the file name extensions and MIME type. You get to the form by clicking Languages andEncoding, 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–sideinclude processing for both the .htmls and .shtml file name extensions, you need to enter twoMIME types.

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

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

If most of your Web page files include one or more SSI directives (for example, to output thelast–modified date for the file), it may be more convenient to select the text/html option. Whenyou 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 DocumentsSSI directives are included in HTML files as HTML comments. The directive is embedded in thecomment. When the server processes the HTML file, it parses each directive in order and substitutesthe generated HTML at the point of the comment. When a directive is successfully parsed, theoriginal comment is removed from the resulting HTML that is sent to the browser. The reason forputting 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

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 ConsiderationsSome of the issues you should consider before deploying SSI are:

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

• Security — There are potential security exposures when users are allowed to processcommands or CGI programs using SSI. Be very careful when deciding which directoriescontain files with SSI directives, especially the exec directive.

User DirectoriesThe User Directories feature of IBM HTTP Server for AS/400 lets you assign a common directoryname 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 beaccessed 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 formby 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’shome directory. You will need to add the directory name you enter to each user’s home directory, ifthey 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 bestto limit the entry to a simple directory name. If you enter a path, you will need to create that pathstructure 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 willbe in each user's home directory.

Configure AS/400 User ProfileYou configure the user’s home directory using the Create User Profile (CRTUSRPRF) or Change UserProfile (CHGUSRPRF) command, HOMEDIR parameter, as shown in Figure 4. The home directory is notcreated when you use the CRTUSRPRF or CHGUSRPRF commands. You must create the home directoryfor each user in the AS/400 system IFS. You can use the Create Directory (CRTDIR) command or usethe 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 creatinga user home directory in either the QDLS or QOpenSys file systems because of the file naming rulesimposed by those file systems.

You must also add the user directory to the user’s home directory. For example, if the user directoryis specified as www (see Figure 3), you must use the CRTDIR command or the Windows 95/NTExplorer 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 commandto set the user's home directory.

User Directory Process FlowWhen 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 homedirectory. For example, suppose www is specified on the User directories form. If the user profile onthe AS/400 system has a HOMEDIR value of /dirname/, the server looks in the /dirname/wwwdirectory 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 thatyou want to associate with particular browser user–agent headers. By using this capability, you cancreate files that use features supported by recent versions of browsers. For example, you can usebrowser 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 beassociated 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 withfiles for a particular browser type. You include the extension in the name of the files that youcreate 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 createHTML files with either of these names:

Homepage.NSC.htmlHomepage.html.NSC

Whichever convention you adopt should be used for all browser–specific files on your serverfor 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 usedmultiple times. You cannot have any embedded blanks in the field; you must specify thewildcard character as a placeholder for blanks. The user–agent header field you specify iscase sensitive and must match the string sent from the browser for all positions that you areusing for the comparison.

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

The directive associated with this form is AddClient.

Examples of the User agent header fieldYou can specify as much or as little of the user–agent header field as you want to match. Forexample, to specify the user–agent header to detect some of the Netscape Navigator browsers youcan 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 includemore 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 BrowserIt is very difficult to determine what the possible user–agent header fields are that you mightencounter. A search on the Internet for a comprehensive list of browsers, their versions and theiruser–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 alsopossible 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 wantto review the agent logs for your site. Those logs contain the first 32 bytes of the user–agent headerfield, which can help identify the browsers being used to access your system. Unfortunately, some ofthe information you need to make an exact determination of the browser is located beyond the first32 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 instanceparameter when you start the HTTP server instance. The log is an AS/400 system spooled outputfile. You can scan that spool file for the string User-Agent. Using the server trace log for thispurpose is quite impractical, since the log can be enormously long, but the log can be used to getthe 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 nationallanguage code. When the client browser sends a request to the server, it indicates which nationallanguages it prefers (set by the user). The server can access the list of preferred languages andserve 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 filethat has an English version for the United States and another for Great Britain, you might havethese two files on your server:

About.html.engbAbout.html.enus

You associate the .engb and .enus extensions with the language code sent from the browser usingthis 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 languageidentifier sent from the browser. You can specify multiple file extensions for the samelanguage identifier if required.

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

The directive associated with this form is AddLanguage.

Serving Language Specific FilesWhen a user configures their browser, they will usually set the language preferences so that theirnative version of the language is listed first, then the "generic" version. For example, a browser userin 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 haveseveral national versions, then the "generic" version of the language.

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

About.html.engbAbout.html.enAbout.html

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

If the user’s browser is configured to look for Australian English first, then English, theAbout.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 documentwould be served.

Local CacheIBM HTTP Server for AS/400 provides an option to cache files that are located on your server. Youcan specify a list of files to load into the cache or simply enable the cache and allow files to becached as they are requested. You will probably find it beneficial to load frequently requested files onyour 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 byclicking 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 atserver start–up time. You can specify as many files as you want, within the limit of themaximum memory and maximum number of files to cache. You must specify the directoryand file name.

• Maximum memory for file caching — This option is used to set the maximum amount ofmemory the Web server can use for caching files. You can specify a memory cache up to32,767 MB in either kilobytes (K) or megabytes (M). The default setting is 2M. Memoryallocated 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 offiles to be stored in the cache. If this number is set to a higher number than the number offiles that are cached when the server starts, the server can continue to add files to the cacheas they are requested, until either the limit specified in this option is reached or themaximum 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 ornot 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 allchanges 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 checkthe file on disk to see if it is more recent before serving the file from the cache. If the file ondisk is more recent, the file in the cache is removed from the cache and the most recentversion (from disk) is served. If the cache is still within the limits of the maximum memoryand 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 anerror message to the browser. The error messages use standard HTTP error message numbers anddescriptions. Unfortunately, the error messages are not very descriptive and usually do not help theuser understand why the problem occurred and what, if anything, they can do to resolve theproblem.

IBM HTTP Server for AS/400 lets you assign customized HTML files for error messages. When theerror occurs, your customized error message is returned to the browser, rather than theserver–provided error message. You configure customized error messages using the Error messagecustomization form shown in Figure 8. You get to the form by clicking the Error messagecustomization 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 acustomized error message HTML file for as many of the error messages as you want. Although youneed to assign an error message file to each error condition that you want to customize, you canassign the same error message file to multiple error conditions if your customized error message isapplicable to multiple conditions.

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

The directive associated with this form is ErrorPage.

Give it a tryAlthough you should only use these features if you need them, you should be aware of as many ofthe options provided with IBM HTTP Server for AS/400 as possible. At some point, knowing how tocustomize your Web server may give you Web serving functionality that would otherwise be verydifficult to provide.

Copyright © 2003, Craig Pelkie. All Rights Reserved

No part of this presentation or the accompanying computer source code may be reproduced ordistributed in any form or by any means, or stored in a database or data retrieval system, withoutthe prior written permission of Craig Pelkie, who is the author of the presentation and the computersource code.

All computer source code distributed with this presentation, either on diskettes, CD-ROM, oravailable for downloading from sources such as the Internet is Copyright © 2003 Craig Pelkie, AllRights Reserved. The source code is for use in computer programs that you develop for internal usewithin your company, or for use within programs that you develop for the use of your clients, whensuch programs are compiled and distributed in an executable computer program such that no part ofthe source code is readily visible without the aid of a computer program disassembler. No part of thecomputer source code distributed with this presentation shall be reproduced in source code format,either printed or in electronic format, by you or by others who you allow to have access to thesource code. You shall not cause the source code to be stored on any information retrieval system,such as computer Bulletin Board Systems or the Internet. You shall not develop any written articles,books, seminar materials, or other presentations that include the source code provided on thediskettes accompanying this manual or within the manual itself.

For any questions regarding your rights and responsibilities using the computer source codedistributed with this presentation, contact Craig Pelkie, Rochester Initiative, who is the owner of thesource code.

LIMITATION OF LIABILITY AND DISCLAIMER OF WARRANTY

No representation is made that any of the programs, computer source code, commands, orconfigurations described and depicted in this manual and on the computer source codeaccompanying this presentation are error-free and suitable for any application that you maydevelop. Craig Pelkie makes no warranty of any kind, expressed or implied, including the warrantiesof merchantability or fitness for a particular purpose, with regard to the information, examples, andcomputer source code presented in this presentation and on the accompanying diskettes. Everythingprovided in this manual and on the accompanying diskettes is provided “as is”. Craig Pelkie shall notbe liable in any event for incidental or consequential damages or any other claims, pursuant to youruse of any of the techniques presented in this presentation, or your use of the computer source codein programs that you develop, even if Craig Pelkie has been advised of the possibility of suchdamages.

You are responsible for testing any and all programs, configurations, commands, and procedurespresented in this manual prior to using the programs, configurations, commands, and procedureswith important user data. You must ensure that adequate and sufficient backup of important userdata is available, in the event that recovery of the important user data is required.