@DATABASE "sss v1.0 Documentation" ******************************************************************************* @NODE MAIN "sss v1.0 doc (26.10.1998)" @PREV MAIN @NEXT MAIN @{b}sss v1.0 (26.10.1998)@{ub} © 1998 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 1st 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 @{"defs.i" link defs.i/MAIN} @{"standard asm source" link sources} @{"main.esa" link main.esa/MAIN} @{"ESA source code" link sources} @{"misc.ei" link misc.ei/MAIN} @{"ESA include file" link sources} @{"opt.ei" link opt.ei/MAIN} @{"ESA include file" link sources} @{"split.ei" link split.ei/MAIN} @{"ESA include file" link sources} @{"data.i" link data.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 a 020+ CPU. It should work also on KS1.3, but I can give no guarantee. @{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 (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 long 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 indicating their 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}) @ENDNODE ******************************************************************************* @NODE sources "About the ESA sources" @PREV sources @NEXT sources @{b}@{u}Preliminary Info @{ub}@{uu} @{b}*********************************************************************** *@{ub}If you have already had a look at the sources and you never heard of @{b}* *@{ub}ESA before, you're now surely wondering what language they're written@{b}* *@{ub}in. The shortest answer I can give to you is: it's a mix of 68k asm @{b}* *@{ub}and higher level constructions. If you're interested and want to know@{b}* *@{ub}more, I advice to download "ESA.lha" from dev/asm on Aminet (the ar- @{b}* *@{ub}chive is really short). @{b}* ***********************************************************************@{ub} @{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} or in this sec- tion. @{b}@{u}Compiling and Assembling @{ub}@{uu} They are fully commented (even if not in the best way possible, I have to admit) and need no other external include file to be compiled and assembled. You can do this in two ways: - calling ESA to compile the file @{"main.esa" link 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. @{b}@{u}Function/Procedures Header Description @{ub}@{uu} Each subroutine has an header of the kind: ******************************************************************************* * RoutineName v a.c.r ******************************************************************************* * INFO ... * SYNOPSIS ... * ... * IN ... * OUT ... * MODIFIES ... * REQUIRES ... * 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 - "SYNOPSIS" 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 - "MODIFIES" lists all the variables/locations which are modified in- side the routine and are not restored on exit - "REQUIRES" here are listed all the variables,definitions, etc. needed by the routine to be compiled or work correctly - "NOTE" additional info regarding important aspects of the routine Any of these fields can be omitted. @{b}@{u}Final Note @{ub}@{uu} This sources are meant to be good examples, so no particular optimiza- tion has been done. Moreover, I'm not much used to ESA yet, so they probably are not "the best" examples possible. @ENDNODE ******************************************************************************* @NODE History "History" @PREV History @NEXT Author @{b}@{u}History @{ub}@{uu} @{b}v1.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 I can also be reached by snail mail at the following addresses: (during "normal" periods) Simone Bevilacqua P.za Garibaldi 9 56100 Pisa (PI) ITALY (during uni vacation periods - "safer" 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 Amiga coders still around. Mega greetings to my family and all my friends!!! (the next time I'd like to scribble here something like: "WOOOOOOOOOOOoooooooooOOOOOOOOOOOOW!FINALLYMYPATIENCEHASBEENREWARDED!!! THANXALOTAMIGAINC./INT.FORHAVINGGIVENTHEWORLDANEWBEAUTYANDAHOPETOSAVEIT FROMTHOSEDIRTYM$OFT/INTEL'SHANDS!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!" Now I wonder: will that moment ever come before 2177a.d.?!? PLEASE, MAKE IT SO, MAKE IT SOON!!!) @ENDNODE