ÛÛÛÛÛÛ»   ÛÛÛÛÛ»  ÛÛÛÛÛÛ»      RAR version 2.00
 ÛÛÉÍÍÛÛ» ÛÛÉÍÍÛÛ» ÛÛÉÍÍÛÛ»     ~~~~~~~~~~~~~~~~
 ÛÛÛÛÛÛɼ ÛÛÛÛÛÛÛº ÛÛÛÛÛÛɼ     Multifunctional Integrated Archive Manager
 ÛÛÉÍÍÛÛ» ÛÛÉÍÍÛÛº ÛÛÉÍÍÛÛ»     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ÛÛº  ÛÛº ÛÛº  ÛÛº ÛÛº  ÛÛº     The Installation SFX for DOS User's Manual
 Èͼ  Èͼ Èͼ  Èͼ Èͼ  Èͼ     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


   1. SFX functionality overview.

   The SFX (SelF-eXtracting module) is the archive module used to extract
   files when executed. It is in the form of a normal executable file.

   The RAR Archiver offers SFX-functionality which is significantly
   enhanced over common SFX, as well as the possibility to create an SFX
   archive, with an alternate SFX module from an external file.

   The alternate SFX module can be created by using the switch
   '-sfx[<sfxfile>]' or the command 's[<sfxfile>]' when, in the optional
   parameter <sfxfile>, you indicate the required SFX executable module.

   Several RAR SFX executable modules are currently available:
      - the common SFX for DOS (default in the DOS version, file dos.sfx);
      - the Installation SFX for DOS (file idos.sfx);
      - the common SFX for OS/2 (default in the OS/2 version, file os2.sfx).

   In fact you may add your own RAR SFX executable module using unRAR
   sources (e.g. for your particular OS or special needs).


   2. The Installation SFX.

   As an alternative to the default SFX you may build an Installation
   SFX which uses a powerful script language, providing original features:

     - fully configurable, friendly, menu-driven interface;
     - check for free disk space before installation;
     - request destination path to which to install files;
     - installation status - file extraction progress bar,
       completed percentage and other features.

   The Installation Script is a plain ASCII text file, which may be prepared
   using your favorite text editor.  The script is placed in the SFX 
   archive comment to be processed by the Installation SFX module when it 
   is executed.  For example, you may use the following command line to
   create such an SFX archive: 

     rar a -sfxidos.sfx -zmyinst.s minstall

   Where 'idos.sfx' is the pathname of Installation SFX module and the file
   myinst.s is the text file containing your installation script.

   The Installation SFX contains build-in interpreter of the Script
   Language.


   2.1 Installation Script Language

   As a program language the script contains the following objects:

     Command    statement initiating an action;

     Procedure  commands defined apparently to be called from the main
                script code;

     Function   built-in procedure which returns a value;

     Constant   character string or a numeric value (4 bytes length);

     Variable   name defining a storage place for a value.

   Variables may be assigned a numeric value or a character string.
   All variables are global, meaning once defined the variable is the
   same within the main code and all procedures.

   Variable and procedure names are case-sensitive.
   Command statements are case-insensitive.

   Command and built-in procedures may be called with parameters -
   constants and variables.  Expressions may not be used as parameters.


   2.1.1. Control commands

   CALL        Initiate a procedure call:

               CALL <ProcName>

               <ProcName> is the procedure name (defined with PROC).


   DELAY       Suspend script execution:

               DELAY [<ms>]

               <ms> is the delay interval (milliseconds).  If the interval
               is ommitted, an infinite interval will be set.  Execution
               continues following a key press or mouse click.


   EXCLUDE     Define the list of files NOT to be extracted from the archive
               while installing:

               EXCLUDE [ <File1> [, <File2>..] ]

               <File1>, <File2>.. are variables or character strings
               containing the names of files to be excluded.  Wildcards are
               permitted.

               The initial value of this file list is "", meaning "no files
               to exclude".  EXCLUDE without any parameters would restore the
               initial value of the file list.


   EXIT        Terminate the Installation SFX:

               EXIT <Code>

               SFX exits with errorlevel = <Code>.


   GOTO        Transfer control to a string in the script, identified
               by a label:

               GOTO <Label>

               <Label> is the name in the script followed by a colon ':'
               character.  For example:

               GOTO Menu
               ...
               Menu:


   IF          Conditionally execute commands:

               IF <Var> <?> <Value>
                     <commands>
                     ...
               ENDIF

               Control flow statement that defines conditional execution of
               the statements within the block IF...ENDIF structure.  <Var>
               is a variable to be compared with the <Value> using a single
               comparison operator, if the result of the comparison is TRUE
               then the statements within the IF...ENDIF are executed.

               Comparison operators are:-

               '=='  ..  EQUAL TO
               '!='  ..  NOT EQUAL TO
               '>'   ..  GREATER THAN
               '>='  ..  GREATER THAN OR EQUAL TO
               '<'   ..  LESS THAN
               '<='  ..  LESS THAN OR EQUAL TO

               <Value> is a constant or variable.
               Character values may be compared using only the '==' or '!='
               comparison operations.


   INCLUDE     Define the list of files to be extracted from the archive
               while installing:

               INCLUDE [ <File1> [, <File2>..] ]

               <File1>, <File2>.. are variables or character strings
               containing the names of files to be extracted. Wildcards 
               permitted.

               The initial value of this file list is "*.*" meaning
               "all files in the archive".  The first INCLUDE defined will
               replace the default value with the specified value.  All 
               further INCLUDE's will add file names to the list without 
               removing previous values.
               To clear all the file names in the INCLUDE list, give the 
               INCLUDE statement without parameters.


   INSTALL     Begin installation.  If no INSTALL statement is given,
               installation will begin when the end of main script code
               is reached.


   OVERWRITE   Set overwrite mode when extracting archived files:

               OVERWRITE { ON | OFF | FRESH | UPDATE }

               ON      always overwrite existing files
               OFF     never overwrite existing files
               FRESH   only overwrite files which exist in the destination
                       directory and are newer in the archive
               UPDATE  As for FRESH but also extract files which do not 
                       exist in the destination directory


   PROC        Define a procedure:

               PROC <ProcName>
                    <commands here>
                    ...
               ENDP

               <ProcName> is the procedure name.  May be called with the
               CALL statement - commands between PROC and ENDP would be
               processed.


   SOUND       Produce sounds on the PC speaker:

               SOUND <F1>, <D1> [, <F2>, <D2>...]

               <F1> is frequency and <D1> - duration in milliseconds of
               produced beep. You may produce as many notes as required


   SYSTEM      Issue an OS command:

               SYSTEM <Arg1> [, <Arg2>..]

               The command line merged from parameters <Arg1>, <Arg2>...
               is executed.

   ;           The script strings starting with a semicolon ';' character
               are comments and are ignored when processing.

   =           To set a variable value, the following command may be used:

               <Var>=<Expression>

               <Var> is the variable name and <Expression> may be a
               constant, numeric expression or a function call.

               Numeric expression is the combination of the pattern "A # B".
               Where A and B could be numeric constants and/or variables,
               '#' is one of the mathematical operators: '+', '-', '*',
               '/', '%'.


   2.1.2. Screen commands

   All output is directed to the current text window (see the WINDOW command
   description).

   Foreground and background colors in all related commands are
   designated with keywords defining the corresponding color:

   BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
   LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW, WHITE.

   Alternatively you may use the numeric attribute value from 0 to 15 as a
   color code.

   If a command does not have a foreground/background pair as a parameter,
   the current color is used for output (see the SETCOLOR command).


   BOX         Draw a box:

               BOX <X1>, <Y1>, <X2>, <Y2>, <Col>, <Bck>, SINGLE | DOUBLE

               <X1>, <Y1> - the left and top point of the box;
               <X2>, <Y2> - the right and bottom point;
               <Col>, <Bck> - the foreground and background colors;
               SINGLE or DOUBLE - Border type, one or two lines.


   CLRSCR      Clear the current window (with an optional symbol):

               CLRSCR [ <Symbol> ]

               The current color is used for clearing.  Optionally a 
               symbol may be given which will be used to fill
               the window.  The symbol should be defined with a 
               character value (in quotation marks - "") or a
               numeric code.


   CTEXT       Write text centered on the current line:

               CTEXT <P1> [, <P2>..]

               <P1>, <P2>.. are variables or character constants.


   GOTOXY      Position the cursor in the current window:

               GOTOXY <X>, <Y>

               <X>, <Y> - the point to which the cursor should be 
               positioned.

   DEFBAR      Define the file progress bar:

               DEFBAR <Col>, <Bck>, <BarCol1>, <BarCol2>, <X>, <Y>, <Length>

               <Col>, <Bck> - foreground and background colors;
               <BarCol1>, <BarCol2> - colors for 'non-filled' and 'filled'
               parts of the progress bar;
               <X>, <Y> - left and top point of the bar window;
               <Length> - length of the bar.

               You may disable the file bar by a using a special form of the
               DEFBAR command:

               DEFBAR OFF


   MESSAGE     Write text in a box:

               MESSAGE <Col>, <Bck>, <Title>, <Str1> [, <Str2>..]

               <Col>, <Bck> - foreground and background colors;
               <Title> - Box header text;
               <Str1>, <Str2>.. strings containing the text to be displayed


   OUTTEXT     Start/end a plain/ANSI text:

               OUTTEXT [ANSI] ON | OFF

               Defines the beginning (ON) and the end (OFF) of a text
               section.  The optional keyword ANSI indicates that the text
               contains ANSI esc-sequences which are to be processed while 
               writing to the screen.

               Example:

               OUTTEXT ON

                  Installation instructions.

                  You should install this program according to
                  the following procedure:
                    ...


               OUTTEXT OFF


   RESTSCR     Restore a screen saved with SAVESCR:

               RESTSCR <NumScr>

               <NumScr> - the identifier of the screen previously saved
               with the SAVESCR statement.  The cursor position, current 
               window setting as well as the foreground and background
               colors are restored.


   SAVESCR     Save screen:

               SAVESCR <NumScr>

               <NumScr> - A numeric value from 1 to 16 identifying the
               storage place for the saved screen data.  Stored data 
               includes the screen data, the cursor position, current 
               window setting as well as the foreground and background
               colors.  Saved screens may be restored using the RESTSCR
               statement.  

               <NumScr> must be numeric value from 1 to 16.


   SETCOLOR    Set the default foreground and background color:

               SETCOLOR <Col>, <Bck>

               <Col> is the foreground and <Bck> is the background color.
               After setting this default all commands, which use but do 
               not contain a color specification, will be output using 
               this color.


   TEXT        Write text:

               TEXT <P1> [, <P2>..]

               <P1>, <P2>.. are variables or character constants containing
               the text to be written.


   WINDOW      Set the current window:

               WINDOW <X1>, <Y1>, <X2>, <Y2>

               <X1>, <Y1> - the left and top point of the window;
               <X2>, <Y2> - the right and bottom point;
               All output, written after this command has been issued,
               will be within the specified window range if else not
               stated in command description.


   2.1.3. Functions

   Function provides built-in procedure call, which returns a value.
                                          

   EXEC        Issue an OS command and return exit code:

               <Var>=EXEC <Arg1> [, Arg2.. ]

               <Arg1>, <Arg2>.. - parameters of which the command line
               merged prior to be executed. If you need spaces - add it
               accordingly into <Arg1>, <Arg2>..
               <Var> - the variable to receive the returned errorlevel
               after the command line execution.

             
   GETDFREE    Get disk free space:

               <Var>=GETDFREE [<DiskNo>]

               <Var> - variable to hold the returned value.
               Available disk space in bytes is assigned to the variable.

               <DiskNo> - the optional number of disk to get available
               space (0 means A:, 1 - B:, 2 - C: etc). If this parameter
               not indicated the available space will be reported for
               destination disk (see DestDir variable description). If
               the disk matched does not exist, -1 will be returned.


   GETKEY      Return pressed key code:

               <Var>=GETKEY

               The function waits for a key depression and returns it's
               code to <Var>.  Special keys produce extended scan codes
               in which the first byte is zero and the second contains
               the extended code.  In this case the key code is returned
               as a value of the second byte plus 256.

  
   INPUT       Perform input:

               <Res>=INPUT <Col>, <Bck>, <Var>, <IniValue>, <MaxLen>

               <Col>, <Bck> - the foreground and background color of the
               input field;
               <Var> - the variable to receive the input value;
               <IniValue> - the initial value (variable or a constant);
               <MaxLen> - the input field (maximum) length.
               <Res> - A flag indicating the success of the transaction.

               If the <Esc> key is pressed during input then a value of
               zero is returned in <Res> and <Var> is undefined.  If a
               value is successfully entered, <Res> is assigned a value 
               of 1 and <Var> is assigned the input value.


   MENU        Initiate a menu:

               <Var>=MENU <X>, <Y>, <Col>, <Bck>, <Position>, <Title>,
                          <Item1> [, <Item2>..]

               <X>, <Y> - the left and top point of the menu;
               <Col>, <Bck> - the foreground and background color;
               <Position> - initial menu pointer position (number);
               <Title> - text of the title;
               <Item1>, <Item2>.. - character strings - menu items;
               <Var> - the variable to receive the returned value.

               Upon successful choice, the function returns the number of
               the menu item (1-n).  If the <Esc> key was pressed, a value 
               of zero is returned. 


   2.1.4. Pre-defined procedures

   Procedures with reserved names which are called from the SFX internal
   code upon special conditions.  Prior to such call SFX sets the parameter
   variables Par1 and Par2.  The pre-defined procedures are optional and
   should be written to particular need by the script programmer using
   the PROC statement.

   ArcDone     Called upon successful completion of extraction.

               No parameter is used.  When ArcDone is executed,
               the archive file is closed and may be erased by
               issuing the command: SYSTEM "DEL ",ArcName

   ChangeVol   Called when the archive volume needs to be changed.

               Par1 is assigned the volume number (0 for the first volume
               change), Par2 is assigned the volume status: If Par2 is 0,
               the volume needs to be installed, (user should be asked to
               load it). This procedure will be called with Par2==0 until
               the requested volume is not found. You may change the
               requested volume name by an assignment to the variable
               ArcName. In the case of non zero value of Par2 the volume is
               successfully installed and no user action is required.

               If the ChangeVol procedure is not defined then the prompt
               "Insert disk with <volume name>" will be displayed by SFX 
               when the next volume is required.

   Error       Called when an error occured.

               Par1 is assigned the error code:

                  1 - Fatal error
                  2 - CRC error, broken archive
                  3 - Write error
                  4 - File create error
                  5 - Read error
                  6 - File close error
                  7 - File open error
                  8 - Not enough memory

               When Error procedure ends, SFX processing terminates.
               This procedure is not called when an incorrect AV code is
               detected.

               If no Error procedure is defined, SFX prompts the user with 
               a standard error message and terminates.

   FileDone    Called upon successful extraction of a file or a directory.

               Par1 variable is assigned the file number in the archive.
               Filename contains the file name.

   OnKey       Called when a key is pressed.

               May be used to implement context sensitive help message
               display as well as break processing.  Par1 is assigned the
               key code of the pressed key.  If the key operation is 
               processed within the OnKey procedure, you should set Par1
               to -1, to inhibit double processing of the key by SFX.
               Recursive calls of OnKey are prevented by SFX itself.  When
               OnKey is called, the current window, color setting and cursor
               position are automatically saved and restored upon exit of 
               the procedure.  Note that screen saving is not performed -
               use SAVESCR and RESTSCR commands if so desired but be sure
               that you save and restore screen with an identifier which
               is not used in the script).


   2.1.5. Pre-defined variables


    Archive variables:

   ArcName       The archive name

   AVPresent     If authenticity verification (AV) is present, the variable
                 value is 1, else - 0.  In the case of invalid AV information
                 the value is -1.

   AVArcName     The archive name stored in AV

   AVDate        The archive date stored in AV

   AVUserName    The archive creator (AV registration string)


    Extraction dependent variables:

   FileName      The name of the file extracted from the archive (no
                 destination path)

   DestFileName  The full path name of the file extracted from the
                 archive (destination path included)


    User-definable variables (to be assigned by INPUT or = operation):

   DestDir       Destination directory to install files from the archive.
                 If the destination directory does not exist, it will be
                 created. If the last character of the destination
                 directory entered not '\' or ':', then the string will
                 be automatically complemented with final '\' character.

   Password      The password to facilitate decryption of the archive files.


   2.1.6. Script notes

   Character strings should be entered using C-language rules.
   For example, use "\\" to enter a single symbol "\".
   Special characters (format operators) such as "\n", "\r" may be used.

   The script text is stored as the archive comment in the SFX module. You
   should place an <EOF> character (ASCII code 26) at the start of the
   script in order to prevent displaying the script as the archive comment
   if the SFX would be handled with RAR itself.

   See the example of the installation script in the file standard.s. It may
   be used to create any installation package.

   Also you may extract the RAR Installation script from the RAR package. In
   order to do this you may run the "extract comment" command on the RAR SFX
   package:

       rar cw rar155.exe rarinst.s

   You will then have the RAR Installation script in the file rarinst.s

   An external install program can be placed into SFX archive to be called
   after successful completion of unpacking (e.g. from PROC ArcDone) with
   using EXEC function:

     PROC ArcDone

          EXEC DestDir, "Install.Exe"
     ENDP

   2.1.7. Technical limitations:

        Maximum script line length.............1023 bytes

        Maximum script length....................62 Kb

        Maximum parameters in command............16

        Maximum parameter length................255 bytes

        Maximum identifier (variable name,
        label) length............................31 bytes

        Maximum variable value length...........127 bytes

   In general, variables can contain numeric (4 bytes length) values or
   strings of up to 127 characters in length.