The Datafile PD-CD 5

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

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / s1 / strongbs / !StrongBS / Documents / Manual < prev next >

Wrap

Text File | 1997-06-28 | 70.2 KB | 1,903 lines

This manual is not complete yet !! If you could check it out and maybe grammer check it and send it back to me that would be very much appreciated. :-) _____ _ ____ _____ / ____| | | _ \ / ____| | (___ | |_ _ __ ___ _ __ __ _| |_) | (___ \___ \| __| '__/ _ \| '_ \ / _` | _ < \___ \ ____) | |_| | | (_) | | | | (_| | |_) |____) | |_____/ \__|_| \___/|_| |_|\__, |____/|_____/ __/ | |___/ •••••••••••••••••••••••••••••••••••••••••••• • • • v1.69 (28th June 1997) • • • • Program and documentation by • • • • © Mohsen Alshayef 1993-1997 • • • • email: mohsen@qatar.net.qa • • • •••••••••••••••••••••••••••••••••••••••••••• Freeware •••••••••••••••••••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• Manual Content ============== - Copyright Notice - Welcome 1. StrongBS Main Features. 2. What You Need To Run StrongBS. 3. Setting Up and Installing StrongBS. 4. Running StrongBS 5. Upgrading StrongBS. 6. StrongBS Basics. 7. The Squash Options 8. Squeezing BASIC programs into Applications 9. Special files and Locking variables. 10. Adding Squash Options. 11. Speeding BASIC programs. 12. Troubleshooting. 13. Frequently Asked Questions. 14. Feedback to The Author 15. Obtaining Future Versions of StrongBS 16. Credits ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• Copyright Notice ------------------ This application is Freeware The application 'StrongBS' is copyright Mohsen Alshayef 1997. I offer no guarantees as to the reliability/stability of this application or any of its functions. You may copy the application freely provided that the whole application remains unaltered. You may not sell the application without my written permission. However, Public Domain libraries may distribute the program provided they charge at most 3 pounds sterling per disc. If anyone else would like to distribute StrongBS then contact me first to get my permission. ••••••••••••••• Warning ••••••••••••••• If you do not program in the BBC BASIC language, you should not use StrongBS. If you have access to BASIC program listings that were produced by others, you should not try to compress them as you would be altering other people programs. Use StrongBS to compress your own programs only. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• Welcome Welcome to StrongBS, a utility that tries to compact and speed up your BASIC programs. StrongBS is very easy to learn and use. StrongBS is intended for any programmer writing code in the BBC BASIC language. The aim is to compact the code to the minimum size possible. Your compacted BASIC code will have the following advantages: • Small code size - smaller memory space requirement. - faster loading from disc. • Faster execution speed. • Difficult to read and understand. • Difficult to hack and modify. • Keeps your programming style and methods confidential :-) ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 1. StrongBS main features ====================== ⇨ Produces the most compact BASIC program ever. ⇨ All compression options are under user control including the removal of REMarks and spaces. ⇨ Over 65 compression options to reduce the size of your program to the minimum possible. ⇨ Modular design. You can add you own code and routines through a very simple interface, they will automatically appear as part of StrongBS ⇨ User defined compression modes. Select the options you like and define your mode so that by one click you can configure all squash options you frequently use. ⇨ Handles assembler listings very well and produces a very tight code that the BASIC interpreter can assemble. ⇨ Contains many options and methods never used in other BASIC compressor programs before. In addition to the common methods used by other BASIC compressor utilities, the following are new feature unique to StrongBS: ------------------ 1. Evaluation of expressions. 2. Removal of unused variables. 3. Removal of the Not-Equal sign. 4. Removal of SYS statements. 5. Removal of brackets. 6. Removal of WHEN and OTHERWISE statements. 7. Removal the STEP token. 8. Removal the ALIGN directive. 9. Removal of user defined debug code. 10. True removal of garbage lines. 11. True removal of colons. 12. Conversion of the CHR$ token. 13. Conversion of spaces. 14. Conversion strings. 15. Conversion of memory operators. 16. Conversion of the TRUE token. 17. Concatenation of strings. 18. Concatenation of multi-line IF structure. 19. Concatenation of DATA lines. 20. Concatenation of READ statements. 21. Concatenation of DIM statements and lines. 22. Concatenation of LOCAL statements and lines. 23. Concatenation of VDU statements. 24. Concatenation of assembler directives. 25. Removal and conversion of assembler mnemonics. * 26. Removal of nil variables. * 27. Removal and conversion of empty routines. * 28. Conversion of common numbers to variables. 29. Auto generation of Application code using additional compression. 30. Conversion of assembler instructions into coded form. Other main features are: ⇨ Handles line number references, as many GOTO's as you like! ⇨ Copes with badly written and badly structured programs. Does not complain and doesnt ask you to change your habit of programming. As long as it works, do it the way you like. StrongBS will try its best to compress it. ⇨ Handles LIBRARY files automatically. ⇨ Handles the EVAL function through use of defined locked variables either by building in your program or through a special file. ⇨ Options to keep first REM line or all start REM line in your program. ⇨ Option to attach (insert) your pre-defined REMs automatically at the start of the compressed output file. ⇨ Removes all garbage and junk lines between procedures and anywhere else in the program. Knows what a true BASIC line from a dummy one. ⇨ 8 type of concatenations that drastically squeeze your code to the limit. ⇨ Automatically removes all those unused codes, procedures and functions. ⇨ Automatically removes that debugging code that you don't want to appear in the output file. ⇨ Evaluates number expression to give you shorter numbers. ⇨ Removes brackets and knows when those brackets you used are not needed. ⇨ Simple user interface, no fiddling with script files. ⇨ Progress display while compressing. ⇨ True compression percentage of your result code! ⇨ Written in assembler for fast execution. Respectable speed. ⇨ Easy fix of any bugs and improvements. ⇨ Automatic line numbering. ⇨ Future planned cross-referencing outputs. ⇨ Through user configured modes, the application can be used for any purpose, not only a compressor. ••••••••• Hope you enjoy using StrongBS ••••••••• If you have any idea for improvement, please let me know. If you want StrongBS to do any specific task not already included or do it in a different way, let me know so that I can make a tailored version that suits your requirements. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 2. What You Need to Run StrongBS ============================= StrongBS requires and Acorn machine with the following specifications: • RISC OS 3.10 or later. • A minimum of 1 Mb of ram free. • Floppy or hard disc space (minimum 200 Kbytes). To date StrongBS has been fully tested on the following machines: 1. A5000 with 4Mb ram - RISC OS 3.10 2. RiscPC 700 36Mb ram - RISC OS 3.60 3. RiscPC StrongARM 64Mb ram - RISC OS 3.70 Compressed BASIC programs generated by StrongBS has been tested and will work with the following versions of BBC BASIC: 1. BASIC V version 1.05 2. BASIC V version 1.06 3. It is expected that the compressed BASIC program generated by StrongBS will work with future versions of the BBC BASIC language. If you used StrongBS with different machine specifications or later versions of BBC BASIC, please notify the Author (see email address above), so that the tested configurations and BASIC versions can be added to the above list. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 3. Setting Up and Installing StrongBS ================================== StrongBS comes supplied in an archived form. You will need to de-archive it first. The method of archiving used may vary depending on the version supplied, in any case you will need the application SparkFS or SparkPlug to de-archive it. If you have obtained StrongBS from a PD library or downloaded it from an FTP server then you will need to obtain SparkPlug or SparkFS from the provider. All copies supplied by the Author either to individuals or PD libraries are archived using SparkFS Zip format. It is recommended that StrongBS is installed on a Hard disc for faster access, however StrongBS will happily work from a floppy disc ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 4. Running StrongBS ================ Once installed, StrongBS can be started by double clicking on its icon in the directory viewer. The StrongBS icon will appear on the icon bar and from now on you are ready to start. Click the mouse menu-button over the application icon to view the main program menu. StrongBS has two windows; the main window which can be opened by clicking the mouse select-button on the icon-bar icon, and the Choices window opened by selecting the "Choices.." option from the main menu. StrongBS has only one main menu which can be called by pressing the menu button on any part of StrongBS application windows or its icon bar icon. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 5. Upgrading StrongBS ================== If you are upgrading to a new version of StrongBS, then you may want to maintain your previous defined modes, Library files and Remark files. To do this, just drag the new StrongBS directory onto the old StrongBS directory, this will cause all old similar files to be updated with new ones and new files added. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 6. StrongBS Basics =============== As you work with StrongBS, there are few basic terms you need to become familiar with. • 3rd Party Directory A directory that contains the code of all additional "Squash Options" written either by you or someone else. Any code added will appear under the 3rd Party menu. • 3rd Party Option A Squash Option that is added by the user or a 3rd party. See adding squash options for more details. 3rd Party Option codes reside in the "3rd Party Directory". • Assembly Means an assembler BASIC listing within the main or "Library File". An assembly listing is one that starts with the open square bracket "[" and ends with a close square bracket "]". • Concatenation A compression method used by StrongBS to join (concatenate) things together in order to produce a shorter equivalent. • Convert The process used by StrongBS to convert something into another shorter equivalent. There are many conversion options to select from. • Debug code Part of your BASIC program that contains a code you are using during the testing and debugging of your program. If you want this code to be completely removed, then StrongBS will do so if you tell it the whereabouts of this debug code. • Label Means an assembler label that starts with a dot ".". • Library Directory A directory that contains "Library-Files". StrongBS will only lookup the first 64 valid "Library-Files" in the directory. Valid files means BASIC program files. The "Library Directory" is normally located within StrongBS application. StrongBS comes with a directory called "Library" that contains example library files. If your preferred library files are located elsewhere on the disc, then simply change the <StrongBS$Library> variable in the !Run file to point at that directory. • Library-File Is a BASIC File that is located in a Library Directory and is displayed by StrongBS in the "Library files" sub-menu. Any selected library file will be automatically appended to the end of the core BASIC program before at the time StrongBS loads your main BASIC program. The library file gets compressed along with the main program, so that options set to the main program also apply to the Library File. The result compressed file contains both your main program and any library files. StrongBS will only display the first 64 files found in the Library directory. You can select more than one Library file from the "Library files" menu. • Log file Is a file that contains all statistical and other details about your BASIC program, before and after compression. The content of the log file is user defined. • Modes Directory A directory that holds user defined "Squash Modes". Up to 32 user modes may be defined. • New Size The result of the compressed "Output File" size. "New Size" is displayed and updated after each compression option is performed. • Output File Means the result compressed output file including any appended library files. • Percentage The percentage ratio and size reduction of the "Output File" compared to the "Source File". Percentage is updated after each compression and displays the percentage in one hundredth of a unit. Looking at the percentage you can immediately tell if any savings have been made. • Progress Bar A progress indicator bar that gives the indication of how many options are still to be applied and how much have been already performed. • REMarks-Directory A directory which contains "REMark-Files". StrongBS will only display the first 32 valid "REMark-Files" in the directory. The path of the "REMarks Directory" is pointed to by the variable <StrongBS$InsertREM> found in the !Run file, you may change this to point at any other directory you prefer. • REMark-File An "REMark-File" is a file that will be automatically inserted at the start of the compressed output result file. A REMark-File can be added to the "REMarks-Directory". Only one "REMark-File" can be selected from the REMark-File menu. You may have up to 32 REMark-Files. • Remove The process used by StrongBS to remove something from your BASIC program that is not necessary, redundant or not required. There are several removal options to select from. • Routines Routines are BASIC functions or procedures defined using DEF FN or DEF PROC. • Size The original size of the main "Source File" program including the size of all loaded "Append" files. • Source File The "Source File" is your main BASIC program that is loaded for compression including any appended library files. • Special file A file that contains information that StrongBS uses and applies to the methods used for compressing the current program. A "Special File" is a text file that you write to tell StrongBS what to do with the current BASIC program in question. You can use it to define variables and/or procedure/function names that should not be renamed. StrongBS can automatically load Special files for each particular BASIC program you load for compression. Note: the "Special-File" is an option, it is not a must have or use. • Squash Option A "Squash Option" is an option that is selectable from the Squash Options menu. StrongBS comes with over 60 different options to select from. • Squash Mode A Squash Mode, is a collection of "Squash Options" that is pre-defined. StrongBS comes with three built-in Squash Modes. You can add your own Squash Modes. • User Mode Is a user defined "Squash Mode" that can be created by the user and gets added automatically to the "Squash Mode" menu. "User Modes" are stored in the "Modes Directory". • Variable A variable means any real, integer, string, real array, integer array or string array, as defined by BASIC rules. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 7. The Squash Options ================== 7.1 General and introduction ------------------------ StrongBS provides a large number of options that can be used to reduce the size of a BASIC program. Some 60+ options are avialable. The purpose of this Chapter is to biefly explain what each option does. Squash Options are divided into 10 categories: 1. Assembler 2. Routines. 3. Variables. 4. Convertion. 5. Concatenation. 6. Removal. 7. Remarks. 8. Constructs. 9. Miscellaneous. 10. Make faster. Although, in the following description, use is made of the words remove, convert, etc., StrongBS will only perform an operation such as removal of a code or conversion of a token, etc., if the test conditions which apply to the particular operation are met. For example when removing brackets, StrongBS will test the mathematical operator priority of each operator inside and outside the brackets. StrongBS also makes allowance for bugs in the current versions of the BASIC interpreter (or as Acorn prefer to call them "features") and will ensure that the result BASIC file runs correctly. The following description does not explain HOW StrongBS does it, it only gives a brief description of what each option means and what are the expected results. It is assumed that you are familiar with BASIC and the BASIC assembler. 7.2 Assembler Squash Options ------------------------ This category provides 11 squashing options. These options will only work on assembler listings inside a BASIC program. Although BASIC programs are very rarely distributed with an assembler source code, if you decide to distribute the source code because the program needs to generate the code at run time then StrongBS will aid in compressing the assembler listing. 7.2.1 Remove assembler remarks ------------------------ This option will remove all remarks inside an assembler listing. Remarks in the main program (outside and assembler) will not be removed. 7.2.2 Remove zero shifts ------------------ This will remove LSL #0, LSR #0 and ASR #0 in the assembler listing. 7.2.3 Remove ALIGN directives ----------------------- Unnecessary ALIGN directives found in the assembler listing will be removed. An ALIGN directive is not required, if it is followed by an instruction. 7.2.4 Convert register names ---------------------- All register names in the form of R0, R1, PC etc will converted into a register number form, i.e. 0, 1, 15 etc.. Note: This option is automatically selected if you select the "Variables Renaming" option, as register name are considered by StrongBS another form of variables! 7.2.5 Convert SWI name ---------------- All SWI names in an assembler listing will be converted into their SWI number equivalents. SWI names that can not be converted will be left as is. Therefore, if a SWI name is only existant in a module that is not currently loaded, all SWI names for the that module will not be changed. You will have to load the module before compressing the BASIC program. StrongBS will not complain about the non-existance of the module. 7.2.6 Convert directives ------------------ This option allows all assembler directives in the form EQUD, EQUB and EQUW to be converted into DCD, DCB, DCW respectively. 7.2.7 Convert zero offset ------------------ This will convert all occurrences of zero offsets in load and store instructions into the shortest form. LDR R0,[R1,#0] -----> LDR R0,[R1] LDR R0,[R1],#0 -----> LDR R0,[R1] Note: Due to what seems to be a bug in the BASIC assembler, the LDRT Rd,[Rn],#0 or STRT Rd,[Rn],#0 will not be converted as the BASIC assembler will treat the shorter instructions differently. 7.2.8 Convert register list --------------------- This option is not yet enabled in this version of StrongBS. Once enabled, the option will allow converting a register list in the STM and LDM instructions into the shortest form. LDMFD R13!,{R0,R1,R2,PC} ------> LDMFD R13!,{R0-R2,PC} 7.2.9 Convert to shortest directives ------------------------------ This will convert all EQUD, EQUB, EQUW, EQUS, DCD, DCB and DCW into the shortest form using the "&" and "=" directives. EQUS ------> = EQUD or DCD ------> & EQUB or DCB ------> = EQUW or DCW ------> = 7.2.10 Concatenate directives ---------------------- This option will reconstruct all those directives by assembling the directives and de-assembling them back into a the shortest possible form. It can cope with all type of directives and the CHR$ keyword. With long directive listings, this can produce a very short and compact BASIC programs. 7.2.11 Assemble into Code ------------------ This option will convert (assemble) all ARM instructions into the equivalent 32-bit value and use the & directive in place with the instruction. For example: MOV R0,R1,LSL #2 becomes &&E1A00101 LDMFD R13!,{R0-R12,PC} becomes &&E8FD9FFF ORREQ R10,R10,R11,LSL #8 becomes &&018AA40B 7.3 Routines Squash Options ------------------------ Five options are provided that work on procedures and function. 7.3.1 Rename functions ---------------- This will rename functions using the shortest possible string. One or two character names are used, with shorter names allocated to the most frequently used functions. 7.3.2 Rename procedures ------------------ This will rename procedures using the shortest possible string. One or two character names are used, with shorter names allocated to the most frequently used procedures. 7.3.3 Remove unused functions ----------------------- A function definition that is not called in the main program or any Library file will cause the complete function to be removed. 7.3.4 Remove unused procedures ------------------------ A procedure definition that is not called in the main program or any Library file will cause the complete procedure to be removed. 7.3.5 Remove empty procedure ---------------------- This option will remove empty procedure. 7.4 Variables Squash Options ------------------------ Nine options are provided that work on all type of variables. 7.4.1 Rename Integer variables ------------------------ Integer variables are renamed using one or two character variable names. 7.4.2 Rename Real variables --------------------- Real variables are renamed using one or two character variable names. 7.4.3 Rename String variables ----------------------- String variables are renamed using one or two character variable names. 7.4.4 Rename Integer arrays --------------------- Integer array variables are renamed using one or two character names. 7.4.5 Rename Real arrays ------------------ Real array variables are renamed using one or two character variable names. 7.4.6 Rename String arrays -------------------- String array variables are renamed using one or two character variable names. 7.4.7 Rename vars in DATA lines ------------------------- This option renames variables found inside DATA lines. 99% of the time this OK. However, it is possible that DATA lines contain data which although not being a variable is identical to a variable name in the program. For this purpose and only in this rare situation you can disable this option. 7.4.8 Remove unused variables ----------------------- Unused variables are those that are only encountered once in the program, ie defined but not used. There are exceptions where some variables which fall into this discription will not be removed as they will be required for proper program execution. StrongBS will, depending on the unused variable location, either remove the variable only or remove the whole statement or the complete line. 7.4.9 Remove nil variables -------------------- This option is not yet enabled in this version of StrongBS. 7.5 Conversion Squash Options ------------------------- Ten options are currently provided in this category. Another 2 options will be enabled in the next releases of StrongBS. 7.5.1 SYS names to numbers -------------------- All SWI names in an a SYS statement will be converted into their SWI number equivalents. SWI names that can not be converted will be left as is. Therefore, if a SWI name is only existant in a module that is not currently loaded, all SWI names for the that module will not be changed. You will have to load the module before compressing the BASIC program. StrongBS will not complain about the non-existance of the module. 7.5.2 CHR$ to string -------------- This will convert a CHR$<no> into a string provided the result string can be joined to the end or the start of an existing string. 7.5.3 ASC" " to number ---------------- This will convert an ASC<string> into the equivalent ASCII code. 7.5.4 NEXT <var> to NEXT or NEXT,, ---------------------------- This option all cause any optional variable after the NEXT keyword to be removed. Also repeated NEXT statements on the same line or multi-lines will be concatenated. 7.5.5 -1 to TRUE ---------- The integer -1 is replaced with the BASIC token TRUE whenever possible. 7.5.6 Numbers to shortest form ------------------------ This option will convert numbers into the shortest representation. It can cope with decimal, hexadecimal, binary and shifted numbers. The shortest form of the 4 possible representation will be used. 7.5.7 Memory operators to shortest ---------------------------- Memory indirection operators such as ? and ! will be converted into the shortest possible form. Examples: pointer%?0=A% ?pointer%=A% pointer%!0=A% !pointer%=A% ?(pointer%+3)=A% pointer%?3=A% !(pointer%+4)=A% pointer%!4=A% 7.5.8 Repeated spaces to SPC ---------------------- Repeated spaces in a string will be converted into SPC. 7.5.9 Repeated chars to STRING$ ------------------------- Repeated characters in a string will be converted into STRING$. 7.5.10 *FX to SYS "OS_Byte" ==================== This option will convert *FX calls into their equivalent SYS call using SYS "OS_Byte" or SYS 6. 7.5.11 var=var+|-x to var+|-=x ----------------------- This option is not yet enabled in this version of StrongBS. 7.5.12 Common numbers to variables --------------------------- This option is not yet enabled in this version of StrongBS. 7.6 Concatenation Squash Options ---------------------------- Nine options are currently provided in this category. 7.6.1 Concatenate Lines ----------------- This option will join all lines and statements to produce multi statements per line. 7.6.2 Concatenate LOCAL lines ----------------------- This option joins together all LOCAL statements and LOCAL lines. 7.6.3 Concatenate DIM lines --------------------- This option joins together all DIM statements and DIM lines. 7.6.4 Concatenate DATA lines ---------------------- This option joins together all DATA statements and DATA lines. 7.6.5 Concatenate IF...ENDIF lines ---------------------------- This option will convert multi-line IF...THEN...ELSE...ENDIF into a single IF..THEN..ELSE statements. 7.6.6 Concatenate strings ------------------- This option concatenates strings in the form <string1>+<string2> into one string. 7.6.7 Concatenate READ statements --------------------------- This option joins together all READ statements and READ lines. 7.6.8 Concatenate VDU statements -------------------------- This option joins together all VDU statements and VDU lines. 7.6.9 Concatenate PRINT statements ---------------------------- This will convert multi PRINT statements into the shortest form. 7.7 Removal Squash Options ====================== Fifteen options are currently provided. 7.7.1 Removal of remarks ------------------ This will remove all REMark lines in the main program and in any attached libraries. It will also cope with *Command remarks. 7.7.2 Removal of garbage lines ------------------------ Garbage lines are those between procedures and at other locations that will never be reached by the program code. These are removed. StrongBS will also remove garbage lines in between BASIC program code which are normally skipped by the program either by use of GOTO's or other constructs. A line is not removed if it is referenced by another part of the program. 7.7.3 Removal of blank lines ---------------------- Blank (empty) lines are removed. A line is not removed if it is referenced by another part of the program. 7.7.4 Removal of spaces ----------------- Unuecessary spaces are removed. 7.7.5 Removal of brackets ------------------- Unnecessary brackets are removed. 7.7.6 Removal of colons ----------------- Unnecessary colons between statements and between lines are removed. 7.7.7 Removal of fractions -------------------- Unnecessary fractional parts in floating point (real) number are removed. Example: X=0.0 becomes X=0 X=0.1200 becomes X=.12 7.7.8 Removal of "not equal" sign --------------------------- The unnecessary "<>0" sign is removed if found in IF, WHILE and UNTIL statements. Examples: IF var<>0 THEN becomes IF var THEN WHILE var<>0 .... becomes WHILE var .... UNTIL var<>0 becomes UNTIL var 7.7.9 Removal of THEN --------------- The "THEN" in a single line IF..THEN..ELSE is optional and will be removed if found. 7.7.10 Removal of LEN -------------- This option is not yet enabled in this version of StrongBS. 7.7.11 Removal of LET -------------- The redundant LET is removed if found. 7.7.12 Removal of STEP --------------- This option removes "STEP 1" in FOR...NEXT loops. 7.7.13 Removal of SYS -------------- This option removes unnecessary 0's in SYS calls. For example: SYS "OS_xxx",0 becomes SYS "OS_xxx" SYS "OS_xxx",A%,0 becomes SYS "OS_xxx",A% SYS "OS_xxx",0,A% becomes SYS "OS_xxx",,A% etc... 7.7.14 Removal of debug code --------------------- Any lines bracketed between the identifiers "REM --[" and "REM ]--" will be removed. 7.7.15 Removal of +/- assignments -------------------------- This will remove unnecessary +0 or -0 in assignments. Examples: X%=Y%+0 becomes X%=Y% Y=Z-0 becomes Y=Z etc... 7.8 Remarks Squash Options ====================== 7.8.1 Keep first REM line ------------------- This option will only only the First REMark line to be preserved. All other REMark lines will be removed, is the "Remove REMarks" option has been selected. 7.8.2 Keep initial REM lines ---------------------- This option allows ALL REMark lines appearing at the start of a BASIC program to be preserved, and will appear in the final output file. 7.8.3 Keep REM starting with ---------------------- This option allows REMark lines starting with a sequence of text or characters to be preserved everywhere in the program, and hence will not be removed. 7.8.4 Insert REMarks file ------------------- This allows a BASIC program file to be inserted at the start of the compressed output file. These will normally be BASIC files containing remark lines, but can be any BASIC file. The file is selectable from a list of files contained in the REMInsert directory. Only one file can be selected. 7.9 Constructs Squash Options ========================= 7.9.1 Remove empty IF constucts ------------------------- Empty IF..THEN..ENDIF constructs are removed. 7.9.2 Remove empty CASE construct --------------------------- Empty CASE...ENDCASE constructs are removed. 7.9.3 Remove duplicate WHEN statements -------------------------------- This option is not yet enabled in this version of StrongBS. 7.9.4 Remove empty WHEN statements ---------------------------- Empty WHEN statements in CASE...ENDCASE constructs are removed. 7.9.5 Remove empty OTHERWISE statements --------------------------------- Empty OTHERWISE statements in CASE...ENDCASE constructs are removed. 7.9.6 Convert CASE to IF construct ---------------------------- Converts a CASE...ENDCASE construct into the equivalent IF..ENDIF construct which is faster to execute..!! 7.9.7 Concatenate WHEN statements This option is not yet enabled in this version of StrongBS. 7.10 Miscellaneous Squah Ooptions ============================ 7.10.1 Evaluate expressions -------------------- This option allows mathematical expressions to evaluated to produce a shorter equivalent. Currently, only simple expressions are parsed and evaluated, future versions of StrongBS will improve on this. 7.10.2 Line numbering -------------- This option will re-number the program with increments of 10 or which ever is suitable for the particular size and number of lines in the program. 7.10.3 Insert Squash info ------------------ This will insert the line: REM Squashed by StrongBS v.vv on dd mmm yyyy at the start of the output file. 7.11 Make Faster =========== 7.11.1 Convert 0 to FALSE This will convert any 0 into the FALSE token. 0's inside assembler listings and *Commands will not be converted. 7.11.2 Convert DIV to >>> This option is not yet enabled in this version of StrongBS. 7.11.3 Convert AND to IF This option is not yet enabled in this version of StrongBS. 7.11.4 Convert real vars to integers This option is not yet enabled in this version of StrongBS. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 8. Squeezing BASIC programs into Applications ========================================== StrongBS allows you to further squeeze a BASIC program into a file of the type Absolute (&FF8), which can be run just like the original program. The converted program has the advantage of smaller size and is safer against unwanted copying and modifying, because it isn't easily recognizable as a Basic program. StrongBS will try to squeeze the BASIC program using its own method which is similar to that of an LZW method. If the squeezing fails, then the program will not be converted into an Absolute type. There is one important thing you should always remember: If the original BASIC program reads the command line parameters, then the command line parameters would not be passed to your program. You should use an alternative method of using system variables in the !Run file. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 9. Special files and Locking Variables ==================================== The purpose of the Special files is to inform StrongBS what variables should not be renamed. A special file is a text file with a list of variable names. Variables may be locked against renaming using one of two methods: 1. Using REM lines in the BASIC program: You can use a REMark line like this: 10 REM LOCK var1, var2, var3, ..... The variable names after REM LOCK will not be renamed. Variables may be seperated by colons or may be entered on more REM LOCK lines. StrongBS searches the complete program for REM LOCK lines, so REM LOCK lines can be anywhere in the program. 2. Using a Special file: The "Special File" is a text file that lists all variables and routine names that you don't want StrongBS to rename. The first word of the file should be the word "LOCK:" on a separate line. Following this, you list your variables. Please note that this is the word "LOCK" immediately followed by a colon. When listing your variables, you can either list each variable on a separate line or separate them by commas. You can use comments if you like using any of the following reserved characters # or \ or | anywhere in the Special file. Here is an example: LOCK: \The following are the variables that are not to be renamed: menu_pointer%( menu_string$( menu_icon% icon%,icon_flag%,icon_size% \The following are the routines that are not to be renamed PROCcreate_menu FNmenu_width Note: The Special file must always end with a blank line. Note: An array variable should be entered until the first opening bracket only. i.e. for pointer%() use pointer%( You can use "REM LOCK", any where in your program. You can separate variable names with a comma. You can have as many "REM LOCK" lines as you want. Automatic loading of Special files: =================================== This feature allows you to customise a special file for each one of your BASIC programs. StrongBS will automatically search the current directory (from where the loaded BASIC program comes) for the Special file called "SBSLock" if it finds one, it will automatically load it in. This feature can be enabled or disabled in the Choices window. You can tell that a Special file is loaded by observing the "Special file" indicator on StrongBS main window (next to the Squash button) which will show one of the following messages: - "Loaded" : a Special file is loaded and will be used. - "Not required" : a Special file is not required for this loaded BASIC program because it has no EVAL functions. - "Required" : Some EVAL functions found but no Special file has been loaded. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 10. Adding Squash Options ===================== StrongBS allows you add more "Squash Options" to the existing ones. Options added will automatically appear under the "3rd Party Options" menu. Note: Any type of option can be added. The option does not necessarily have to be a compression or squashing type. A maximum of 32 new Squash Options may be added to the 3rd Party Options menu. If you write any additional options then send me a copy so that it can be included with future versions of StrongBS. The code you write becomes Freeware and the conditions that apply to StrongBS will automatically apply to your code. • How to write your own code? --------------------------- 1. You will need to write your code in assembler. 2. You don't have to worry about where to store or load the main BASIC program, or your code. StrongBS will take care of that. 3. Write your code and test it separately. 4. When satisfied that it does what it should, then you can add your code to the "3rdParty" directory, and append some details about your code in the "CodeList" file. A simple example code is given in the 3rdParty directory, have a look at it and also at the "CodeList" text file to get some idea. 5. Here is the most important bit your code should do: (a) The first 4 bytes (one word) at the start of your code should be &00000 (i.e. zero). (b) StrongBS calls your code at (code start address)+4 (c) The first 4 bytes are reserved so that in future it will be used to pass info (request something) from StrongBS before it executes your code. (d) Your code will be called after all other compression options have been performed. This is important to keep in mind, the program passed to your code is a highly compressed BASIC program!! (e) StrongBS will pass the following information to your code to tell you where the source program is and where it expects you to store the result. Note: Use is made of memory, no disc access required. ----------------------------------------------------------------------- | On entry: StrongBS will pass the following to your code: | | --------- | | R0 - Memory start address of "Source Program" in memory | | R1 - Memory start address to store "Output Program" | |---------------------------------------------------------------------| | On exit: Your code should return the following to StrongBS: | | -------- | | R0 - End address of "Output Program". (i.e. end of | | new result program). | | If an error occurred then set bit 31 of R0 and | | bit 0-7 to the error number. Bits 8 to 30 will | | be the line no. of the program where error occurred. | | | ----------------------------------------------------------------------- It is very important that you pass back the end address of the result "Output Program" in R0. StrongBS uses this to calculate the new size of "Output Program" you have generated. "Output File size" = R0 - R1 on entry. Your code gets called by StrongBS front end program which is a BASIC program. So your code is called like this (assuming that your code is loaded by StrongBS in buffer memory code%): A% = Source_Prog_Start% B% = Result_Prog_Start% Result_Prog_End% = USR (code% + 4) You should preserve registers that are important to basic like R13 and R14. Any others are free for your code except that you should return result back in R0. StrongBS does not offer you any supporing routines, therefore your code should work on the whole program from start to end. Your code does not have to perform compression! it could do anything to the BASIC program. The result file could be larger than the original! You don't have to worry about size allocated to the result file in memory. In fact you could perform de-compression of the file, although this is not suggested as it is against the purpose of StrongBS. • Important Notes About Your Code ------------------------------- 1. You must remember that the "Source File" BASIC program passed to your code can be very tightly compressed. Your code should be able to handle this. Therefore, at the testing stage of your code, you should ensure that it does cope with compressed BASIC program listings!! 2. The status of the "Source File" BASIC program passed to your code depends on what options have been selected by the user. 3. You should not assume that REMarks or spaces have already been removed. The user may not have selected these options. Therefore, your code should make allowance for REMarks and spaces and ignore them. 4. Your code should come up with something new, a new option or replace an existing option code. If you think an existing option does not produce the results you want, I suggest you contact me rather than coding your own code. StrongBS is built around some 72 separate codes, these can be very easily changed and customized with very little modification. If you have a new idea for an option that you want to test and experiment with or you are developing another application and think that some of the code used in StrongBS may be applicable or may help speed-up the development stage of your application, let me know so that I could send you some of the source code of the routines and sub-routines I use in StrongBS. The current version of StrongBS assumes that your code can be executed from memory and it will load your code into memory and then call it. StrongBS doesn't allow (yet) 3rd party options to be written as a stand alone application that can be run using the command line nor does it allow the BASIC program to be passed to your code as a file. This may however change in future versions. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 11. Speeding BASIC Programs ======================= The speed of execution of any program is not just determined by the power of the microprocessor, but also by how the program is written. One way of speeding up BASIC programs is to use integer variables instead of floating point variables, this also reduces the memory space required for storage of the variables. Another aspect is the structure of the program and the way you choose your BASIC keywords. This might have a significant effect on the speed. Of course StrongBS can't do anything about your programming style and will not be able to re-structure a an interpreted BASIC program. Once a program has been debugged, the final version can be doctored to work much faster. This is where StrongBS comes in. The many options in StrongBS all work towards speeding up your program and reducing its size. StrongBS can improve your program speed by 20% to 30% and reduce it size to 30% - 60% of the original size. A smaller BASIC program allows your program to be very responsive in the desktop environment. Hints for speeding-up your BASIC programs: ------------------------------------------ 1. Use integer variables instead of floating point variables. 2. Use a FOR...NEXT loop instead of a REPEAT...UNTIL or WHILE...ENDWHILE. The FOR...NEXT loop is much faster. 3. When comparing more than 2 variables avoid using AND. Use IF instead. For example: IF D%=15 AND M%=12 AND Y%=1997 THEN PRINT "something" can be replaced with the faster equivalent: IF D%=15 IF M%=12 IF Y%=1997 THEN PRINT "something" 4. In a comparison structure like in IF structure or CASE structure, place the most common condition first. This will speed execution. For example: CASE condition% OF WHEN 32: PROCspaces WHEN 13: PROCcr WHEN 10: PROClf ENDCASE In the above example the WHEN 32 is placed first because it is expected to occur more often than the rest of the conditions. 5. Avoid use of calculations inside a loop structure, if at all possible. 6. Finally, use StrongBS to produce shortcuts and compress your program. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 12. Troubleshooting =============== 1. When I run the compressed output program, the error "Unkown or missing variable" is generated. It is most likely that your program contains an EVAL keyword. Ensure that any variables that are passed to the EVAL function as strings, are not renamed by telling StrongBS not to rename these variables (LOCKed variables). See 9 above. 2. When I changed some lines in the compressed BASIC program that was created by StrongBS using my favourite editor, the program failed to run and produces errors. It was OK before loading into the editor. What is happening? All editors that handle BASIC programs use either their own code or the built-in BASIC code for tokenising the BASIC line. Secondly some editors work on your BASIC program in text (Ascii) mode not in a tokenised mode, this will even give more errors. The problem is due to the fact that the compressed program has all spaces removed. When tokenising a BASIC line, BASIC and other applications need a space between a BASIC keyword and a variable, else they get confused and they will not tokenise the BASIC keyword, thinking that it is a variable. If the BASIC keyword is not tokenised, this will result in the length of the BASIC line being changed becoming larger than the original. If the line length is already close to the maximum allowed limit of 251 bytes per line, it is possible that this limit is exceeded and your editor will give an error that "Line too long". If the line length wasn't exceeded then your editor will happily tokenise the line but using the character equivalent of the BASIC keyword not it's token. When you come to run the program, BASIC will complain that it does not know the particular keyword. If you use the BASIC "LIST" keyword to list the line, you will not be able tell what the problem is, nor if you use an editor that does not show BASIC keywords in a different color. I personally recommend that, if you edit BASIC programs, use an editor that allows you to distinguish BASIC keyword from the rest of the program and most importantly, avoid editing a compressed program. 3. My compressed output file failed to run!!! 1. Ensure that your BASIC program does not contain the BASIC keyword "EVAL". If it does, then ensure that if "EVAL" is used to evaluate variables or procedure names, these should not be renamed. You will need to lock these variables from being renamed by StrongBS. See FAQ blow on how to do that and 9 above. 2. If all EVAL variables are locked, as indicated above, and your compressed program still fails to run then disable all variable renaming and try again. If it did work, then you have discovered a bug in StrongBS, for which I appreciate that you inform me so that I can correct it. You can try compressing with some options disabled to see which option causes the problem. Please see the Section "Feedback to the Author". 4. When double clicking on the StrongBS icon, to start it, nothing happens! You copy of StrongBS has become corrupt, try to install StrongBS again. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 13. Frequently Asked Questions ========================== 1. I am not interested in the many Squashing Options that StrongBS has, I just want to load my program and its accompanying libraries and produce an output that contains my main program plus the procedures and functions in the LIBRARY files that the main program needs. I don't want to remove anything else or compress anything. Can StrongBS do that for me? Just tell StrongBS what you want, and it will do it. To answer your requirement, do the following: 1. Copy you LIBRARY programs to the "Library" directory. 2. Startup StrongBS. 3. Clear all Squash Modes by clicking on the "Clear All" entry in the "Squash Options" menu. This action clears all selected options. 4. Select "Remove unused functions" and "Remove unused procedures" from the "Squash Options Routines" sub-menu. 5. Select your LIBRARY files from the "Append-File" menu and load your main program. 6. Now you can press the "Squash" button to generate the result file. In the above example we have created a new mode that only removes unused functions and unused procedures. If you want you can add it to the "Squash Modes", so next time you do not have to repeat the above process. StrongBS comes with a Squash mode called "Library" that just removes unused procedures and functions, this can be selected from the Squash options menu list. 2. I want StrongBS, on startup, to automatically select my favourite Squash Mode. How can I do that? Load the "Messages" file located in the "Resources" directory into your text editor. Locate the token "SquashMode:". The number after the token is the default startup Squash Mode, change it to the mode you like. The numbers mean: -1 Custom Mode (this is StrongBS default mode). -2 Full including 3rd Party. -3 Full mode 0 First user defined mode. 1 2nd user defined mode. 2 3rd user defined mode, and so on.... Note: StrongBS defaults to "Custom Mode" if the mode number is invalid. 3. I want to change the color of the progress bar. How can I do it? Load the "Messages" file located in the "Resources" directory into your text editor. Locate the token "BarColor:". The number after the token is the default color, change it to a color number between 0 to 15. 4. I have a LIBRARY file that I want StrongBS to compress along with my program, how can I tell it to? You can copy your LIBRARY file to the "Library" directory, then start StrongBS. On startup StrongBS will list your LIBRARY file under the "Library Files" menu. Tick your LIBRARY file in the "Library Files" menu list and from now on it will be compressed along with your main program. You should remember that any library file will only be loaded at the time StrongBS loads the main program, so if you had already loaded your main program and then selected the libraries you will need to load the program again so that the libraries get loaded with it. 5. What is "Debug code removal"? how can I use it? I have lots of code of this sort in my program, and I just don't want it to be compressed, I want it to be removed. How can I do that? Any code that you want to be removed completely, and not appear in your output compressed BASIC program can be bracketed between two identifiers, so that StrongBS knows about it. The start identifier is "REM --[" and the end identifier is "REM ]--". Anything between these two identifiers will be completely removed. Here is an example: 10 ....... 20 REM --[ 30 debug%=TRUE 40 REM ]-- 50 ....... ..... 1030 ....... 1040 REM --[ 1050 IF debug% THEN PROCdebug_msg 1060 REM ]-- 1070 ....... ....... 4000 REM --[ 4010 DEF PROCdebug_msg 4020 .....some more debugging code ... 4030 ............ 4040 ENDPROC 4050 REM ]-- 4060 .... ........ In the above example program, all code that would only be used during the development stage for debugging is bracketed between the two identifiers. If the option "Remove Debug" is selected, then StrongBS will automatically remove lines 20 through 40, lines 1040 through 1060 and lines 4000 through 4050. 6. I want to create my own "Squash Modes". How can I do that? First, setup the squash options you need by selecting those you need and de-selecting those you don't. Now go to the "Create New Mode" sub-menu in the "Squash Modes" menu. Enter the "Mode Title", this is the title of the mode that will appear in the Modes Menu, and enter the "Mode File", this is the filename under which your mode definitions will be saved into the Modes Directory. Press "SAVE" when ready. If you now, go to the "Modes Menu" you will see the "Squash Mode" you have created listed and selected as the current Squash-Mode. 7. How can I remove a "Squash Mode" that I have created from the "Squash Modes" menu? In the "Modes Directory", locate the filename that contains the mode definition and delete it. Now re-start StrongBS, it will be gone. 8. I only have two variables that I don't want StrongBS to change. I don't want to use a "Special File", is there a shortcut? You can use a REM line in your program. Follow the REM keyword with the word "LOCK" and then your variable name. Here is an example: If you want the variables memory_area% and pointer%() not to be renamed, then you should have the following line in your program: 1000 REM LOCK memory_area%,pointer%( Important Note: An array variable should be entered until the first opening bracket only. i.e. for pointer%() use pointer%(. You can use "REM LOCK", any where in your program. You can separate variable names with a comma. You can have as many "REM LOCK" lines as you want. 9. Can I re-compress the result program again to gain further savings? Yes, you can do that by clicking the "Squashed" button again as many times as you like. StrongBS will try its best to produce the best compression from the first pass. Some routines have been optimised to do that already, however, some routines still don't achieve all they could from the first pass, and a second compression pass may squash the program further saving on few bytes! 10. How can I tell StrongBS about my "Special File" which contains my locked variables? Just drop your "Special File" into StrongBS. StrongBS will then use it for the current BASIC program already loaded into memory. You should load your BASIC program BEFORE loading the Special File. When loading a BASIC program, StrongBS ignores any previously loaded Special files. StrongBS can automatically load a special file for each BASIC program that you load. See Chapter 9 above. 11. I have a program that has locked variables defined after the "REM LOCK" keyword, can I add more locked variables using a "Special File"? Yes. Any locked variables in a "Special File" are added to those already defined in your program after the "REM LOCK" keyword if any. 12. In what format should I write the "Special File"? The "Special File" is a text file that lists all variables and routine names that you don't want StrongBS to rename. The first word of the file should be the word "LOCK:" on a separate line. Following this, you list your variables. Please note that this is the word "LOCK" immediately followed by a colon. When listing your variables, you can either list each variable on a separate line or separated them by commas. You can use comments if you like using any of the following reserved characters # or \ or | anywhere in the Special file. Here is an example: LOCK: \The following are the variables that are not to be renamed: menu_pointer%( menu_string$( menu_icon% icon%,icon_flag%,icon_size% \The following are the routines that are not to be renamed PROCcreate_menu FNmenu_width Note: The Special file must always end with a blank line. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 14. Feedback to the Author ====================== The Author encourages any one using this application to report any bugs and/or errors that are discovered in StrongBS itself or in the result compressed program. The Author also welcomes any suggestions and ideas for improvement. Bug reporting: -------------- If you find a bug then please give me as many details as possible as to the circumstances that cause it, try and get it repeatable. Try to isolate it to an individual Squash Option by compressing your program using one or group of options at a time. You may send me your original un-compressed BASIC file that produces the error. If you do that please ensure that the program you send is a stand alone program, i.e. does not need other resources to run, like Template files, !Run files, Sprite file, etc.. A bug in StrongBS may not cause an error message to be generated when your compressed program is run, it may cause it to behave differently!! You can also give detailed useful info by comparing the line of the compressed BASIC program that gives the error with the original line of the un-compressed program, to do that de-select the "Line Numbering" option, to speed line number comparison. Suggestions for improvement: ---------------------------- If you have any suggestions and/or ideas for improvement that you want to see in StrongBS, please let me know, so that every one can benefit. Contacting me: -------------- You can contact me by email: mohsen@qatar.net.qa If you want to send any program you could send them as attachments to the email message using any encoding/attachment you prefer. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 15. Obtaining future versions of StrongBS ===================================== I will be sending any future versions of StrongBS to: 1) Hensa: e-mail: archive-server@micros.hensa.ac.uk ftp : micros.hensa.ac.uk (IP 148.88.8.84) 2) The Archimedes Public Domain Library (run by David Holden): 39 Knighton Park Road Sydenham London SE26 5RN 3) http://www.geocities.com/SiliconValley/Heights/7423 ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• 16. Credits ======= See the "Credits" file. ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• StrongBS ••••••• ••••••••• Hope you find StrongBS useful ••••••••• © Mohsen Alshayef email: mohsen@qatar.net.qa 28th June 1997