The Best of Select: Games Special 10

home *** CD-ROM | disk | FTP | other *** search

/ The Best of Select: Games Special 10 / SPSP10.ISO / xtra / rar155 / sfx.doc < prev next >

Wrap

Text File | 1995-08-19 | 23KB | 629 lines

██████╗ █████╗ ██████╗ RAR version 1.55 ██╔══██╗ ██╔══██╗ ██╔══██╗ ~~~~~~~~~~~~~~~~ ██████╔╝ ███████║ ██████╔╝ 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 favourite 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 ommited, 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 seimicolon ';' 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 dependant 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 succesful 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.