@DATABASE "sss 1.4 documentation (rev. 20021011.0)" ******************************************************************************* @NODE MAIN "sss 1.4 documentation" @PREV MAIN @NEXT MAIN @{b}sss 1.4@{ub} © 1999 Simone Bevilacqua @{" DISCLAIMER & Distribution " link DISC_&_dist} some legal stuff @{" Requirements & Installation " link req_&_inst} what you need to get it working @{" Introduction " link intro} why it exists and what it's for... @{" Usage " link usage} how to use it @{" About the ESA sources " link sources} notes on the source code @{" History " link History} what has happened till now @{" Author " link Author} some notes about me... @{" Greetz & Thanx " link Greetz} ciao! @ENDNODE ******************************************************************************* @NODE DISC_&_dist "DISCLAIMER and Distribution" @PREV DISC_&_dist @NEXT req_&_inst @{b}@{u}DISCLAIMER @{ub}@{uu} @{b}********************************************************************** * THIS PROGRAM IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND * * EITHER EXPRESSED OR IMPLIED. * * @{"I" Link Author} ACCEPT NO RESPONSABILITY OR LIABILITY FOR ANY DAMAGE OR PROBLEM * * DERIVING FROM THE USE OF THIS PROGRAM: USE AT YOUR OWN RISK!!! * **********************************************************************@{ub} @{b}@{u}Distribution @{ub}@{uu} This program is FREEWARE, therefore IT CANNOT BE SOLD FOR PROFIT. So, only the distribution charges (i.e.: disk, postage, handling, etc.) can be applied. No fee is required from @{"me" link Author}, but donations of any kind (something like the first original tankobon of "Dr. Slump & Arale chan" would be just a dream... ;) will be gladly accepted. If distributed on a coverdisk, please send a copy of the mag!!! ALL the following files *MUST* be included in the same package (regard- less of the form it comes in): sss/ (progdir) sss executable sss.guide this documentation @{"do" link do/MAIN} script for quick compiling cod/ (sources dir) @{"defs.i" link cod/defs.i/MAIN} @{"standard asm source" link sources} @{"main.esa" link cod/main.esa/MAIN} @{"ESA source code" link sources} @{"misc.ei" link cod/misc.ei/MAIN} @{"ESA include file" link sources} @{"opts.ei" link cod/opts.ei/MAIN} @{"ESA include file" link sources} @{"splt.ei" link cod/splt.ei/MAIN} @{"ESA include file" link sources} @{"dat.i" link cod/dat.i/MAIN} @{"standard asm source" link sources} You can freely modify the program for your personal use, but before spreading a modified version, please contact me. @ENDNODE ******************************************************************************* @NODE req_&_inst "Requirements & Installation" @PREV DISC_&_dist @NEXT req_&_inst @{b}@{u}Requirements @{ub}@{uu} sss requires an Amiga with 020+ CPU and KS 2.04. @{b}@{u}Installation @{ub}@{uu} It doesn't need to be installed, just put it anywhere on your HD (preferably on your commands path). @ENDNODE ******************************************************************************* @NODE intro "Introduction" @PREV intro @NEXT usage @{b}@{u}Introduction @{ub}@{uu} This prog has been born mainly because @{"ESA" link ESAinfo} (Extended Syntax Assembly - you can find it in "dev/asm" on Aminet) lacked of a good, full working example: that's why you find also the @{"source code" link sources} in this archive. A secondary reason is that I needed a simple file splitter and I could not bother finding the right one among the incredible amount available on Aminet. A third reason is that I wanted to replace (on Aminet) an old program of mine which - I fear - could fail to work well (I coded it when I was getting started with asm and patched it later, but...). OK, the preamble's over, and from the 2nd point you should have guessed what sss is: a simple file splitter. Being simple doesn't mean it is not smart, though... sss, in fact, will try to allocate a buffer as big as the chunk size to reduce the accesses to disk; should it fail, it will try to allocate the largest available contiguous block of memory. The output files produced will have a numerical extension in ascending order. Only the needed number of digits will be used: for instance, if there are only 9 chunks, the extension will be exactly 1 char long. If, instead, 9 < chunks < 100, then a 2 digits extension will be used. 3 for chunks > 99, 4 for chunks > 999 and so on... Oh... not much more to say, why don't have a look at the @{"usage" link usage}? @ENDNODE ******************************************************************************* @NODE usage "Usage" @PREV intro @NEXT usage @{b}@{u}Usage @{ub}@{uu} @{b}SYNTAX@{ub} sss [@{b}-q@{ub}] @{b}InputFile ChunkSize@{ub} [@{b}OutBase@{ub}] @{b}ARGS@{ub} @{b}-q@{ub} = quiet mode: don't print any message @{b}InputFile@{ub} = name of the file to split @{b}ChunkSize@{ub} = size in bytes of each chunk (0 < ChunkSize < $7fffffff = 2,147,483,647) @{b}OutBase@{ub} = output files will be called @{b}OutBase@{ub}.x (000 <= x <= 99,999; by default @{b}OutBase@{ub} = @{b}InputFile@{ub}) @{b}NOTE@{ub} execution can be stopped by pressing @{b}CTRL-C@{ub} anytime @ENDNODE ******************************************************************************* @NODE sources "About the ESA sources" @PREV sources @NEXT sources @{b}@{u}About the ESA sources @{ub}@{uu} In the archive there are all he source files of sss (no other external include file needed). Those sources are meant to be a concrete example of @{"ESA" link ESAinfo} programming, so, to foster readability, no particular optimization has been done. Moreover, I'm not much used to ESA yet, so they probably are not "the best" examples possible. @{" About ESA " link ESAinfo} some preliminary info @{" Tabulation " link tab} sources layout @{" Compiling & Assembling " link CompAsm} DIY @{" Function/Procedures Header Description " link FPheader} about comments @ENDNODE @NODE ESAinfo "About ESA" @{b}@{u}About ESA @{ub}@{uu} If you have already had a look at the sources and you never heard of ESA before, you're now surely wondering what language they're written in. Well, the "language" is ESA itself and the shortest information a- bout it I can give to you is: it's a mix of 68k asm and higher level constructions. If you're interested and want to know more, I advice to download the archive "ESA.lha" from dev/asm on Aminet (the archive is really short). @ENDNODE @NODE tab "Tabulation" @{b}@{u}Tabulation @{ub}@{uu} All the sources have been written using this tabulation: @{b}Label instruction operands comment T T T T@{ub} That's why they look jerky on the window of the amigaguide viewer you are currently using, if you click on the gadgets @{"here" link DISC_&_dist 31}. @ENDNODE @NODE CompAsm "Compiling & Assembling" @{b}@{u}Compiling & Assembling @{ub}@{uu} The sources are fully commented (even if not in the best way possible, I must admit) and need no other external include file to be compiled and assembled. You can do it in two ways (you must have @{"ESA" link ESAinfo}): - calling @{"ESA" link ESAinfo} to compile the file @{"main.esa" link cod/main.esa/MAIN} and then assembling the output asm source with your fave assembler - using the script "@{"do" link do/MAIN}" (please note that you could have to change so- me of the variables therein) The final source code is assembled correctly by PhxAss, maybe you could have to do minor changes to fit your assembler. @ENDNODE @NODE FPHeader "Function/Procedures Header Description" @{b}@{u}Function/Procedures Header Description @{ub}@{uu} Each subroutine has an header of the kind: ******************************************************************************* * RoutineName v a.c.r ******************************************************************************* * INFO ... * SYN ... * ... * IN ... * OUT ... * MOD ... * REQ ... * WARN ... * NOTE ... ******************************************************************************* - "RoutineName" indicates the name of the procedure/function - "v a.c.r" indicates the version according to this versioning system: a=algorithm version (this changes when an algorithm replaces the previous, structurally different, one) c=compatibility (this increases when the modifications made to the source force changes also to the sources which call the func/proc; in practice when the proc/func can't be used [safely] in the same way/place as before the changes) r=revision (increased when bugfixes, optimizations, or any other operation which doesn't affect compatibi- lity or doesn't represent a major change in the algorithm structure are made) - "INFO" gives a brief description of what the routine does - "SYN" shows how to make the call. For example: OutValue = RoutineName[arg0,arg1] d0 a0 d1 Means that "RoutineName" is a function which requires two parameters ("arg0" and "arg1") as input and returns a value, indicated as "Out- Value" in d0 - "IN" is a list of the input arguments, describing their meaning and the expected/allowed values - "OUT" gives a description of the value returned by a function - "MOD" lists all the variables/locations which are modified inside the routine and are not restored on exit - "REQ" here are listed all the variables,definitions, etc. needed by the routine to be compiled or work correctly - "WARN" informs you about some particularly critical aspects of the routine - "NOTE" additional info regarding important aspects of the routine Any of these fields can be omitted. @ENDNODE ******************************************************************************* @NODE History "History" @PREV History @NEXT Author @{b}@{u}History @{ub}@{uu} @{b}1.4 (20.5.2002)@{ub} - bug fix: didn't handle filenames enclosed in quotes correctly - few style changes in the code (no effect on functionality) - few changes in the guide This update is mainly due to the fact that I wanted to remove an old and buggy version @{b}1.3 (19.5.2002)@{ub} - few style changes in the code (no effect on functionality) - few changes in the guide @{b}1.2 (13.10.1999)@{ub} - Now simply requires KS 2.04... just nothing else! @{b}1.1 (20.11.1998)@{ub} - CTRL-C detection added - command line handling changed - KS version check - cleanup call moved in the right place - this .guide updated @{b}1.0 (26.10.1998)@{ub} First public release @ENDNODE ******************************************************************************* @NODE Author "Hi there!" @PREV History @NEXT Greetz @{b}@{u}Hi there! @{ub}@{uu} If you have any problems or want to know more about ESA write to: - bevilacq@cli.di.unipi.it - saimobvq@interfree.it I can also be reached by snail mail at the following address: Simone Bevilacqua Via A.Volta 6 86010 Ferrazzano (CB) ITALY @ENDNODE ******************************************************************************* @NODE Greetz "Greetz and Thanx" @PREV Author @NEXT Greetz @{b}@{u}Greetz and Thanx @{ub}@{uu} Thanks to all the true Amigans still around!!! Mega greetings to my family and all my friends!!! (couldn't be simpler...) @ENDNODE