Configuring Subject Search Server(TM):
Instructions for Web Masters

  1. Introduction
  2. SSServer Search Form
  3. Search Query Parameters
  4. Multi-language support in SSServer
  5. Remote Installation
  6. File types supported by SSServer
  7. System Requirements and SSServer Messages

    SSServer™ and Subject Search Server™ are trademarks of Kryloff Technologies, Inc.



1. Introduction

SSServer™ is a powerful search tool that automates the retrieval and selection of all the useful information available on your Web Site. SSServer allows to:

  1. Search for data based on users' questions. The resulting reports contain the most relevant data retrieved directly from your site. Furthermore, users may enter questions in the language of their choice (see also: Multi-language support in SSServer).
  2. Build maps of your site. SSServer formats and displays the map in an easy-to-understand and navigate hierarchy of directories.
SSServer is fully configurable: you may select a desired query form template, files and directories of your Web server to be scanned while searching, language of your documents, etc. Along with the traditional Literal Search approach, SSServer also supports the Subject Search method developed by Kryloff Technologies, which provides outstanding search quality! The Subject Search method works in more than 35 languages: we are proud of the work we have done and think that we provide the most comprehensive and easy-to-use language support available.

The general search procedure is as follows:

  1. You create a search form in one or several HTML-documents accessed from your Web server;
  2. Having loaded this form into a browser, your visitors type in queries and post the data onto your Web server;
  3. The server executes the file ssserver, which accepts the queries, scans an index of your files and responds with the resulting report;
  4. The Web server sends it back to the users, who are now given a powerful capability to search through your Web site.


2. Search Form

Below is an example form to be included in one or several HTML documents on your Web server. You may copy and paste this form into a temporary HTML document, then modify or translate its contents into another language (the form layout has been simplified).


Do not remove this reference:
Search on this site is provided by Kryloff Technologies, Inc.

Search phrase:

The rest of the FORM elements given below are optional; the default values are shown on the form and can be changed by modifying the configuration file "ssserver.ini":
Use search method: Subject Search (smart fuzzy) Literal Search (exact)
Report to you with: most relevant hits
Each quotation contains: characters
Extract no more than: quotations from the same document (relevant if the Subject Search method is selected)
Include quotes with the relevancy: (%) or higher (Subject Search only)
Search for: (Literal Search only)
Case sensitiveness: (Literal Search only)

Here's this search form contents in HTML format (unnecessary tags excluded):

<!-- To be included within the <body> tag of your HTML files -->
<FORM ACTION="cgi-bin/ssserver" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="CONFIG" VALUE="ssserver.ini">

Search on this site is provided by
<a href="http://www.kryltech.com">Kryloff Technologies, Inc.</a>
<!-- Do not remove the reference to Kryloff Technologies, Inc. -->

Search phrase: <INPUT TYPE="TEXT" NAME="QUERY" SIZE="72" MAXLENGTH="255" VALUE="">

The rest of the FORM elements given below are optional; the default values are 
shown on the form and can be changed by modifying the configuration file 
"ssserver.ini":<HR>

Use search method:
<INPUT TYPE="RADIO" NAME="METHOD" VALUE="FUZZY" CHECKED>Subject Search (smart fuzzy)
<INPUT TYPE="RADIO" NAME="METHOD" VALUE="EXACT">Literal Search (exact)

Report to you with:
<SELECT NAME="QUOTES">
<OPTION>10
<OPTION SELECTED>25
<OPTION>50
<OPTION>100
<OPTION>250
<OPTION>500
<OPTION>1000
</SELECT>
most relevant hits

Each quotation contains:
<SELECT NAME="QUOTESIZE">
<OPTION>100
<OPTION>500
<OPTION SELECTED>1000
<OPTION>2500
<OPTION>5000
</SELECT>
characters

Extract no more than:
<SELECT NAME="QUOTESPERDOC">
<OPTION>1
<OPTION>2
<OPTION>3
<OPTION>4
<OPTION SELECTED>5
<OPTION>6
<OPTION>7
<OPTION>8
<OPTION>9
<OPTION>10
<OPTION>11
<OPTION>12
<OPTION>13
<OPTION>14
<OPTION>15
</SELECT>
quotations from the same document (relevant if the Subject Search method is selected)

Include quotes with the relevancy:
<SELECT NAME="RELEVANCY">
<OPTION>10
<OPTION>20
<OPTION>30
<OPTION SELECTED>40
<OPTION>50
<OPTION>60
<OPTION>70
<OPTION>80
<OPTION>90
<OPTION>100
</SELECT> (%) or higher (Subject Search only)

Search for:
<SELECT NAME="TERMS">
<OPTION VALUE="ANY">for any term
<OPTION VALUE="ALL" SELECTED>for all terms
<OPTION VALUE="PHRASE">as a phrase
</SELECT> (Literal Search only)

Case sensitiveness:
<SELECT NAME="CASE">
<OPTION VALUE="INSENSITIVE" SELECTED>case insensitive
<OPTION VALUE="SENSITIVE">case sensitive
</SELECT> (Literal Search only)

<INPUT TYPE="SUBMIT" NAME="SEARCH" VALUE="Search">
<INPUT TYPE="SUBMIT" NAME="SITEMAP" VALUE="Site Map">
<INPUT TYPE="SUBMIT" NAME="HELP" VALUE="Help">
</FORM>



3. Search Query Parameters

SSServer processes query strings posted on the application by a remote browser when the user presses any of the SUBMIT buttons on the search query form. The query string should contain all or any of the following parameters:

QUERY=<query string>
CONFIG=<configuration file name>
TEMPLATE=<search form template file name>
LANGUAGE=<language dictionary file name>
FILELIST=<name of the file, which lists files/directories to be searched>
HELPFILE=<name of the End-User Help file>
HEADER=<name of the file containing the heading for SSServer reports>
FOOTER=<name of the footer file for SSServer reports>
SITEROOTURL=<your Web server's Internet address>
WORKDIR=<directory, in which SSServer keeps temporary and work files>
ACTION=<action>
QUOTES=<number of quotes to generate>
QUOTESIZE=<quotation size>
QUOTESPERDOC=<max. number of quotes that can be extracted from the same file>
METHOD=<search method>
RELEVANCY=<relevancy in the range 0-100>
TERMS=<Literal Search option>
CASE=<Literal Search option>
ALLOWSITEMAP=<YES or NO>

The description of each of the parameters follows:

  • QUERY contains a question that remote users (visitors to your Web site) enter into the form with a browser. The default value is 'NoPhrase'; this is the only unconditional parameter which is required to process queries; the rest of the parameters are optional and may or may not be present in query strings.

  • CONFIG points out the configuration file, for example: "CONFIG=/usr/local/www/cgi-bin/ssserverdata/ssserver.ini". The file path is relative to the ssserverdata subdirectory of the directory, in which ssserver has been installed. Under this example, having just "CONFIG=ssserver.ini" is enough if the full path for ssserver is /usr/local/www/cgi-bin/ssserver.

    This file contains all or any of the query string parameters (except for the CONFIG option, again: recursion is not allowed). Each parameter occupies one line. Example:
    TEMPLATE=template.txt
    LANGUAGE=English.ssl
    FILELIST=filelist.txt
    HELPFILE=help.htm
    HEADER=header.txt
    FOOTER=footer.txt
    SITEROOTURL=http://www.mycompany.com
    WORKDIR=workdir/
    ALLOWSITEMAP=NO

    It is not usually necessary to include such parameters as QUOTES or ACTION because they are primarily selected by site visitors. However, if you have simplified the Search Query form and some of the options are not now selectable by users, the default values for them may be set in the configuration file. For example: the statement METHOD=FUZZY in the configuration file instructs SSServer to use the Subject Search Method.

    The default value for the CONFIG parameter is not defined, e.g. SSServer does not look for or read configuration files automatically. This means that in order to reassign the default values for query string parameters, your search query form should contain a reference to the configuration file; this reference should be present as the very first and invisible statement in the search query form. For example:
    <INPUT TYPE="HIDDEN" NAME="CONFIG" VALUE="ssserver.ini">

    Basically, configuration file is used to define search string parameters that are common to all queries and cannot be changed by site visitors. For example, if a number of pages on your server are in Latin, and you want your visitors to be able to search in this language, the configuration file for the corresponding Search in Latin form should contain the statement: "LANGUAGE=Latin.ssl". Apart from assigning the defaults, you may use configuration files to prevent visitors from obtaining your site map. Just include the statement "ALLOWSITEMAP=No" in it.

  • TEMPLATE points out a file that contains a new search form template. The content of this file is placed in the end of SSServer reports for user convenience: having done a search and read the report, a user can immediately issue another search as a new search form always appears on the bottom. The default is template.txt (all file paths are relative to the ssserverdata subdirectory of the SSServer root directory). For your convenience SSServer is shipped with 8 different templates (template1.txt .. template8.txt).

  • LANGUAGE specifies the language of your Web site documents. You should specify the corresponding language dictionary, for example: "LANGUAGE=/usr/local/www/cgi-bin/ssserverdata/Latin.ssl". The default language dictionary is English.ssl; its file path is relative to the ssserverdata subdirectory of the SSServer root directory.

    Important: Your visitors should enter questions in the language of your Web site documents and also in the same encoding if your language allows using different coding tables. You should keep in mind that SSServer does not translate questions into English nor does it perform encoding of any sort. If your Web page contains documents in more than one language, you may create several search forms for each group as is described in the section Frequently Asked Questions, question 11.
    See also: Multi-language support in Kryloff Technologies' products.

  • FILELIST specifies the name of the file, which lists documents to be searched by SSServer. This file must exist on your server; by default, it is filelist.txt. The file path is relative to the ssserverdata subdirectory of the SSServer root directory. If you have renamed this file or placed it in another directory, you should specify its full or relative path, for example: /usr/local/www/cgi-bin/ssserverdata/myfilelist.txt

    This file contains a sequence of paired lines, which should follow right after each other. Each pair can be either:

    FILE=<local file name>
    URL=<Internet address of this file>
    
    or
    
    DIR=<name of the local directory>
    URL=<Internet address of this directory>
    
    The pairs point out a local file or a directory on your Web server and a URL which corresponds to the file or directory.
    Important: The "DIR=" instruction causes SSServer to process all the files in this directory (not including subdirectories). If some of them should not be scanned while searching, use a sequence of "FILE=" instructions, instead.

    Example file filelist.txt:
    Dir=/usr/local/www/data
    URL=http://www.kryltech.com/
    
    Dir=/usr/local/www/data/download
    URL=http://www.kryltech.com/download/
    
    File=/usr/local/www/data/samples/getid.htm
    URL=http://www.kryltech.com/samples/getid.htm
    
    In this example SSServer searches in ALL files from directory /usr/local/www/data, directory /usr/local/www/data/download, and also in the file /usr/local/www/data/samples/getid.htm. SSServer does not automatically scan subdirectories, so pointing out the download subdirectory is obligatory if you want SSServer to scan it as well. For the Dir= instructions, SSServer appends local file names to their directory's Internet address (URL) to obtain the URL's of each file within the directory.

  • HELPFILE specifies the name of the file, which SSServer displays when user presses on the HELP button in the Search Query form. By default, it is help.htm. You may translate it into another language if required.
    See also:
    Multi-language support in Kryloff Technologies' products.

  • HEADER
    SSServer generates reports in a manner that lets you customize the report layout to your own requirements, namely: you may change or add a header to each report, control the report background and colors, position on screen, etc. Adding a proper heading section makes your visitors feel as if they are "staying in your site" while reading SSServer reports and makes the reports fit into the overall design of your site.

    The Header parameter specifies the file whose contents will be placed on top of each SSServer report. This file must contain the <HTML> and <BODY> tags. The default value for this option is header.txt; the file path is relative to ssserverdata subdirectory of the directory, in which ssserver has been installed.

    Example file header.txt:
    <html>
    <head>
    <title>SSServer(TM) Search Results</title>
    <!-- the STYLE tag below is placed here to minimize space occupied
         by quotations; you may remove it if it does not match the style
         that you use in other documents on your site. -->
    <STYLE TYPE="TEXT/CSS"><!--
    H1,H2,H3 {font-size:14pt; margin:0pt}
    H4,H5,H6,P {margin:0pt}
    UL,OL,DL {margin-top:0pt; margin-bottom:0pt}
    --></STYLE>
    </head>
    <body BGCOLOR="#FFFFFF" LINK="#0000FF" ALINK="#FF0000" VLINK="#990099"
          TOPMARGIN=2 LEFTMARGIN=4 MARGINHEIGHT=2 MARGINWIDTH=4>
    

  • FOOTER specifies the name of the file, which SSServer appends to the search reports. Typically, this file contains just the </BODY> and </HTML> tags to meet the HTML requirements. If other tags are included in the header section, the corresponding terminating tags must be also present in the footer file. By default, SSServer appends file footer.txt; its path is relative to ssserverdata subdirectory of the directory, in which ssserver has been installed.

    Example (file footer.txt):
    <!-- place here other end-tags if required -->
    </body>
    </html>
    

  • SITEROOTURL specifies the Internet address (URL) of your site. The default value http://siteurl.com, obviously, should be reassigned in the SSServer configuration file.

  • WORKDIR selects a working directory for ssserver, in which the application should be allowed to create, read, modify and delete temporary files. By default, SSServer creates the subdirectory ssserverdata/workdir/ of its root directory. The contents of this directory are fully controlled by ssserver: do not modify it.

  • ACTION instructs SSServer what it should do: to perform a search, to generate a map of your site or to respond with the contents of the HELP file (see the HELPFILE parameter above).
    If there is no parameter in the query string which stands for ACTION, by default ssserver does a search. If generating site maps is not allowed on your server (see ALLOWSITEMAP below), ssserver responds with a warning message. Allowed values include:
    1. SEARCH=<just Search or another value that corresponds to your language>;
    2. SITEMAP=<Site Map or its translation into another language>;
    3. HELP=<Help or any corresponding string>

    For example, when ssserver detects the "SEARCH=something" substring in the query string, it searches for data.

  • QUOTES
    This parameter selects the maximum number of hits a user can receive in the search report (25, by default).

  • QUOTESIZE selects the size of quotations to be placed in the search report (in characters). The default value for this parameter is 1,000 characters.

  • QUOTESPERDOC specifies number of quotations from the same document which SSServer can extract and place in the search report. The lowest value of this option (set to 1) does not allow SSServer to quote the same document twice or more even if the corresponding document brings up the same subject many times in different paragraphs. This option mostly affects quoting long documents. By default, SSServer can quote the same document no more than 5 times.

  • METHOD selects search method SSServer should use while processing a query; can be either:
    1. METHOD=FUZZY (for Subject Search; this method is used by default) or
    2. METHOD=EXACT (for Literal Search).

    SSServer™ supports two types of searches: Subject Search and Literal Search. Developed by Kryloff Technologies, Inc., the Subject Search method is the intelligent and the most powerful way of information retrieval. The core Subject Search technique is also used in the rest of Kryloff Technologies' products known as Subject Search Suite™. This method accepts natural language enquiries and is used by default, so it is unlikely that you would need to change it.

    In addition to Subject Search, SSServer™ supports the traditional Literal Search approach. Visitors can use this method while looking for digits, number, names, etc. Using this method, SSServer extracts quotations "as is". Unlike to the Subject Search approach, if a user is looking for "John Griffiths" on your pages, Literal Search method does not select "Jon Griffit". This feature can be also quite useful in a number of cases, so it is recommended that you allow visitors to use both search methods: do not remove the corresponding radio-buttons from the search query form unless your documents do not have enough space.

  • RELEVANCY
    The Relevancy parameter (Minimum percentage of relevancy) is only relevant to those queries for which the
    Subject Search method is selected. SSServer generates reports with the most relevant quotes/extracts from your documents. Each quotation is ranked for relevancy with some value in the 0%-100% range. This option instructs SSServer to skip those quotations which do not exceed the value specified by this parameter. The higher the value, the fewer quotes. The default value is 40.

  • TERMS
    This parameter specifies additional options for the
    Literal Search method. The following values of this option are allowed:
    1. TERMS=ANY (instructs SSServer to search for any term in user's query);
    2. TERMS=ALL (SSServer searches for all terms, by default);
    3. TERMS=PHRASE (search for occurrences of the entire phrase)

  • CASE specifies additional options for the Literal Search method. Allowed settings are either "Sensitive" or "Insensitive":
    1. CASE=SENSITIVE instructs SSServer™ to treat uppercase and lowercase letters equally;
    2. CASE=INSENSITIVE causes SSServer™ to make a distinction between "A" and "a", "B" and "b", etc.
    Important: this option is supported not only in English but also in all European languages (see Multi-language support in Kryloff Technologies' products to obtain the full list of languages).

  • ALLOWSITEMAP allows or forbids generating site maps. If the configuration file contains the line "ALLOWSITEMAP=NO", ssserver prevents visitors from obtaining your site map. By default, SSServer is allowed to generate site maps on user's request.



    4. Multi-language support in SSServer™

    SSServer version 1.0 is able to search in the following languages:
    Afrikaans
    Bulgarian
    Catalan
    Chinese (Traditional Big5 encoding)
    Czech
    Danish
    Dutch (standard and Belgian)
    English (all dialects)
    Estonian
    Finnish
    French (all dialects)
    German (all dialects)
    Greek (standard)
    Greek (Latin encoding)
    Hebrew
    Hungarian
    Icelandic
    Indonesian
    Irish
    Italian (standard and Swiss)
    Japanese (Shift-JIS encoding)
    Japanese (EUC encoding)
    Korean (EUC encoding)
    Latin
    Latvian
    Lithuanian
    Norwegian (Bokmal and Nynorsk)
    Polish
    Portuguese (standard and Brazilian)
    Romanian
    Russian (Windows encoding)
    Russian (KOI-8 encoding)
    Slovak
    Spanish (all dialects)
    Swedish
    Turkish
    

    Since Kryloff Technologies is constantly improving its Muli-Language Support, it is recommended that you visit our Muli-Language Support Page to obtain additional languages dictionaries if your language is not yet listed above.



    5. Remote Installation

    Even in the case when your Web site is hosted on a remote computer and you do not have permission to add the package to the system, you can still properly install and use SSServer. Obviously, the best and the easiest way is to ask your Web administrator to do it. But, if you have remote access to your Web server (typically, via FTP), you can do it yourself! Just extract the original SSServer archive into a temporary directory on your "home" PC, which may be running any operating system, not obligatory FreeBSD.

    Then locate SSServer files in the www/cgi-bin subdirectory and upload them to your Web server (including the ssserverdata subdirectory). Make sure that the Web server application can execute files from the directory, in which you have uploaded the SSServer files. Upon completing these steps, you may use your web browser to run SSServer configuration utility sssconf located in the ssserverdata subdirectory. Finally, when configuring SSServer is finished, your visitors will be able to use the search form and search your site!


    6. File types supported by SSServer™.

    SSServer v1.0 is able to search files written in Hyper-Text Markup language as well as standard ASCII text files. File names do not obligatory have to end up with ".HTM", ".HTML" or ".TXT" extension: the application automatically detects the type of each file it processes.

    Despite the fact that SSServer does not internally support other file types, you may still make it process files written under ANY data storage format such as Rich Text Format (.RTF), Portable Data Format (.PDF), etc. For each "external" file you may create a corresponding text file containing just the textual information of the original one. Then, edit the SSServer File List (usually, it is the file ssserverdata/filelist.txt), and replace the local "external" file name with the name of its textual copy. After these changes, SSServer will search for queries in text files while supply its findings with the references to the original ones!

    Example: say your Web site contains the file ExternalFile.RTF in Rich Text Format and you want SSServer to search in it as well. Do the following:

    1. Using the SSServer File List Editor, first, include ExternalFile.RTF into the list of files to be processed. After this, the file filelist.txt will contain:
       ...
      FILE=ExternalFile.RTF
      URL=http://www.mysiteurl.com/ExternalFile.RTF
       ... 

    2. Then, create a text file ExternalFile.TXT and copy the contents of ExternalFile.RTF into it.

    3. Finally, replace the string ExternalFile.RTF with ExternalFile.TXT:
       ...
      FILE=ExternalFile.TXT
      URL=http://www.mysiteurl.com/ExternalFile.RTF
       ... 

    This "trick" makes SSServer search the file ExternalFile.TXT and extract quotations from it but then include the link to the original file http://www.mysiteurl.com/ExternalFile.RTF in the resulting reports!

    To create text files, you may use our GetText utility available for free downloading at http://www.kryltech.com/freestf.htm


    7. System Requirements and SSServer™ Messages.

    SSServer functions under the following environment:

    SSServer automatically builds file indexes (or deletes them if required) in its working directory. If some of your documents have been modified, SSServer automatically rebuilds the corresponding index files. The only case you should be careful of is the situation when you delete documents from your Web server. If, having deleted some document, you do not also delete the corresponding "FILE=" statement in the file list, SSServer starts generating a warning message "Error reading file XXX" in each report.

    Important: To prevent your visitors from seeing error messages, it is strongly recommended that you issue at least one query right after deleting any files or modifying SSServer configuration files (filelist.txt, ssserver.ini or template.txt). If you do not see any error messages in the report, all changes have been done correctly and your visitors will not see any error or warning messages either.

    If you issue a query for the very first time, it may take a while as none of your documents have been indexed yet. All subsequent searches are done much faster. Index files occupy approximately as much space as the original documents, so make sure that there is enough disk space on the drive in which you have installed SSServer.

    Other possible SSServer messages are described in section: Troubleshooting and Frequently Asked Questions: Instruction for Web Masters

    Developer (manufacturer) is Kryloff Technologies, Inc.