.-------+----------+--------- [MultiExec] -------+--------------------:
        |                     MultiExec System v1.00 by TuS                   |
        :-------+----------+----------+-----------------+---------------------:

Index
-----
    1)Features
    2)How it works
    3)Supported Functions
     3.1)FTPD Events
     3.2)USER Commands
     3.3)Script Parameters
     3.4)Script Configuration
    5)Requirements
    6)Setup & Install (w/RaidenFTPD)
    7)Configurable Options
    8)Credit
    9)Change Log

1)Features
-----------
    - Standalone MultiExec system for RaidenFTPD (or Not)
    - Runs multiple commands and scripts on single FTPD event
    - Any event provided in the *.ftpd file is Supported (ie:onNewDir, onDelDir,...)
    - Allows multi level condition based execution
    - Supports Multiple Running RaidenFTPD servers
    - Coded in vbs which is natively supported by Windows
      (no third party engine needs to be installed to interpret the scripts)

2)How it works
---------------
The MultiExec system allow execution of multiple commands and scripts on a single
FTPD event or a standalone call to the EultiExec.

When the MultiExec is called it will sequentially execute the different commands
as defined in the configuration file. MultiExec will also check if the previous
command is supposed to provide an answer that will then condition the execution
of the following commands.

As many as required commands can be configured and each command can have as many
as required parameters. Additionally each command can be defined as being a non
monitored execution or a monitored and script conditioning execution.

For each FTPD event that you want to use MultiExec for, you will need to create a
folder called <RaidenFTPD>\Addons\MultiExe<eventName> and extract the package
content to it. As each event requires it's own configuration.
    ie: <RaidenFTPD>\Addons\MultiExeOnNewDir
        <RaidenFTPD>\Addons\MultiExeOnDelDir
        <RaidenFTPD>\Addons\MultiExeOnLogin

3)Supported Functions
----------------------
3.1)FTPD Events
    Any FTPD event defined in the *.ftpd file can be used.

3.2)USER Commands
    #    None

3.3) Script Parameters

    MultiExec has 3 base parameters:
    P1) "%@"    : GCiD, used to pass along to the commands and for ask response
                  filename resolve.
    P2) "%h"    : ServerName, used to pass along to the commands.
    P3) <event> : eventName, used to pass along to the commands and for ask
                  response filename resolve.

    It is crucial, if you want to use the condition based execution (ie: CMD3ASK = True)
    that you get theses parameters correct otherwise the MultiExec will not be 
    able to resolve the expected response filename to read the output from.

    Following parameters P4 to PX are on a need basis and will depend on the
    requirements of the commands that you want to execute.

3.4) Script Configuration

 Const NUMCOMMANDS  = 2  This defines the Number of commands defined and to be
                         processed. Number must be an integer value is typically
                         greater then 1 (you would'nt be using MultiExec otherwise)

 Command X Definition
 ---------------------
    Const CMDX = "CMD"  This is the actual command to execute.
                        Command's must be included in "" and have full path.
                        exemples:
                            Const CMDX = "C:\RaidenServer\RaidenFTPD\addons\Pre.exe"
    Const CMDXARGS = 2  This defines the number of arguments that the command
                        requires. Argument Number must be an integer value and
                        be less or equal to the MultiExec script arguments.

 Command X Arguments Definition
 -------------------------------
    Const CMDXARGY = 1  This defines the argument Y that the command requires
                        if the Argument value is an:
                         - integer : Maps to the Script Argument
                         - string  : is a fixed string
                exemples:
                    Const CMD1ARG1 = 2        This will map the command 1 Argument 1
                                              to the MultiExec script argument 2
                    Const CMD1ARG1 = "login"  This will map the command 1 Argument 1
                                              to the fixed string "login"
                    Const CMD1ARG1 = "2"      This will map the command 1 Argument 1
                                              to the fixed string "2"
    Const CMDXARGYQuotes = false    This defines the if the argument Y should be included in ""
                                    Value is a Boolean:
                                     - True    : Value will be with ""
                                     - False : Value will be without ""

 Command X Type Definition
 --------------------------
    Const CMD3ASK = False  This defines whether the command is just a call or an ASK (must reply to FTPD)
                           Uses the standard <RaidenFTPdPath>\OutPut\ask-onSite<event>.GCiD files.
                           <event> is one of the MultiExec parameters and must match the FTPD event
                           in order to resolve corectly the answer filename.
                           Value is a Boolean:
                            - True  : The command will reply (standard ASK interface)
                                      In this case the script will analyze the response and react
                                      based on the response, continue or abort following commands.
                            - False : The command does not reply, just continue with next command

 Example Command Definition
 ---------------------------
    Const CMD1         = "C:\RaidenServer\RaidenFTPD\addons\Pre.exe"
    Const CMD1ARGS     = 4

    Const CMD1ARG1 = 1
    Const CMD1ARG1Quotes = False
    Const CMD1ARG2 = 4
    Const CMD1ARG2Quotes = False
    Const CMD1ARG3 = "SomeStr"
    Const CMD1ARG3Quotes = True
    Const CMD1ARG4 = 6
    Const CMD1ARG4Quotes = True

    Const CMD3ASK = False
    ------------------------------------------------------------------------------
    Script call:
        MultiExec.vbs "0123456" "TheunderSpecs" "onNewDir" "NEWDIR" "D:\JSource" "/incoming/TV/SERIE/Serie2.S02E02"
    Executes:
        <RaidenFTPD>\addons\Pre.exe 0123456 NEWDIR "SomeStr" "/incoming/TV/SERIE/Serie2.S02E02"
    and does not process any answer.
    ------------------------------------------------------------------------------

3.4) Configuration example

    To better understand how the commands are configured and how to setup the
    MultiExec we will use the following example:

    We need to run 2 different commands on the onNewDir FTPD event.

    #Command 1 : tj-mkdir.exe, to check and disallow creation of directories
            containing spaces in their name. The command replies to the FTPD
            using the standard ask interface.

    Configuration of the command in the *.ftpd file:
        onNewDir=ask://C:\RaidenServer\RaidenFTPD\addons\TJZipScript\tj-mkdir.exe "NEWDIR" "%r" "%S" "%g" "%Y" "%@"

    #Command 2 : LatestX script, to create the Junction point, must be executed
            only if the previous command provided a positive answer.

    Configuration of the command in the *.ftpd file:
        onNewDir=exec://C:\WINDOWS\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\addons\LatestX\LatestX.vbs" "%@" "%h" "NEWDIR" "%G" "%r"

    Obviously, the first thing to do is is to validate each command individually
    by configuring the command in the *.ftpd file as if it was alone. Once each
    command (script) configuration has been validated you can proceed in setting
    up MultiExec.

    Before proceding we have to analyse the parameters that will be required by
    the different scripts and by MultiExec itself.

    Parameter list:
                 |      P1      |  P2  |    P3      |    P4    |  P5  |  P6  |
    MultiExec    |     "%@"     | "%h" | "onNewDir" |          |      |      |
    tj-mkdir.exe |   "NEWDIR"   | "%r" |   "%S"     |   "%g"   | "%Y" | "%@" |
    CScript.exe  | <scriptName> | "%@" |   "%h"     | "NEWDIR" | "%G" | "%r" |

    Now, so that MultiExec can pass on the required parameters to the different
    commands we need to add the missing parameters to the MultiExec parameter list.
    !!! The first 3 parameters of MultiExec are fixed and must not be changed !!!

    Once we have added the missing parameters to the MultiExec list with parameters
    required by the commands, we need to map MultiExec parameters to the command
    parameters :

                 |      P1      |  P2  |    P3      |    P4    |  P5  |  P6  |  P7  |  P8  |
    MultiExec    |     "%@"     | "%h" | "onNewDir" |   "%G"   | "%r" | "%S" | "%g" | "%Y" |
    tj-mkdir.exe |   "NEWDIR"   |  P5  |    P6      |    P7    |  P8  |  P1  |      |      |
    CScript.exe  | <scriptName> |  P1  |    P2      | "NEWDIR" |  P4  |  P5  |      |      |

    Once the parameter mapping is done we can define the commands in the
    MultiExec.Config file:

    '# Command 1 Definition
        Const CMD1 = "C:\RaidenServer\RaidenFTPD\addons\TJZipScript\tj-mkdir.exe"
        Const CMD1ARGS = 6
    '#Command 1 Args
        Const CMD1ARG1 = "NEWDIR"
        Const CMD1ARG1Quotes = True
        Const CMD1ARG2 = 5
        Const CMD1ARG2Quotes = True
        Const CMD1ARG3 = 6
        Const CMD1ARG3Quotes = True
        Const CMD1ARG4 = 7
        Const CMD1ARG4Quotes = True
        Const CMD1ARG5 = 8
        Const CMD1ARG5Quotes = True
        Const CMD1ARG6 = 1
        Const CMD1ARG6Quotes = True
    '#Command Should Output to FTPD
        Const CMD1ASK  = True

    '# Command 2 Definition
        Const CMD2 = "cscript.exe"
        Const CMD2ARGS = 6
    '#Command 2 Args
        Const CMD2ARG1 = "C:\RaidenServer\RaidenFTPD\addons\LatestX\LatestX.vbs"
        Const CMD2ARG1Quotes = True
        Const CMD2ARG2 = 1
        Const CMD2ARG2Quotes = False
        Const CMD2ARG3 = 2
        Const CMD2ARG3Quotes = False
        Const CMD2ARG4 = "NEWDIR"
        Const CMD2ARG4Quotes = False
        Const CMD2ARG5 = 4
        Const CMD2ARG5Quotes = True
        Const CMD2ARG6 = 5
        Const CMD2ARG6Quotes = True
    '#Command Should Output to FTPD
        Const CMD2ASK = False

    Once the commands defined we can update the entry for the onNewDir event in
    the *.ftpd file:
        onNewDir=ask://c:\windows\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\Addons\MultiExeconNewDir\Multiexec.vbs" "%@" "%h" "onNewDir" "%G" "%r" "%S" "%g" "%Y"

5)Requirements
    - Windows Script Host 5.6 or above
    - Script must be invoked by cscript engine
    - FTPD: RaidenFTPD 2.4.3902 or higher (or Not)

6)Setup & Install (w/RaidenFTPD)
    +Prerequisite
     This install "guide" assumes following :
      - RaidenFTPD installed to "C:\RaidenServer\RaidenFTPD",
     If this is not the case then you will have to adapt the settings in the config
     file.

    +System files
     Copy the content of this package to a folder.
     In this guide we use : "C:\RaidenServer\RaidenFTPD\Addons\MultiExec<eventName>"

    +Validate the different commands/scripts individually.

    +Edit "MultiExec.config" file
     Even though you have identical setup as described in this setup, open you're
     favorite text editor and inspect/edit the following file : "MultiExec.config".
     Make sure every path and filenames matches you're configuration.
     Use section 3.4 as a guideline to setup the "MultiExec.Config" file.
     DO NOT CHANGE ANY LOG LEVEL YET.

    +Cscript as default engine
     Set cscript as default script engine. To do this open command prompt and type
     the following: cscript //H:Cscript.
     You should receive this reply if successful: The default script host is now
     set to "cscript.exe". Default script engine in Windows is wscript. This is
     fine, if we would like messages to appear as a dialog. However this is a
     system which in most cases never will be monitored directly. An error with
     wscript engine will wait for someone to click a button, hence the script will
     never complete if an error occurs. This again might lead to multiple instances
     of unfinished script processes. It's possible to omit setting cscript as
     default engine, and call the script directly using "cscript scriptname".

    +Setup RaidenFTPD
      Use section 3.4 as a guideline to setup the "MultiExec.Config" file.

    FTPD event
    ----------------
    Go to the directory "C:\RaidenServer\RaidenFTPD" and open your server's *.ftpd
    file.

    Use section 3.4 as a guideline to setup the "MultiExec.Config" file.

    !!! Save the file !!!

    +Restart the FTPD

    +Do some thing to fire one of the events configured and check:
        - The event was fired (Raiden GUI) you can also have a look on the differen
          params provided correctly to the script.

    +Inspect script log
    Open the log directory <ScripthPath>\Logs and verify that the log only contain
    Information/Success    entries. If not you must correct the error according to the
    log.

    +Do the same thing for the remaining FTPD events and check the logs

    +Tuning off logs
    Once that you're system is working flawless you can trun off the logs ie: Const FILELOG = 0
    to have better performance on execution time.
    Script has log "rollover". The rollover function makes sure that no more than n logs exist
    in your log directory. Number of logs can be tuned ie: Const NUMBEROFLOGS = 5.

    Now, there's really no point of logging if you're not going to read it.
    So if you know that you'll never read any log what's so ever, set log levels to 0:
        ie:    Const EVENTLOG = 0
            Const FILELOG = 0

    WARNING! Do NOT use eventlog level 2 & 3. Default is 0, and we recommend you to keep it
    that way. If you insist on getting entries into eventlog, use level 1, and make sure you're
    eventlog do overwrite with new events.

7) Configurable Options

    '#------------------------------------#
    '#- Paths and Files Settings         -#
    '#------------------------------------#
    'RaidenFTPD Root folder
    Const RAIDENFTPD_PATH     = "C:\RaidenServer\RaidenFTPD"

    '#------------------------------------#
    '# Script settings                    #
    '#------------------------------------#

    'Number of commands defined and to be processed, Number must be an integer value and
    is typically greater then 1 (you wouldn't be using MultiExec otherwise)
    Const NUMCOMMANDS  = 2

    '#  Command X Definition(Use this template for your command definitions)
    '#  Replace the X by your command number ie: 1
    '#--------------------------------------------------------------------------------
        Const CMDX = "some command"
        Const CMDXARGS = 4
        '#Command X Args
        Const CMDXARG1 = 1
        Const CMDXARG1Quotes = false
        Const CMDXARG2 = 4
        Const CMDXARG2Quotes = True
        Const CMDXARG3 = 3
        Const CMDXARG3Quotes = True
        Const CMDXARG4 = 2
        Const CMDXARG4Quotes = True
        '#Command Should Output to FTPD
        Const CMDXASK = False

    '#------------------------------------#
    '# Logging settings                   #
    '#------------------------------------#

    'Loglevel Eventlog 1|2|3 0 = None 1 = Success/Error 2 = Full 3 = Debug.
    '!WARNING! Level above 1 is not recommended (Use file, default is 0)
    Const EVENTLOG     = 0

    'Loglevel File 1|2|3 0 = None 1 = Success/Error 2 = Full 3 = Debug
    Const FILELOG      = 1

    'Number of logs to store in log directory 0 = Do not delete any.
    '!WARNING! this will make sure that no more than n files will remain in log directory.
     Const NUMBEROFLOGS = 5

8) Credit
    - Christer Finsen and Nils-Erik Auråker for their VBS Script Framework (FTPD Search system)
    - Team John Long for making the one of the world's most versatile FTPD on Windows,
    - And last but not least... pn169 from RaidenFTPD forum... ;)

9) ChangeLog
    v1.00: May 2011
     + Initial Release (Hopefully Bug Free)