


                            FolderConvert 1.01

                                User Guide




       1. INTRODUCTION

       1.1 LEGAL NOTICE

         FrontDoor is a registered trademark of Joaquim Homrighausen.
         Other brands and product names are trademarks or registered
         trademarks of their respective holders.

         This publication is protected by international copyright laws
         and treaty provisions. It may only be distributed and used in
         accordance with those laws and treaty provisions.

         FolderConvert is provided to you "as is", without warranties of
         any kind. In no event shall Piglet Productions be liable to you or
         anyone else for any damages or costs arising from the use or
         inability to use this program.

         FolderConvert is protected by copyright laws, and may not be
         modified, reversed engineered, sold or distributed in any way that
         would involve some sort of trade, without written permission from
         Piglet Productions.

         FolderConvert may be used without charge by anyone that is running
         a registered copy of the shareware version of FrontDoor, or the
         commercial version of FrontDoor.

         FolderConvert may also be used during the 30-day trial/evaluation
         period of the shareware version of FrontDoor. After this period,
         FrontDoor must be registered if you want to continue using this
         program (or FrontDoor).


       1.2 USING THIS DOCUMENT

         This document is intended to be a reference guide for FolderConvert.
         It makes the assumption that the reader understands the basics of
         the FrontDoor Mail Editor (FM).


       1.3 WHAT THIS PROGRAM DOES

         FolderConvert is a utility to help FrontDoor sysops export the areas
         defined in the FastEcho/ABS configuration to the FrontDoor Mail
         Editor folder list. It is designed to be flexible, allowing a very
         large degree of control over which folders are imported, which users
         may access them, how the description are formatted and so on.


       1.4 SYSTEM REQUIREMENTS

         FolderConvert does not require any special components to be
         installed on your system. The program has been tested under DOS 3.x
         and above, Windows 9x, Windows NT 4.x with good results.                                             


       1.5 INSTALLATION

         Copy the files contained in the distribution archive into any
         directory on your system.

         You may wish to copy it into the path or the FD directory. In any
         case, FLDRCONV will need to be able to find SETUP.FD, either in the
         path pointed to by the "FD" environment variable, or in the current
         directory (that is, the same directory as FDFLDCVT.EXE).


       1.6 FIRST TIME USAGE

         FolderConvert can be run as a batch process with a previously saved
         configuration. Configuring FolderConvert can be done in an
         interactive menu driven environment built into the program itself.
         To trigger this mode, simply run the program with no command line
         parameters.


       2. CONFIGURATION

         When FolderConvert is run with no parameters, a menu appears which
         allows you to configure various options on the behaviour of the
         program, as well as allowing configurations to be loaded and saved.

         The various configurable options are detailed below.


       2.1 MODE

         FolderConvert can run in one of two modes, Import and Update.
         The mode is toggled by this switch.

         In Import mode FolderConvert scans through the Mail Processor
         configuration and imports folders into the FrontDoor configuration.

         In Update mode, the program scans through the FrontDoor
         configuration and checks whether the descriptions on the various
         folders need to be updated from the Mail Processor configuration.

         The modes are dealt with in more detail below.


       2.2 SOURCE TYPE

         This version of FolderConvert can import information from several
         different sources. This menu determines which program configuration
         should be read.

         Note that in some cases only the most up-to-date version of a
         given program (at the time of release) may be supported.


       2.3 SOURCE PATH

         This is the directory where the Mail Processor configuration can be
         found. If an appropriate environment variable is set, this field may
         already be filled.


       2.4 FORMAT STRING

         This is a template for forming descriptions of folders in the
         FrontDoor configuration.

         Format Strings are dealt with in detail in a separate section below.


       2.5 OVERWRITE

         Only applicable in Import mode.

         Rather than deleting the current FrontDoor Folder configuration and
         importing from the Mail Processor to form a new file, FolderConvert
         will, by default, use the existing FrontDoor folders as a
         starting point. It will then check each folder from the Mail
         Processor before importing to see if that folder already exists in
         the FrontDoor Editor configuration. If so, the folder will not be
         imported.

         This ensures that any special case descriptions which have been
         arranged in the FrontDoor configuration will be preserved and not
         overwritten. Indeed even folders not found in the Mail Processor
         configuration are preserved.

         If this switch is enabled, however, FolderConvert will delete the
         starting FrontDoor folder configuration and start from scratch. This
         is considerably faster however, as no comparisons need be made to
         check if a folder already exists.


       2.6 SEPARATOR

         Only applicable in Import mode, with Overwrite disabled.

         This setting determines whether or not FolderConvert should add
         a separator after the currently existing folders and before newly
         added folders.


       2.7 FOLDER OPTIONS

         Only applicable in Import mode.

         These are certain folder configuration options allowed on FrontDoor
         folders. It is possible to use this menu to determine which of
         these settings should be made on freshly imported folders.

         Depending on your version of FrontDoor (Whether MultiLine [ML] or
         SingleLine [SL]) some of these options may have no effect on the
         way that the FrontDoor Mail Editor (FM) behaves.


         NO CHECK

         If this switch is enabled, all imported folders will be marked with
         the NoCheck flag in the FrontDoor folder configuration. These folders
         will not be scanned for new mail when a folder scan is performed in
         FM, for speed reasons.


         TRANSLATE

         This switches the translate flag on for imported folders (as defined
         in FDSetup). This causes FM to use the translation tables for this
         folder.


         FORCE HARD CR

         This switches the Force CR flag on for imported folders (as defined
         in FDSetup). This causes FM to create hard CR characters at the end
         of a line, rather than using the LF characters.

         This may be useful in internet environments.


         EXPORT OK

         This switches the Export Ok flag on for imported folders (as defined
         in FDSetup). This allows non-Supervisors to export messages from
         this folder.


         NETMAIL REPLY

         This switches the NetMail Reply flag on for imported folders (as
         defined in FDSetup). This causes all replies to messages in this
         folder to be directed into the Main NetMail folder.


         NEW IF ANY

         This switched the New If Any flag on for imported folders (as
         defined in FDSetup). When this flag is set on a folder FM will
         display it as if it contains new mail if there are any messages
         in it (whether new or not).


       2.8 USERS

         Only applicable in Import mode.

         This option calls up a submenu, to specify which FrontDoor users
         will have access to newly imported folders. If no users are
         specified, only Supervisor users will be able to read imported
         folders.


       2.9 GROUPS

         Only applicable in Import mode.

         This options calls up a submenu, allowing FolderConvert to import
         folders only in specified Mail Processor groups. If possible,
         FolderConvert will attempt to display the descriptions of the
         groups.

         In addition, by pressing Cursor Right over any group, FolderConvert
         will present a list of FrontDoor addresses. It is possible to select
         an address which FolderConvert will use for all folders imported
         from that group, or to leave it at Auto Detect, where FolderConvert
         will obtain the address from the Mail Processor configuration.

         This should be left to Auto Detect unless you specifically need this
         feature.


       2.10 LOGGING

         This option provides a submenu providing control over optional
         logging of any Import / Update operation. If the log name is blank,
         no logging will take place. It is also possible to specify how much
         detail FolderConvert should include in its log files.


       2.11 INFORMATION

         Provides copyright information about this program.


         Once configured, F2 may be used to save the current configuration,
         which may be recalled by use of the /SETUP: parameter, or using F3
         from inside the interactive configuration using F3.



       3. COMMAND LINE PARAMETERS

         FolderConvert supports the following parameters.


         /SETUP:<Previously saved configuration>

         Once a configuration has been prepared and saved it may be used (in
         a batch mode) by loading it with this command line parameter.

         If other command line parameters are used, these will override the
         setup file where appropriate.


         /ALLUSERS    (Only in Import mode)

         All users will be granted access to imported folders.


         /OVER        (Only in Import mode)

         This has the same affect as the Over Write switch detailed above.


         /UPDATE

         This causes FolderConvert to use a currently saved Import setup as
         an Update one. (See discussion of modes above)


         /DELETE      (Only in Update mode)

         When updating folders, FolderConvert will usually ignore folders in
         the FrontDoor configuration that have no match in the Mail Processor
         configuration, and write them without alteration. If this switch is
         used, FolderConvert will stop on each occurence and prompt the user
         whether or not to delete the folder.

         Therefore this parameter should not be used when the program is to
         be run in an unattended mode.


         /INTER

         If FolderConvert is loaded with no command line parameters, it will
         immeadiately enter the configuration mode as detailed above. If
         command line parameters are used, but it is still useful to enter the
         configuration mode to preview or change the setup, this parameter
         will cause the Interactive setup to be loaded before starting the
         operation.


         In addition to these operational parameters, the following
         parameters control the creation and detail of a log file.

         /LOG:<Filename for a FrontDoor style log file>

         Using /LOG with no filename will cause a log file FDFLDCVT.LOG to be
         created in the current directory. If this parameter is absent, no
         log will be created.


         /DEBUG:<Level>

         The levels are

                0       low    (default - no debug parameter)
                1       medium
                2       high   (used if /DEBUG with no level is specified)



       4. MODES OF OPERATION

         FolderConvert has two modes of operation. However, there are some
         common aspects of behaviour to both modes. FolderConvert will always
         preserve the previous FrontDoor configuration in FOLDER.OLD
         (as opposed to FOLDER.BAK which is used by FDSetup). Thus after any
         run it is possible to reclaim the previous configuration by copying
         FOLDER.OLD over FOLDER.FD.

         It is also possible to interrupt FolderConvert during either import
         or update by using Ctrl-C. This causes the program to prompt the
         user as to whether it should abort. It will either resume, or quit,
         clearing up all busy files and leaving the FrontDoor configuration
         as it was before the execution began.



       4.1 IMPORT MODE

         In this mode, FolderConvert runs through the Mail Processor folder
         configuration and attempts to create new areas in FOLDER.FD.

         By default, FolderConvert will create a new FOLDER.FD file
         containing all the existing FD folders, and then add imported ones
         at the end. The result may be easily sorted using FDSetup. If no
         FOLDER.FD exists, or /OVER is used, the contents of the file will be
         ignored and FolderConvert will simply create a list of imported
         folders from in FOLDER.FD.

         FolderConvert may skip folders in the Mail Processor configuration
         for a variety of reasons, which it will label on the right hand
         side, these are:


         Bad Group

         A set of desired groups has been specified. This folder was not in
         one of the listed groups.


         Exists

         The folder is already present in FOLDER.FD and /OVER was not used.


         Passthrough

         The folder is not stored on the system, and so no folder is
         possible.


         Unknown

         The folder does not match one of the known storage types used by
         the FrontDoor Mail Editor (FM). That is, it is not a HMB, JAM, MSG
         (or passthrough folder).



       4.2 UPDATE MODE

         In this mode, only paramaters to edit the format string and
         Source Path are valid. In somewhat the reverse of the Import mode,
         this causes the program to run through the FrontDoor Mail Editor's
         folders. If it can find a matching folder in the Mail Processor
         configuration, it will update the description of the folder in
         FrontDoor's configuration by processing the Mail Processor entry
         using the format string.

         Folders not found in the Mail Processor configuration will, by
         default, be written without translation, but if the /DELETE switch
         has been used (see above) then FolderConvert will prompt the user
         to select to keep, or delete, the folder.

         In this mode an action is written on the left hand side as before.
         These are:


         NoMatch

         This folder has no match in the Mail Processor configuration,
         (see above).


         NoChange

         The folder has a match, but the description is up to date.


         Updating

         The folder is rewritten using the FastEcho/ABS data.



       5. FORMAT STRINGS

         The format strings follow a philosophy very similar to that used by
         the 'C' programming language, but a brief summary of the concept is
         given below. If you are fimilar with 'C', you need only examine the
         tokens used.

         The format string is essentially a template of how text will appear
         in the FOLDER.FD description. Any text in the string will appear at
         that position in the description. However, it is also possible (and
         in fact, only sensible) to include tokens which represent particular
         items. The tokens are

         %%      Produces a single '%' character;
         %n      Area name as defined in Mail Processor;
         %d      Area description as defined in Mail Processor;
         %t      A character representing folder type:
                        C       Conference;
                        N       Netmail;
                        L       Local;
                        B       Badmail;
                        D       Duplicates;
                        P       Personal mail;
                        U       Unknown.
         %s      A character representing folder storage:
                        H       Hudson;
                        M       Msg;
                        J       Jam.
         %g      Either a character representing the group which the
                 folder belonged to in the Mail Processor, or, when there
                 are 255 groups, the number of the group.
                 imported from.


         So that, the simple format string

         %n : %d

         will yield folder descriptions starting with the area name, a space,
         then the description, for example

         FDECHO : FrontDoor discussion


         It is possible to modify the tokens in several ways with control
         sequences placed between the '%' character and token character
         itself.


       5.1 MINIMUM FIELD WIDTH

         By placing a number inside the token, we specify a width to
         "pad to". For example

         %10n : %d

         will cause any Name to be padded to a width of ten characters.
         By default this padding occurs on the left, so that the output
         is right justified.


       5.2 LEFT JUSTIFICATION

         To force left justification while padding, use a negative number.
         For example

         %-10n : %d

         will cause any Name to be padded to a width of ten characters, but
         the padding is added at the right, giving a left justified output.


       5.3 TRUNCATION

         The maximum length for a description in FOLDER.FD is limited, and
         FolderConvert will truncate the whole description if need be. It is
         possible however to truncate individual fields. To do this we use a
         decimal point '.' (the character will always be '.' regardless of
         the decimal usage in your country). For example

         %.10n : %d

         will cause any Name to be trucated if it is over 10 characters in
         length, smaller strings will be unaffected.


       5.4 COMBINATION OF EFFECTS

         It is possible, and sometimes desireable to combine the above
         options, for example

         %-10.10n : %d

         Will left justify any name, pad it to ten characters if less than
         that, truncate it at 10 characters if more than that, then add the
         " : " text, and finish by adding the description, with no particular
         formatting information.


         REMEMBER: descriptions too long for FOLDER.FD will be brutally
         truncated after being formed using the above format string.


       6. ERRORLEVELS

         FolderConvert uses the following errorlevels when it exits.

         0       Nothing to do
         1       Folders imported/updated
         2       Parameter error
         3       Fatal memory allocation error
         4       Setup File error
         11      Unable to load SETUP.FD
         12      SETUP.FD incompatible version
         13      Error handling Source Configuration
         14      Error handling FOLDER.FD
         15      Busy Semaphores still present after 30 seconds
         20      Import/Update aborted by user (Interactive Mode, or Ctrl-C)




       7. OTHER INFORMATION

         FolderConvert in it's interactive mode should detect and timeslice
         under DESQview, MicroSoft Windows, and OS/2.


         FolderConvert uses structures published by Joaquim Homrighausen
         and Tobias Burchhart, Folkert J. Wijnstra.

         Andreas Klein does not publish IMail structures, but they are used
         in this program with kind permission.

         Thanks are due to all these authors for the structures and the
         programs themselves.


         Thanks are also due to Flemming Danielsen, Malte Erikson,
         Daniel Gulluni, Peter Hampf, Richard Hansen, Eric Larson, Jim Smoot,
         Mats Wallin, and all the FrontDoor beta team members for suggestions,
         help and testing.


       8. DISTRIBUTION

         This is a Piglet Productions program, developed and distributed
         from

         The Heart Of Gold BBS

         +44-1247-274919         2:443/13.0
         +44-1247-273172         2:443/14.0

         Both lines also support FAX.

         WWW: http://www.piglets.com

         For support, NetMail Colin Turner at 2:443/13.0 or,
         email support@piglets.com.

-=-

The product was brought to you by the letter "D" and the number 4.

// End of file FDFLDCVT.TXT


