Skip to main content

 
IBM Power Systems software  >  IBM i  > Software  > 

HTTP Server for i

Secure, powerful, and complete

  
Overview Getting Started Documentation Support

iSeries Webserver Search Engine - National Language Support

Setting up the Search Engine to Run on Your Web Site

This page contains the documentation that is specific to adding a search to your web site. Be sure to read iSeries Webserver Search Engine - Getting Started before starting the setup.

Once you have worked with the search engine using the HTTP Server Administration and Configuration forms, you are ready to add the search function to your own web site. You will need do the following:

  1. Create or modify the HTTP server that is running your site so that it can run the sample search Net.Data macro.
  2. Create a search index for your documents.
  3. Copy the sample search macro to your own directory.
  4. Modify the sample search macro to use your index.
  5. Add a search box to your web page using the sample search html.
Follow these steps, modifying the example when necessary.
  • Create a server to run your web site.
  • Use your web browser to access the iSeries Tasks page by specifying the URL http://yourserver.com:2001 where yourserver.com is the domain name of your iSeries system.
  • Select the icon for IBM HTTP Server for i.
  • Select the icon for Administration to create a new server or Configuration to update an existing server.
  • To create a new server instance, select Create HTTP Server and use the wizard to create a server powered by Apache or an original server. For both server types, the wizard will perform some of the configuration steps. Be sure to enter the port number for your server.
  • If you are running the search on an Original server, continue with the next few steps. If you are running the search on an Apache server, follow the instructions in Set up for running the sample search macro on an Apache Server. Then skip to the steps to Create a search index for your documents.
  • If you are using an original server, select Configuration to display all the necessary forms.
  • Press Apply.
  • Select your new configuration then Request processing.
  • Under Request processing, select Methods and check the POST box.
  • Press Apply.
  • Under Request processing, select Request routing to define the required directives for Net.Data as well as Pass directives.
  • Insert the two request routing rules before the directive Pass /* /www/myserver/* added by the wizard. (V5R1 only)
    Map /cgi-bin/db2www/*
    /QSYS.LIB/QHTTPSVR.LIB/DB2WWW.PGM/mydir/macro/*
 Exec /QSYS.LIB/QHTTPSVR.LIB/*
  • Insert at least one Pass directive so that documents that appear in the search results can be displayed. .
  • Press Apply.
  • Now that you have your server configured, continue here to create the index.
  • *** Create a search index for your documents. ***
  • Click on Search Setup to display the administration tasks that can be performed.
  • Select the option to Create a search index and fill in the following fields:
    The Index Name.

The Index Directory (or use the default).
The Index Description (optional).
  • Press Apply.
  • On the next form, enter the directory name containing the files you want indexed, such as the sample recipe files in the Build a document list field from this directory field.See also Indexing your own document directory.
  • Select the index attributes you want to use.
  • Click the radio button to Create a mapping rules file from this HTTP server.
  • Select the HTTP server you just created.
  • Enter the Prefix to use for URL address or leave it blank .
  • Press Apply.
  • Next you will copy the sample search macro to your own directory.
    1. Create directory /mydir/macro where the sample macro will be copied.
    2. Copy the file. CPY OBJ('/QIBM/ProdData/HTTP/Public/HTTPSVR/sample_search.ndm') TODIR(' /mydir/macro') .
  • Modify the sample search macro to use your index and index directory. See Modifying the sample search Net.Data macro for more details.
  • Add a search box to your web page using the sample search html. See Sample HTML
  • Start the HTTP server by returning to Administration..
  • Under General Server Administration, select Manage HTTP Servers.
  • Select your server and press the Start button.
  • Now you are ready to test your site. Bring up a browser and enter the URL for your web page, for example, http://myserver:80/cgi-bin/db2www/sample_search.ndm/simple.

 Indexing your own document directory

Indexing your own document directory is similar to indexing the sample recipe files. The index can be built in the default /QIBM/UserData/HTTPSVR/index directory or a directory of your choice. Use an index name that describes the type of information indexed and use the description field for additional information. Specify your document directory in the Build a document list from this directory field on the Create search index form. If you want a subset of the documents in this directory, you can use the Document filter field to limit the files to a specific extension such as *.htm* . Wildcard characters are allowed.

You can also build your own document list on the Build document list form and use the resulting document list file name in the Use the Document list in this file field on the Create search index form. Be sure to click the button next to this field.

Note: It is best to index only HTML or text files. Other file types such as *.gif files will consume a large amount of system storage when they are indexed.

If you want to be able to view the documents found on a search from the HTTP Server Configuration and Administration form, you will have to build a mapping rules file for this index selecting the webserver configuration that will be used to serve your documents. This mapping rules file can be built from the Create search index or from the Build URL mapping rules file form. See URL Mapping Rules File.

 Modifying the sample search Net.Data macro

This section describes how to modify the sample Net.Data macro that you can use on your own web page to do searches and show the results.

Search indexes are built by the webserver administrator using the Search Administration section of the IBM HTTP Server Configuration and Administration forms. The webserver administrator can also test the index using these same forms. However, in order to make a search index available to others or to the general public, a separate search macro must be created so that this new index can be served from a webserver other than the ADMIN server.

To make creating this search macro easier, a sample Net.Data macro is provided with the Webserver Search Engine product. It will produce pages similar to those displayed when you are using Search index in the Search administration forms. It can be found at:

/QIBM/ProdData/HTTP/Public/HTTPSVR/sample_search.ndm

The sample macro contains instructions for updating it. Additionally, it provides more information about the various parameters that are required for the call to the search index program.

In most cases you will have to create a search macro for each search index you create. To do so, follow these steps:

  • Copy the sample macro to a directory of your choice. For example, / mydirectory/macros/mysearch.ndm. Make sure this directory is accessible to the webserver. It should have *PUBLIC *RX authority.
  • Use the EDTF command on the iSeries to modify the macro.
  • There are instructions in the macro you copied that help you determine what to modify. Essentially, there are three steps.
    1. Specify the name and directory of the search index to be used by this macro. You can also specify a mapping rules file name if different from the default: index_directory/index_name.MAP_FILE. If not, leave it blank.
    2. Modify the look and feel of the search form that will be presented to the user. You will likely do this to minimize the number of decisions the user has to make. To do this, remove the input field you do not want displayed on the form and add an associated hidden field with the default value you would like to assign to that parameter. A rudimentary knowledge of HTML is required for this step.
    3. Modify the look and feel of the results form. There is quite a bit of information returned for every document, but perhaps you wish not to display it all or you would like to format it in a way that is consistent with the rest of your web site. The Net.Data macro gives you great flexibility to format the results the way you wish. This step requires a rudimentary knowledge of the Net.Data macro language. Refer to the Net.Data web site for documentation and information on Net.Data.
  • Ensure you have a webserver configured to run Net.Data and the search. Verify that your webserver configuration has the the correct information. If you are running search on an Original server, select your configuration from the list on the IBM HTTP Server Configuration and Administration page. (For Apache, see Set up for running the sample search macro on an Apache Server.) Then select to Display configuration. Your configuration should contain the following two request routing rules
     Map /cgi-bin/db2www/*
    /QSYS.LIB/QHTTPSVR.LIB/DB2WWW.PGM/*
    Exec /QSYS.LIB/QHTTPSVR.LIB/*

    The Map directives map entries using the format /cgi-bin/db2www/* to the library where the Net.Data program resides on your system. (The asterisk (*) at the end of the string refers to anything that follows the string.)

    • Post enabled. There should be a line Enable POST
    • One Pass directive to allow documents that are found to be displayed.
    See URL Mapping Rules File section for more information.
  • Execute the macro from your browser using the following URL: http://myserver.com:port/cgi-bin/db2www/mydirectory/macros/mysearch.ndm/simple where myserver.com is the domain name for your system, port is the port number used by your webserver instance if different than 80, mydirectory/macros/mysearch.ndm is the path and name of your search macro and simple specifies the simple search form. You could also have specified advanced to request the advanced search form.
If you have existing web pages that you wish to modify to include a search form, you will have to add the appropriate HTML to provide an input field in which a user can enter the search terms and a button to submit the search request. Below is a sample html page which can be copied into your web page and modified for your search index. You should modify the ACTION parameter on the FORM tag to specify the location of your search macro as follows: ACTION="http://myserver.com:port/cgi-bin/db2www/mydirectory/macros/mysearch.ndm/output". You would also modify the frmIndexName and frmDir hidden variables to reflect the name and directory of your index.

Sample HTML

A sample HTML file /QIBM/ProdData/HTTP/Public/HTTPSVR/sample_html.html is available that you can insert into your existing web page or use as-is. All you have to change are the values for the ACTION (path to the Net.Data program along with the directory containing the search macro), the name of your index (frmIndexName variable) and your index directory (frmDir variable).

<html> 
<head> 
<title>Search for documents</title>; 
</head> 
<body bgcolor="#FFFFFF"> 
<h2>Search for documents</h2> <!--  Modify the following action to reflect the name of your search macro  --> 
<!--  This can be a complete URL or a relative URL                                  --> 
<FORM NAME="search"    ACTION="/cgi-bin/db2www/qibm/proddata/http/public/httpsvr/sample_search.ndm/output"    METHOD="post"> 
<!-- The following fields must be provided to the search macro, either as hidden fields or input fields  --> 
<!--    Modify the index name and directory appropriately for the index being searched                     --> 
<INPUT TYPE="hidden" NAME="frmIndexName" VALUE="Recipes"> 
<INPUT TYPE="hidden" NAME="frmDir" VALUE="/QIBM/UserData/HTTPSVR/index"> 
<INPUT TYPE="hidden" NAME="frmMapFile" VALUE=""> 
<INPUT TYPE="hidden" NAME="frmQueryType" VALUE="simple"> 
<INPUT TYPE="hidden" NAME="frmStartNum" VALUE="1"> 
<INPUT TYPE="hidden" NAME="frmPreference" VALUE="wildcard"> 
<INPUT TYPE="hidden" NAME="frmCaseSensitive" VALUE="no"> 
<INPUT TYPE="hidden" NAME="frmStemming" VALUE="no"> 
<INPUT TYPE="hidden" NAME="frmLogical" VALUE="AND"> 
<INPUT TYPE="hidden" NAME="frmPrecision" VALUE="100"> 
<INPUT TYPE="hidden" NAME="frmMaxCount" VALUE="10"> 
<!-- Fields added for new enhancements -->
<INPUT TYPE="hidden" NAME="frmFieldName" VALUE="BODY">
<INPUT TYPE="hidden" NAME="frmSortOrder" VALUE="SORT_BY_RANK">
<INPUT TYPE="hidden" NAME="frmAscDesc" VALUE="DESCENDING">

<table> 
<tr><td><b>Enter search terms :</b></td> 
</tr> 
<tr><td><INPUT TYPE="text" SIZE=50 NAME="frmSearchString" VALUE=""></td> 
<td><INPUT TYPE="submit" NAME="Submit" VALUE="Search" ></td></tr> 
</table> 
</FORM> 
</BODY> 
</HTML>