ISAPI Variable Parser filter

newObjects (ZmeY soft) ISAPI Variable Parser filter

Variable Parser ISAPI Filter

Version 1.212 (last updated 03 Mar 2001)

What's new ?

  • Version 1.212
    • Simple installation wizard added.
  • Version 1.21
    • Adds ability to control parsing process of URLs
  • Version 1.2 fixes one minor bug in the filter:
    • Constant part that is not part of the host name was parsed case sensitive in previous version
  • Version 1.2 adds some enhancements:
    • Strict TCP port management for parsing rules in filter and administration tool
    • Adds option to pass script name with several constant parameters. For example parsed url can be passed to /scripts/myscript.asp?const1=A&const2=B.
    • Parsing algorithm is faster than previous version.
  • Version 1.1 removes dependency on shared DLLs

Upgrade: Just copy new version over older version files. (You must stop W3SVC in order to replace VarParser.dll)

Filter description

This filter processes through a given URL and transforms it to an execution of a given script with parameters based on the URL. URLs that should be processed are identified by a beginning part, called URL Idetificator, which does not take part in the formation of script parameters. That part should include at minimum the hostname and domain of the server. When searching in its database of URL identifications the filter takes the longest match. The way the filter transforms the part of URL that follows the identification part is called Parsing Scheme. Tree parsing schemes have been defined in that release. (See below for description of each parsing scheme and an illustration). User specifies script name and location and parsing scheme for each URL identification.

Package contents

File name: | Description:
VarParser.dll | The ISAPI filter itself.
admin\VarParserConfig.exe | CGI application, configuration tool for the filter
admin\Scheme1.gif admin\Scheme2.gif admin\Scheme3.gif admin\newObjects-logo.gif | Logo and Images that illustrate the operation of parsing schemes
VarParser.chm | HTML help file
Readme.htm | obsolete - all information is now in the VarParser.chm
Dumper.exe | CGI test tool - dumps all data from query string, form post, cookies and environment
install.hta img/logo.jpg | Installation wizard - HTML application - requires IE5 or later. Double click install.hta if you are installing the filter for the first time.

Parsing Schemes

· Scheme 1

Nothing special here. If the number of subdirectories in the URL is not even the value of the last variable is empty.

See also samples

· Scheme 2

The names of variables are specially defined for that scheme. Also significant is their order because it means which subdirectory from the URL will be the value. If the subdirectories in the URL are less than the variables, the last ones are left empty. If the subdirectories are more - they are processed to the number of variables and the remaining are ignored.

See also samples.

· Scheme 3

Here only one variable name is specified and it receives the raining part of the URL after the identificator.

See also samples

Filter installation

  1. Copy files
  2. Register the filter with IIS
  3. Configure it
  4. Upgrading notes

· Copying the files

You should copy all files included in this package to their permanent locations by hand. Put VarParser.dll in a safe directory not shared to the WEB, which has full SYSTEM access to it. Copy admin subdirectory or its contents to a folder exposed as a virtual directory by the WEB server. VarParserConfig.exe is a CGI application so you should copy it to a location that is accessible from the WEB and has execute access (not only script) from IIS. Your web server must want authentication to that location because only administrators should have access to that configuration tool and because CGI and any other server programs run in the account of the user authenticated through the "authenticate" dialog shown by the browser. Administrative rights also needed to set serial number and configuration file location ! Remember - it is not enough to log on locally as administrator - you must be authenticated as member of the administrators group by IIS on the server machine. Thus the virtual directory that contains CGI administration tool must require authentication. Copy the pictures in the same location where VarParserConfig.exe.

· Registering the filter in IIS

You can register that filter either on the whole web server (i.e. on all web sites) or on specific site(s) only. Use Microsoft Management Console for the registration. Open Properties dialog box for the selected web site or General Properties for the web server. You can add the filter form ISAPI filters tab. There you can browse to the filter location and select VarParser.dll. You can type whatever you want for filter’s name. If on the same site is installed ZmeY Soft URL Mapper Filter, this filter must be with higher priority (i.e. upwards in the list). You need to restart the web site or the whole IIS, so the filter takes action. If you have installed it on a web site you can simply stop and run again this site. If the filter is installed globally you will need to stop and start the IIS service. (Don’t bother if the first time after you have installed the filter Management Console shows it is not loaded).

· Running the configuration tool

Filter will not do any work until it has a configuration file. That configuration file is created and edited by the configuration tool. You can run it by going to its location with your web browser and typing VarParserConfig.exe. The first time you start this tool you should go to the menu. There you can type in the location where the configuration file will be created and stored. Bare in mind that the CGI configuration tool and the filter must have full access to that location. You are free to name this file by your choice. Also Registry Configuration is the place where you must enter your registration number - you must be logged on as administrator to do this. After you have submitted the form, a configuration file will be created and the filter will begin to operate. To do some real work you should register the URLs which it will process. See the section Configuring the filter for details.

· Upgrading notes

Upgrade you must do manually by replacing the old files with new ones - VarParser.dll and configuration tool files. Until now all versions are compatible forward and backward thus you can use the same configuration file without change. Before replacing files you must stop the WEB server.

Configuring the filter

The filter stores a list of URL Identificators for the URLs that it processes. When selecting Edit URL options or Remove URL you can see the list. To add URL select Add URL to parse. The same form appears (but filled with the current options) when you edit options for a present URL. There you enter the URL Identificator - that is the beginning of the URL that will be processed. When the filter finds an URL that begins in that way, it processes it.

Next is the location and name of the called script. It receives the generated variables. The location is given without the hostname in relation to the root directory. It should begin with a slash. For example: /scripts/filename.asp.

After that you must select the parsing scheme which will be used for processing that URL. On the next form are the options, specific for the selected scheme.

(new v.1.21) Here you can specify how filter will identify URLs. Exact matching means that URL will be matched only if it is a whole part of the virtual path i.e. URL server/key will match exactly in the http://server/key/aaa/bbb/ccc. If you choose to use not exact (partial) matching this server/key will match in request like http://server/keyaaa/bbb/ccc too.

See samples and filter behavior for more information.

Schemes options

Scheme 1 - there are no options for that scheme.

Scheme 2 - you must build a list of variable names. Use the bottom input for new variable name and button Add. You can remove a variable with the button Remove in front of it. Use Move Up and Move Down buttons to change the order in the list. There is no way for editing the name of already added variable - remove it and add again with the new name.

Scheme 3 - here you assign only one variable name - that receives the part of the URL that follows the URL Indentificator.

General options

From that menu you can enable/disable the filter. When disabled the filter is still active but does not make any changes to the URL.

If you type a location and filename a log file will be created. The filter appends records to it on every URL procession.

Demo version restrictions

The functionality of the demo version is limited to two parsing schemes (Scheme 1 and Scheme 3) and in the CGI configuration tool Edit URL options menu is disabled. To edit the options for an URL you must remove it and then add it again. Also there is no serial number.

Also the filter accepts up to 100 requests and then stops parsing the URLs. You have to restart the web server to activate it again!

Additional notes

Be careful when writing the script that the filter executes. If it refers to any objects by URL (pictures, html pages, etc.) these URLs MUST NOT be processed by the filter or at least the filter must not generate a request to the same script. There is a danger of potential recursion that will crash the web server!

If you have any questions and suggestions please mail us: support@newobjects.com
Copyright newObjects (ZmeY soft) 1999-2001


Samples

ISAPI Variable Parser sample configurations

General Scheme 1 Scheme 2 Scheme 3

General

hlp-general.gif (21909 bytes)

On the picture above you can see page displayed by the CGI configuration tool for general filter options. Here you can do the following:

  1. Disable entire filter. This is equivalent of removing filter from IIS configuration but takes effect at run time immediately without need of restarting WEB server.
  2. Set default URL matching policy. This option is used for all configured URLs that do not specify their own. Configuration of version 1.21 and later versions is fully compatible with previous versions - i.e. if option is omitted in .cfg file it will appear as non-checked on this page and filter will act with partial match policy.
  3. Log file. Enter full path name of the file that will be used to log filter events. Please note that filter logs more than 2 lines of text for every request. It is strongly recommended to enable logging only for test purposes !

hlp-general-2.gif (27146 bytes)

On this picture you can see common screen for all parsing schemes. Here you must enter general parameters as URL to match, script to pass request too and (of course) what scheme to use.

  1. In this field constant part of the URL must be entered without http:// and trailing "/" (if "/" appears in the string it will be removed while saving configuration. Do not specify port as in the address bar of the browser !
  2. Specify here TCP port of the site that answers URL specified in the field 1. If 0 was specified (or 80) default port - 80 will be assumed.
  3. Write here full virtual path of the script that must be called after URL matching. Script can not be on another site ! "/" in the beginning is required for full virtual paths.
  4. Choose parsing scheme to be used here
  5. Select specific matching policy for this URL if needed. (see URL Matching policy)

Scheme 1

hlp-scheme1.gif (25576 bytes)

There are no options for this scheme. URL will be divided in parts - every odd part will be used as variable name and even parts will be used as values for the corresponding variables.

Example:

Configured URL: server/key

Passed URL: http://server/key/aaa/bbb/ccc

Script: /script.asp

Script will be called as follows:

http://server/script.asp?aaa=bbb&ccc=

In this example server/key matches "exactly" i.e. it is matched as part of the passed URL that consist only of whole URL parts - you can think about whole part as for the virtual directory. /key/ is whole part but /keyaaa/ is partial match. Thus previous example will do the same work if URL http://server/keyaaa/bbb/ccc was passed to the server and match partially option was checked on the previous screen, but it will not occur if exact matching is the selected option.

Scheme 2

hlp-scheme2.gif (28923 bytes)

This scheme defines set of variables that will be used to pass parts of the URL to the script. Resting part of the request will be ignored.

Example:

Configured URL: server/key

Passed URL: http://server/key/aaa/bbb/ccc

Script: /script.asp

Variables: Var1 and Var2

Script will be called as follows:

http://server/script.asp?Var1=aaa&Var2=bbb

Here ccc part of the request line is omitted in the final request sent to script because there is no variable defined for it.

Scheme 3

This is the simplest scheme available in the filter. You must define only one variable and entire request after the configured URL will be passed as value of this variable.

Example:

Configured URL: server/key

Passed URL: http://server/key/aaa/bbb/ccc

Script: /script.asp

Variable: Var

Script will be called as follows:

http://server/script.asp?Var=aaa/bbb/ccc


Configuration

Configuration file description

Here you can see one example configuration file. In spite of recommendation to configure filter with CGI configuration tool you can edit it config file manually. But please do it with care ! Incorrect configuration may cause IIS to crash. CGI admin tool eliminates many possible human errors.

File consist of sections. Section begins with { <Section_name>: and ends with } <Section_name>; Every section contains records and/or subsections. Every line of the file can contain only one record or one begin or end of section.

Section names can contain any character except ":" and ";".

Record and section names are case insensitive.

Spaces before section names (example: {___Sample name:) are ignored. At least one space must present before the section name.

Spaces before entries are ignored.

If first nonspacing symbol is ";" line is treated as comment. CGI admin tool removes any comments !

Every record must have type specified in the ( ) brackets. Meaningful types for VarParser filter are: int and string. Any values with other type will be loaded but ignored.

Sample configuration:

{ MAIN:
    (int)Disable=0
    (string)Log=F:\Inetpub\isapi\logs\parser.log
    (int)MatchURLExactly=0
} MAIN;
{ COMPURLS:
; Rule sections
    { asmodeus/dump:
        (string)Script=/dumper.exe
        (int)Scheme=2
        (int)MatchURLExactly=1
        (string)SubURLVar=alpha
        (string)Vars=a
        (string)Vars=b
        (string)Vars=c
        (string)Vars=d
        (string)Vars=e
        (string)Vars=f
        (string)Vars=g
    } asmodeus/dump;
    { asmodeus/dump1:
        (string)Script=/dumper.exe
        (int)Scheme=2
        (string)Vars=a
        (string)Vars=b
        (string)Vars=c
        (string)Vars=d
    } asmodeus/dump1;
    { asmodeus|81/dump:
        (string)Script=/dumper.exe
        (int)Scheme=1
    } asmodeus|81/dump;
    { asmodeus.zmey/dumpit:
        (string)Script=/dumper.exe
        (int)Scheme=3
        (string)SubURLVar=aaa
    } asmodeus.zmey/dumpit;
} COMPURLS;

MAIN section

  • int Disable - if set to 1 filter is disabled and urls will not be modified.
  • string Log - log file location. If empty or missing filter will log nothing. Filter logs every request ! It is strongly recommended to enable logging only for debugging purposes.
  • MatchURLExactly - if omitted or set to 0 all URLs without this option set will be matched partially, If set to 1 exact match will be default policy.

COMPURLS section

This section contains subsections for every rule that filter applies to requests. Section names are constructed as follows:

<host_name>|port_number/constant_part_of_the_url

Port number can be omitted if port is 80 i.e. default HTTP port.

Rule sections

  • int Scheme - scheme number. Valid numbers are 1,2,3 - any other value will be ignored
  • string Script - Script that will be called with modified URL. Script must be specified with full virtual path in the site.
  • MatchURLExactly - if omitted default option applies (from MAIN section). If set to 1 this URL will be matched exactly, if set to 2 - partially.
  • Additional options for Scheme 2
    • string vars - any number of records with the same name. Every record specifies variable to use for corresponding part of the URL.
  • Additional options for Scheme 3
    • string SubURLVar - Name of the variable used to pass resting part of the query string to the script.


ISAPI Variable Parser filter

Filter behavior

Scheme below shows how Variable Parser filter processes the requests.

image001.gif (9009 bytes)

Filter checks every URL from its configuration. It selects the largest one that matches the beginning of the request currently processed. Match occurs if in the request exist beginning part that matches currently checked URL. Depending on the "Exact match" option this match will be or not discarded:

  • Exact match means that configured URL is equal to the part of the request that consist of entire "paths" i.e. if the configured URL is server/key it exactly matches in the server/key/aaa/bbb/ccc but only partially matches in the server/keyaaa/bbb/ccc
  • Partial match means that the beginning of the request matches configured URL without any additional conditions

Exact match option can be set for every configured URL or globally. Global option (in general options) takes place for every configured URL that does not have its own option set (Use default policy was set).

Ideas on how to use the filter

You can use this filter not only to improve indexing by search engines. One interesting application can be intelligent redirection of the user to the right page based on the partially entered URL. You possibly know about many interesting Microsoft's sites that can be found by entering www.microsoft.com/some_word . Imagine that user doesn't knows what word to enter - for example he(she) looks for scripting information. You can configure filter to pass all requests of type www.microsoft.com/scrip to the desired page and configure this URL to be matched partially. Then all requests (/script /scripting /scripts etc.) will be passed to your script there. If you wish to do more you can create script that reviews resting part of the URL passed and give to the user additional choices.


Contact information

Contact and registration

Note that our domain name was changed. Please update your links and e-mail addresses from zmey.com to newobjects.com domain. Structure of our site(s) and mail boxes are the same but on the new domain.

Registration of the retail version of the filter costs:
$40 for one machine license
$100 for full (Developer) license for your company/organization.

Visit us:
http://www.newobjects.com

Contact us:
Sales: sales@newobjects.com
Support: support@newobjects.com
Other: info@newobjects.com
Copyright newObjects (ZmeY soft) 1999-2001


ISAPI Variable Parser filter

logo.jpg (9832 bytes)

What to read first?

  • If you are going to install the filter for the first time and you have IE5 or later on your system you can double click install.hta HTML application from the root directory of the package.
  • If you are going to upgrade the old installation or you do not have IE5 installed see Installation
  • If you are running the old version see the What's new chapter
  • You need samples about configuring URL to be parsed see samples

Use the navigation tree (on the left) to find additional information on another topics.