Index Server provides a rich set of variables that can be set or referred to in .idq and .htx files. This appendix presents the following:
Following are the variables that can be set in the .idq file or as CGI variables and referred to in the .htx file. They can also be set as variables in forms or given as parameters to a direct execution of the .idq file.
CiCatalog sets the location of the catalog (index) to use. If CiCatalog is not set, the catalog location defaults to the value in the registry (if it is set). If the registry value is not set, the catalog location defaults to the value of CiScope.
CiColumns contains those column names (such as property friendly names) that are available for reference within .htx files. In other words, it is a list of output columns available in the .htx file.
The format of CiColumns consists of a list of names separated by columns as follows:
CiColumns=name,rank,size
This list can contain up to 50 names. No duplicate names are allowed. Different friendly names that refer to the same property are considered to be duplicates and are not allowed.
CiDeferNonIndexedTrimming specifies whether additional non-index tests are to be performed during index retrieval if the number of matches exceeds CiMaxRecordsInResultSet. Therefore, the value of this variable has implications for query performance.
Culling of records (trimming) in the result can be performed after using the index to find potential matches. Scope, property values, and security are types of matching that are commonly used to perform this trimming. For queries that are sorted in descending order by rank, the entire set of objects is searched to locate the top CiMaxRecordsInResultSet records. However, these records cannot include objects that have failed post-index trimming. Therefore, it is possible that many thousands of objects must be examined and trimmed, which is a very resource-intensive operation.
Trimming during index retrievals can be deferred by setting CiDeferNonIndexedTrimming to TRUE. This causes Index Server to first locate the top CiMaxRecordsInResultSet records in the index and to trim just this set. The result set often contains fewer than CiMaxRecordsInResultSet records in it. Any results that are missed by deferring trimming are guaranteed to be of lower rank than those in the result set. The best results will always be returned.
CiDeferNonIndexedTrimming should only be set TRUE when the scope of the query is set to CiScope=/ and it is expected that no property value clauses are used in queries (that is, queries are pure content queries) and most of the results are accessible by the user. This is common on most Web sites. If fact, using an appropriate site layout with properly designed query forms and .idq files can assure that this is the case.
The value of CiFlags determines the depth of a search. Setting CiFlags to SHALLOW causes only the directory specified by CiScope to be searched. Setting CiFlags to DEEP causes the directory specified by CiScope as well as all subdirectories within that directory to be searched.
Setting CiForceUseCi=TRUE forces the query to use only the content index, regardless of whether it is out of date (documents have been added or documents have been modified since the last index update).
CiLocale defines which locale issues the query. Standard HTML locale encoding is supported. Table B.2 (in a subsequent section of this appendix) provides a full list of locale string values.
CiMaxRecordsInResultSet specifies the maximum number of query results, or hits, to return in the result set.
CiMaxRecordsPerPage specifies the maximum number of result records to display on each HTML page sent to the user.
CiRestriction contains the description of what Index Server is to search for. It is comprised of several query language clauses and search terms, which are often dictated by the user through the use of HTML query forms.
CiScope contains the starting directory for the search (as either a virtual or physical pathname).
CiSort specifies how results are to be sorted. Sorts can be made using multiple columns with the primary column listed first. The format of this variable value is a series of columns (), each of which is followed by either [a] for ascending order or [d] for descending order like so:
CiSort=Rank[d], FileName[a]
Setting CiSort might force the search to use a non-sequential query and result in less efficient performance and slower query execution.
CiTemplate specifies the path to the report template (.htx) file to be used to format results in the result set. The pathname must be a complete pathname from the virtual root with no . or .. components.
Numerous variables can be referenced (but not set) as read-only variables within .htx files, including
The value of this variable is a reference to the first row (result) on the HTML page.
CiContainsFirstRecord contains the value 1 if the current results page contains the first record of the query results. Otherwise, the value is 0.
CiContainsLastRecord contains the value 1 if the current results page contains the last record of the query results. Otherwise, the value is 0.
For sequential queries, the value of CiContainsLastRecord will not be accurate until after the execution of the <%enddetail%> section in the .htx file.
CiCurrentPageNumber contains the number of the current page of query results, (page number x of y total pages, for example).
CiCurrentRecordNumber contains the record number for the current result being substituted into the detail section of the .htx file.
CiErrorMessage contains the error message and is only available for error pages. Error messages are detailed in Appendix C, "Index Server Error Messages."
CiErrorNumber contains the error number and is only available for error pages.
CiFirstRecordNumber contains the record number of the first record on a page.
CiLastRecordNumber contains the record number of the last record on a page.
For sequential queries, the value of CiLastRecordNumber will not be accurate until after the <%enddetail%> section is executed in the .htx file.
CiMatchedRecordCount contains the total number of records matching a query.
Referencing CiMatchedRecordCount in an .htx file has implications for query performance. Such a reference forces the search to use a , resulting in less efficient, slower query execution.
CiOutOfDate contains the value 1 if the context index is out-of-date; Otherwise, the value is 0.
CiQueryIncomplete contains the value 1 if the query could not be resolved using the context index while CiForceUseCi=TRUE. Otherwise, the value is 0.
CiQueryTimedOut contains the value 1 if the query exceeded the time limit for execution. Otherwise, the value is 0.
CiQueryDate contains the date (according to the Web server) on which the query was executed.
CiQueryTime contains the time (according to the Web server) at which the query was executed.
CiQueryTimeZone contains the server's time zone.
CiRecordsNextPage contains the number of result records to be displayed on the next HTML page.
Referencing CiRecordsNextPage in an .htx file has implications for query performance. Such a reference forces the search to use a , resulting in less efficient, slower query execution.
CiTotalNumberPages contains the total number of HTML pages that will be required for all query results.
Referencing CiTotalNumberPages in an .htx file has implications for query performance. Such a reference forces the search to use a , resulting in less efficient, slower query execution.
CiVersionMajor contains the major version number for the Index Server software handling queries on your Web server.
CiVersionMinor contains the minor version number for the Index Server software handling queries on your Web server.
Table B.1 lists a number of string variables that can be used to format columns with vectors. These variables can be set in .idq files (though they may not reference other parameters). The variables cannot be referenced in .htx files.
| String Variable | Variable Description |
| CiBoolVectorPrefix | String printed prior to vectors of boolean values |
| CiBoolVectorSeparator | String printed between elements of vectors of boolean values |
| CiBoolVectorSuffix | String printed after vectors of boolean values |
| CiCurrencyVectorPrefix | String printed prior to vectors of currency values |
| CiCurrencyVectorSeparator | String printed between elements of vectors of currency values |
| CiCurrencyVectorSuffix | String printed after vectors of currency values |
| CiDateVectorPrefix | String printed prior to vectors of dates |
| CiDateVectorSeparator | String printed between elements of vectors of dates |
| CiDateVectorSuffix | String printed after vectors of dates |
| CiNumberVectorPrefix | String printed prior to vectors of numbers |
| CiNumberVectorSeparator | String printed between elements of vectors of numbers |
| CiNumberVectorSuffix | String printed after vectors of numbers |
| CiStringVectorPrefix | String printed prior to vectors of strings |
| CiStringVectorSeparator | String printed between elements of vectors of strings |
| CiStringVectorSuffix | String printed after vectors of strings |
CiBookmarkSkipCount is used with CiBookmark to establish an offset (such as a number of hits) from the previous page of results returned by a query—in other words, CiBookmarkSkipCount aids in the navigation of result pages returned to the user. It represents the signed number of rows to skip for the next page (a negative value indicates a skip backward, whereas a positive value indicates a skip forward).
CiBookmarkSkipCount should be set within the query form because it cannot be set in the .idq file. For additional information on the use of these parameters, refer to Chapter 8, "HTML Extension Files."
The following sections briefly describe each of the CGI environment variables that can be referenced within .idq and .htx files.
ALL_HTTP headers include those that were not already parsed into one of the other CGI variables listed in this section. These variables appear in the form
HTTP_header field name
with each variable separated by \r\n (carriage return-linefeed) like so:
HTTP_ACCEPT: */*, q=0.300, audio/basic, audio/x-aiff, image/gif, image/jpeg, text/plain,text/html HTTP_USER_AGENT: Microsoft Internet Explorer/0.1 (Win32) HTTP_REFERER: http://omniscient/test_web/omni_search.htm HTTP_CONTENT_TYPE: application/x-www-form-urlenPRE: 10 HTTP_EXTENSION: Security/Digest
For servers that support user authentication and run protected CGI programs, the value of the AUTH_TYPE variable details the method used to validate users. The authentication method is protocol specific. the following code indicates the most commonly used value.
AUTH_TYPE = Basic
In this case, a basic authentication scheme requires a client to provide a password and user identification to authenticate itself.
CONTENT_LENGTH represents the length (in characters) of the data buffer sent by the client (as in a POST request) to the server during a request. The following code indicates how this variable appears.
CONTENT_LENGTH=105
The value of CONTENT_TYPE represents the MIME type of the data sent from the client to the server as the result of a METHOD=POST request from the client. This method is commonly used in HTML forms processing. If no data was sent , the value is set to NULL. For example, the following code is the default encoding for forms.
CONTENT_TYPE=application/x-www-form-urlencoded
GATEWAY_INTERFACE simply contains the version of the CGI specification with which the server complies. The server reports this value as shown in the following, which indicates CGI version 1.1.
GATEWAY_INTERFACE=CGI/1.1
The value of HTTP_ACCEPT indicates all the MIME data types that the requesting client will accept. Basically, seven MIME types are used by HTTP, including application, text, multi-part, message, image, audio, and video. These types are associated with subtypes. For example, gif is a subtype of image. Our server reported that a Microsoft Internet Explorer 2.0 Web client accepts the following image types:
HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, */*
Note that the list is formatted like so:
HTTP_ACCEPT=type/subtype, type/subtype, . . ., type/subtype
The value of PATH_INFO represents extra path information supplied by the client. Servers can decode this information from URLs before executing a script. The following URL points to a CGI program called test-env and is appended with additional information (that is, extrastuff).
<FORM METHOD="POST" ACTION="http://omniscient.domain1/cgi-bin/test-env/extrastuff">
This resulted in the server reporting the following:
PATH_INFO=/extrastuff
CGI applications typically do not have any knowledge of how this value was set. It is up to the developer to know the context in which this value may be used. This variable gives the developer another method of passing information from an HTML document to a CGI program. For instance, suppose an anchor with the following URL was in the following document.
<A HREF="http://jupiter.lnk.com/cgi-bin/myperl.pl/param1=val1+param2=val2
This would result in the following PATH_INFO value:
PATH_INFO=/param1=val1+param2=val2
This, in effect, has provided a method by which two additional parameters can be passed to the CGI program myperl.pl, which could then obtain these values from the PATH_INFO environment variable.
The value of PATH_TRANSLATED is a virtual-to-physical PATH_INFO mapping provided by the server. It represents the server's attempt to provide a full operating-system absolute path to the data indicated in PATH_INFO. In the URL in the previous example, the server used the server's DocumentRoot value of /usr/local/etc/httpd/htdocs to translate the full path to the following:
PATH_TRANSLATED=/usr/local/etc/httpd/htdocs/extrastuff
The value of QUERY_STRING is a URL-encoded string that is appended following a ? character at the end of the URL referencing the script being executed. URL encoding is a method of translating data values to be transferred between the client and server to ensure that the data sent is received intact.
For a METHOD=GET test, the following URL-encoded data string is sent to the server by the client.
http://omniscient.domain1/cgi-bin/test-env?uname=&email=&address=&bus=sw&title=Pres&cgidev=Perl5&dbase=Access&description=&dbyesno=YES&subscribe=YES
The server reported the value of the QUERY_STRING variable as follows:
QUERY_STRING=uname=&email=&address=&bus=sw&title=Pres&cgidev=Perl5 [ccc]&dbase=Access&description=&dbyesno=YES&subscribe=YES
REMOTE_ADDR contains the value of the IP address for the requesting client or agent (which may actually be a host of the requesting client). The following code indicates how this variable appears.
REMOTE_ADDR=168.143.1.44
REMOTE_HOST contains the full DNS hostname for the requesting client or agent provided that the server is able to obtain this information. Otherwise the value is NULL. The following code indicates how this variable appears.
REMOTE_HOST=dkittel.clark.net
REMOTE_USER contains the authenticated user's name provided that the server supports user authentication and the CGI application program is protected from unauthorized use. For example, if the AUTH_TYPE variable is set to basic, the REMOTE_USER variable can be set using the user's identification as sent by the client. This is illustrated in the following code.
REMOTE_USER=julie_wirkkala
REQUEST_METHOD contains the client HTTP request method. GET and POST methods are of greatest interest because they are by far the most popular and widely used. The following code indicates how this variable appears.
REQUEST_METHOD=POST
SCRIPT_NAME contains a virtual path to the CGI program being executed by the server. The following code indicates how this variable appears.
SCRIPT_NAME=/cgi-bin/test-env
SERVER_NAME contains the Web-server hostname, domain name service (DNS) alias, or IP address. The following code indicates how this variable appears in the case of a Web-server hostname.
SERVER_NAME=dkittel.clark.net
The following code indicates how this variable appears in the case of a DNS alias.
SERVER_NAME=dkittel
The following code indicates how this variable appears in the case of an IP address.
SERVER_NAME=168.143.1.44
SERVER_PORT contains the port to which the client request was sent. Ports refer to communications sockets used by TCP/IP applications. Most TCP/IP applications use a well-known port identifier; such is the case with HTTP, which uses port number 80 as a default. However, it is possible for the port number to be explicitly called out in the URL. For example, a server may use a port number such as 8080 as the designated port for the HTTP server. In this case, URLs would need to explicitly reference the port as follows:
http://jupiter.lnk.com:8080/cgi-bin/test-env
This URL results in the SERVER_PORT CGI variable being set as follows.
SERVER_PORT=8080
Using different post numbers allows multiple servers to be run from the same machine. This can be beneficial for establishing servers for CGI testing as well as for separate intranets.
SERVER_PROTOCOL contains information regarding the protocol used by the requesting client. It includes both the name and the versionnumber. The following code indicates how this variable appears.
SERVER_PROTOCOL=HTTP/1.0
SERVER_SOFTWARE contains the name and version number of the Web server that is tending to Web-client requests.
Table B.2 lists the locale string (and equivalent Win32 expression) for several languages. These locale strings can be used for setting CiLocale in .idq or .ida files. The locale can also be specified by the requesting browser via the HTTP_ACCEPT_LANGUAGE tag like so:
HTTP_ACCEPT_LANGUAGE=EN, SL, CZ, FR
Values passed via this tag are superseded by settings in the .idq or .ida file. If no value is set, the entries in HTTP_ACCEPT_LANGUAGE are parsed left-to-right until a language supported by the server is found.
| Language | Locale String | Equivalent Win32 Expression |
| Chinese | ZH, ZH-CN, ZH-TW | LANG_CHINESE SUBLANG_CHINESE_SIMPLIFIED |
| Bulgarian | BG | LANG_BULGARIAN | SUBLANG_DEFAULT |
| Croatian | HR | LANG_CROATIAN | SUBLANG_DEFAULT |
| Czech | CS | LANG_CZECH | SUBLANG_DEFAULT |
| Danish | DA | LANG_DANISH | SUBLANG_DEFAULT |
| Dutch | NL | LANG_DUTCH | SUBLANG_DUTCH |
| English (UK) | EN-GB | LANG_ENGLISH | SUBLANG_ENGLISH_UK |
| English (US) | EN, EN-US | LANG_ENGLISH | SUBLANG_ENGLISH_US |
| Finnish | FI | LANG_FINNISH | SUBLANG_DEFAULT |
| French | FR, FR-FR | LANG_FRENCH | SUBLANG_FRENCH |
| French(Canadian) | FR-CA | LANG_FRENCH SUBLANG_FRENCH_CANADIAN |
| German | DE | LANG_GERMAN | SUBLANG_GERMAN |
| Greek | EL | LANG_GREEK | SUBLANG_DEFAULT |
| Icelandic | IS | LANG_ICELANDIC | SUBLANG_DEFAULT |
| Italian | IT | LANG_ITALIAN | SUBLANG_ITALIAN |
| Japanese | JA | LANG_JAPANESE | SUBLANG_DEFAULT |
| Korean | KO | LANG_KOREAN | SUBLANG_DEFAULT |
| Neutral (use built-in word breaking) | NEUTRAL | LANG_NEUTRAL | SUBLANG_NEUTRAL |
| Norwegian | NO | LANG_NORWEGIAN | SUBLANG_DEFAULT |
| Polish | PL | LANG_POLISH | SUBLANG_DEFAULT |
| Portuguese | PT | LANG_PORTUGUESE | SUBLANG_DEFAULT |
| Portuguese (Brazilian) | PT-BR | LANG_PORTUGUESESUBLANG_PORTUGUESE_BRAZILIAN |
| Romanian | RO | LANG_ROMANIAN | SUBLANG_DEFAULT |
| Russian | RU | LANG_RUSSIAN | SUBLANG_DEFAULT |
| Slovak | SK | LANG_SLOVAK | SUBLANG_DEFAULT |
| Slovenian | SL | LANG_SLOVENIAN | SUBLANG_DEFAULT |
| Spanish | ES, ES-ES | LANG_SPANISH | SUBLANG_SPANISH |
| Swedish | SV | LANG_SWEDISH | SUBLANG_DEFAULT |
| Turkish | TR | LANG_TURKISH | SUBLANG_DEFAULT |
