OS/2 Shareware BBS: 35 Internet/35-Internet.zip/fltintch.zip/fltintch.txt

Text File | 1997-10-01 | 11KB | 220 lines

1 October 1997 - updated for new filter delim introduced in 1.34
   fif format drastically overhauled for readability
9 April 1997 - updated for news flag  (ff13.14)
6 Jan 1997  - jt MR2ICE filter interchange

Summary:

ICEFX.CMD exports a set of mr2i filters into a readable interchange
format.  It should be run from the base mr2i directory (for users with only
a default account; for multiple account users, read on).

ICEFI.CMD converts an interchange file created by icefx into entries
suitable for incorporating into your mr2i.flt file.

There are a number of considerations, please read further before trying the
programs, especially icefi.cmd.

Discussion of how to document and exchange filters.

History:

To date, there has been no convenient way to share filter definitions for
mr2i. What's generally done is to read the settings manually from the
filter edit screen, and then enter them manually into a message.  Since the
edit screen is based on the mr2i.flt file (which has one line for each
filter), and Nick was kind enough to document the format of the file for
this project, it was a SMOP [Small <some say Simple> Matter Of Programming]
to parse each line of the file and output the results as a file that is
both reasonably readable by humans and other programs. The program that
does this is ICEFX.CMD.; here is its usage information:

  Usage is ICEFX outfile [infile]
  If infile is not present, mr2i.flt is used as input.  The
  extension .fif [Filter Interchange Format] is reccommended for
  outfile.  This program reads <infile> and the folder index
  file (either folder.ndx or mail\folder.ndx; converts each
  filter entry to interchange format and writes to <outfile>.
  The folder index file entries contain both the folder
  directory and the name of the folder (as read from the
  folder.ndx file); interchange files identify folders by name
  (the raw filter file identifies them by directory name).  A
  fair amount of checking is done to ensure that the filter
  item is legal.

This program does the following:

1.  Reads in the folder index (so that folder directory names as they
    appear in the filter file will be replaced by folder NAMES.

2.  Reads the filter file one line at a time.

3.  Each line is checked for legal parameters (this process, unfortunately,
    will need to be updated whenever new filter functions are added).

4.  Each field (or, when applicable, subfield) of the filter
    (there are currently 13 fields) is output as one line (fields with
    unused values are not output) laid out as in the example:

"Enabled"                                f1.1 1 +
"Filter description"                     f1.2 * mr2i experts
"Filter alias"                           f2 * mr2i.exp
"Search modes::  Header "                f3 # 8
"Search text"                            f4 * [e-mail]
"Folder for copy :: F016 "               f6 * mr2ice.exp
"Filter type:: Both (In and Out) "       f13.1 1 B
"Search type:: Simple "                  f13.2 1 S
"Match type:: Match "                    f13.3 1 M
"Copy to folder"                         f13.7 1 Y
"Disposition:: Delete NOW "              f13.13 1 Y

There is one line for each field (or subfield) of the filter.
Descriptive information starts in column 1 and is delimited by quotes.
This information may include the :: delimiter which is followed by
descriptive information explaining the encoding of the field.
This is padded out to a fixed length for readability and followed by the
field identifier, size, and value information as follows:
The first field is the field identification (i.e f1.1 is subfield 1 of
field 1; f2 is the second field, and so forth).
The second field is the length or format:
    1 = 1 character
    # = numeric
    * = arbitrary alphanumeric (may include blanks)
This is followed by the actual value of the field in most cases; for search
text or expressions, a multiline format is used for readability:

"Search expression"                      f4 *
 {S}"RETURNED MAIL: HOST UNKNOWN" | {S}"WARNING: COULD NOT SEND MESSAGE"
 | {S}"RETURNED MAIL: SERVICE UNAVAILABLE" | {S}"RETURNED MAIL: USER UNKN
 OWN" | {S}"RETURNED MAIL: CAN'T CREATE OUTPUT" | {S}"DELIVERY REPORT (FA
 ILURE)" | {S}"RETURNED MAIL: WARNING: CANNOT SEND" | {S}"RETURNED MAIL:
 CANNOT SEND MESSAGE" | {S}"RETURNED MAIL: UNKNOWN MAILER ERROR" | {S}"SU
 BJECT: RETURNED MAIL: LOCAL CONFIGURATIO" | {S} RETURNED MAIL: INSUFFICI
 ENT PERMISSION | {S} RETURNED MAIL: REMOTE PROTOCOL ERROR | {S} RETURNED
  MAIL: TOO MANY HOPS

Each filter is delimited by a line of the form:
---------- Filter 2  FIF-level 1.35nf ----------
This file format has been designated as a FIF (Filter Interchange File);
the suffix fif is suggested.

It is fairly easy to use this format as a guide to manually creating a
replica of the filter on a different system, as well as input to a program
to create a filter.

There are a few concerns when moving filters from one system to another:

a.  Any paths specified (for rexx commands, etc.) may not be consistent
    between the source and target systems.

b.  Folder names may not match between the two systems; a folder name
    will have to be selected on the target system.

c.  Where should the filter go in the sequence of filtering?

Subject to these concerns (the folder name issue is somewhat addressed), the
companion program ICEFI.CMD will read a FIF produced by ICEFX.CMD
and create filter file entries.  Its usage information follows:

  usage is:  ICEFI  infile [outfile] [+] [-]

  Run this program in the directory that contains your mr2i.flt
  file (even if you explicitly specify a different outfile).

  If outfile is omitted, lines are appended to mr2i.flt.  If the +
  switch is not present, filters are left disabled regardless of
  setting of the enabled flag in the interchange file.  If the + is
  present, the enabled state is copied from the input.
  If folders.ndx or mail\folders.ndx file is found, will try to
  match folder NAME (not directory) in interchange file and use
  corresponding folder directory on target system; if no match
  found you will be asked to select a folder directory for this
  case [and optionally, any subsequent cases where there is no
  folder name match].

  Unless the - switch is present, the output will be in 1.34 and later
  filterfile format.
  If the - switch is present, output will be in old format.

The output can either be written to a designated file or appended to
mr2i.flt.  Again, this program does a fair amount of checking for
consistency of the filter and valid entries in the fields.  An option
either preserves the enabled status of the input or creates all the
entries as disabled.

In the process of working up these programs, it was observed that in some
cases there are fields in the mr2i.flt file that contain irrelevant values
(such as an arbitrary auto-reply template when autoreply has not been
selected). I have chosen to eliminate these fields as well as not creating
FIF entries for fields that take on their default values.  Because of this,
exporting and then importing a set of filters will not create a new filter
file that is bitwise identical to the original, but it should be
FUNCTIONALLY identical (if not, this is a legitimate bug).

The import program also reads in the local folder index file.  For each
filter specifying a folder, a check is made to see if there is a folder
with a matching NAME (this check ignores case).  If so, that folder is
used. If not, the folder list is displayed and the user is asked to select
an EXISTING folder to be used for the filter. [This choice may be repeated
for each subsequent case where there is no matching name, or saved for use
in all subsequent cases with no matching folder name].

Thus, one of the 3 concerns is somewhat addressed. However, it is expected
that if the imported filters are going to be merged with your existing
filters, a certain amount of editing is going to be required, both for path
names and to position the filters properly in your own sequence of
application.  As a consequence, and because no ready solution came to mind,
the path and sequence issues are left to be dealt with manually (normally
using filter edit in mr2i) by the user.

The maximum length of a simple search text is 80 characters, 1024
characters for freeform. This is checked by the import program.

One note; it is strongly recommended that you manipulate filters only when
mr2i is not running, and to first test a filter setup on existing
(perhaps garbage) messages.  Also, before allowing a filter to delete
messages entirely, I copy them to a "junkbox" folder until I am convinced
that the filter is not grabbing more than it should.

USAGE notes:  Invoking either ICEFI or ICEFX with no arguments will
cause usage and descriptive information to be displayed.

Normally the programs should be run in the base mr2ice directory (but see
below for users with multiple accounts).

NOTES on new version ( FIF level 1.35nf ).

Nick changed the filter format with mr2ice version 1.34, since the old
version used the "\" as a delimiter; this caused major problems if there
was a \ in search criteria.  In the old format, a '\' in a path
specification (for a REXX cmd file) was converted to '/' in the mr2i.flt
file. The old FIF format followed this rule; paths were shown as
c:/mr2ice/xxyz.cmd.  The new FIF format preserves the use of \ in path
specifications.

Note that these programs can be used with either old or new format filter
files, and that the fif file is

The filter EXPORT program - icefx.cmd - will detect which delimiter is
used in the mr2i.flt file, and convert the path separator accordingly.

The default action of the filter IMPORT program icefi.cmd is to
generate the new filter format.  If the '-' switch is used, it will
generate the old filter format; in this case, if the '\' character
appears in any of the text fields (primarily search criteria), an error
will be flagged.

NOTES on multiple accounts.

For users with more than one account, there is an mr2i.flt file in the base
mr2ice directory (this is associated with the default account),
and one in the directory associated with each supplemental account
(a subdirectory under the base mr2ice directory).  The folders.ndx
file for the default account is in the mail subdirectory, but for additional
accounts is in the account subdirectory.  The rule for using these programs
in a multiple account mr2i environment is to run them in the directory
associated with the account of interest; i.e. for the default account, use
the base mr2ice directory, but for a supplemental account, use the
subdirectory associated with that account.  In each case the programs will
find the correct folders.ndx file.