=================================================================================================
                            Scratch! for x86 Version 1.5 Build 270702
                         Created by L_O_J a proud member of Auraflow Team
                                  Developed and Compiled in QB4.5
=================================================================================================

Document Info :
-------------------
Author   : Achmad Aulia Noorhakim a.k.a L_O_J
Dated    : 27-7-2002
Version  : 1.0
Apply to : Scratch Version 1.5+

Author Info :
-------------------
Name     : Achmad Aulia Noorhakim
Degree   : None for now (maybe 3 years from now :)
E-mail   : L_O_J@Telkom.net
Address  : Jl.Duta Graha X No.51 Blok E7, Duta Harapan, Bekasi, Indonesia
Age      : 19

Software Info :
-------------------
Name     : Scratch!
Purpose  : To translate x86 (8086+) Assembly instruction to fully running BASIC source code
Version  : 1.5 Build 260702
Status   : Beta Test  (soon will be stable) [90%]
Developer: Achmad Aulia N  a.k.a L_O_J  (Auraflow Team)


Table Of Contents :
--------------------
[a] Disclaimer
[b] Introduction
[c] Feature List
 | +-> c.1 Label support
 | +-> c.2 Direct Variable passing
 +-+-> c.3 Dec and Hex Notation
   +-> c.4 Handles 8086 to Pentium Pro ASM Instructions
   +-> c.5 Wrap some of the detail work for you
   +-> c.6 Create output : formatted .BAS file or Hex file

[d] Details to know
[e] Scratch! Directives
[f] Q & A List
[g] Credits

=================================================================================================
[a] Disclaimer
-------------------
I do not responsible for any damage or injury that this software causes to you or your computer
hardware. I distributed this software as a freeware and open source. You may not edited this file
and the source code and then distributing it by your name (this is Evil Rip off).You may edited 
or change (improve) the source code and then recompiled it, if you want to distribute it you also
may add your name in the Author Info List but you must not deleted the previous author name and 
you also can use your own version name.


[b] Introduction
-------------------
In the mid July 2002 I have no work to do so I open up my computer and start looking for some 
thing to do :).Then I start to open the old QB:tm Webzine which contain Peter Holmberg ASM 
tutorial. I think "Hey this a good chance to learn ASM" ,so I did and the effect is amazing, ASM 
is not so hard after all. After a whole week studying Peter's tutorial and some other nice 
tutorial on SAM'S started to code one, but I have no assembler and based on Peter's tutorial I 
can use DOS DEBUG.EXE that come with DOS and Win9.x so I try a few code and it was amazingly fun.
Despite all the fun, I realize that using plain DEBUG is a pain. So I created this software as 
translator to make easier to translate ASM code to BASIC source code more easier and fun. The use
of DEBUG is actually to create sets of Machine code from ASM source code. Now what Scratch! do is 
to translate that Machine Code set to BASIC source code that you can use without assembling that 
ASM code first. So if you don't have an Assembler and want to use Asm in your BASIC then Scratch!
is for you. Happy Coding :)


[c] Feature List
-------------------
c.1 Label support :
    Normally DEBUG does not support the use of Label instead it uses offset of the code. But with
    Scratch you can specify a Label and then call it using either Jump or Loop instruction. Here
    is some Example in using Label.
    
    Example :
        Mov cx, 1000                ; Set counter to 1000
        Start_Of_Loop:              ; Specify a Label
        Loop Start_Of_Loop          ; Loop 1000 times
    
    Label Info :
    1. Maximum label that can be handled is 256 labels
    2. Label can be any size
    3. Label is not case sensitive (mean "LABEL" = "label" = "LaBeL")
    4. You must not use ES,DS,SS,CS as a label name (this is to maintain compability to Standard        DEBUG Segment Overiding method).
    5. Scratch support is for Short and Long Jump (although the Long one is not tested yet)

c.2 Direct Variable Passing :
    In DEBUG you cannot pass Variable from BASIC by it's name instead you must specify a stack
    address where that Variable is saved.In Scratch you can do that, you can pass Variable from
    BASIC by it's name.
    
    Example :
        BASIC SUB Asm (Var1%,Var2%,Var3%)
        
        Mov ax, [bp+04]       ---> In DEBUG
        Mov ax, Var3%         ---> In Scratch!

    Variable passing info :
    1. You can pass Max. 100 variable
    2. Your variable will always be translated to [BP+??]
    3. If you want to pass the value of the variable then turn the .BYVAL directive ON
    4. If you want to pass the offset of the variable then .BYVAL is OFF
    5. If .BYVAL OFF and you want to get the value than use :

        Mov bx, VarName%
        Mov ax/cx/dx, [bx]    ;---> you can't use bx in here

    6. You can only pass integer variable (string and other are not supported)
    
c.3 Dec[imal] and Hex[adecimal] notation :
    In DEBUG you can use Hex number only, but you can use Decimal and Hexadecimal number in it
    Decimal number is noted by "b"/"B" in the end of the number -> 1000d is 1000 decimal
    Hexa number is noted by "h"/"H" in the end of the number -> 140h is 140 in Hex = 320 in Dec

    Example :
        
        Mov ax, 140h       ---> ax = 140 in Hex = 320 in Decimal
        Mov ax, 140d       ---> ax = 140 in Decimal

    Notation Info :
    1. if a numeric value don't have notation than it is considered as Hex.

c.4 Handles 8086 to Pentium Pro ASM Intruction :
    DOS DEBUG can only handle 8086/8088 ASM instruction.In Scratch! you can use 8086 - Pentium
    Pro ASM Instruction, this can be happen because the use of Debug.com (a DEBUG replacer by        Paul Vojta).Debug.com enabled Scratch! to access/use 8086+ instruction.

    Example :
        you can use 32 bit Register such as EAX,EBX,etc

    Instruction info :
    1. Debug.com does not support MMX instruction therefore Scratch! Doesn't either.

c.5 Wrap some of the detail work for you :
    In order to incorporate ASM code to you BASIC you must push some value and then pop and calc
    ulate the returned byte.Scratch! Do this for you so you don't have to bother write again.

    Example :
    
    ;DEBUG Style...
    Push bp
    Mov bp,sp
    Mov ax,1
    Int 33
    Pop bp
    Retf (NumOfVar * 2) in Hex

    ;Scratch! Style...
    ;no need for push and mov, Scratch! added it for you
    Mov ax,1
    Int 33
    End                ;Tell Scratch! to add pop bp and retf and calculate the bytes

    Wrapper info :
    1. If you dont specify "End" then Scratch! will automaticly add POP BP|RETF in the end of ur
       Code.So if you have this form of code :

       Part1
       Jump to Part2
       Jump to Part3
       End here         ;---> use "End" Here
       Part2
       Part3
       ; If you don't use "End" it will end here :p

c.6 Create output formated .BAS file or Hex file :
    Scratch! final result is a .BAS file that is already formated for easy reading and easy to
    edited manualy. Also Scratch can produce a Hex file ,Hex file is a series of opcode put in
    one file.You can do this through Scratch Directive ".OUTHEX ON".

    .BAS Info :
    1. The BAS file consist of 2 Subs (Init (), and Subs created by the .OUTSUB Directive)
    2. To use it Call Init first (Always!) and then the other Sub.


[d] Detail to Know :
---------------------
1. Segment Overiding, for this you can use Seg:Off form ,like MOV ES:[DI],Value
2. Scratch! produce 2 debug output file for the whole process and then checks those 2 files for
   errors that may occured and you will be noticed by Scratch! if there is any.Please keep in
   mind that Scratch only trap error that is generated by DEBUG so logic error is not trapable.
   if you want to understand more about the error you can recompile the source to leave the debug
   output file undeleted and then you can check on them your self.
3. It is very highly recomended that you run Scratch! in Real DOS mode (not Win DOS Box!),because
   it may cause a lost character in big program (small program does not likely to be effected).
4. You can use Scratch! in 2 ways :
   
   Scratch Filename$  ---> including path if needed like "Example\808\cls.808".
   Scratch <enter>    ---> this bring up the input window.
   Scratch /?         ---> this print the infos.

[e] Scratch! Directives :
--------------------------
Scratch! have it own directives.The purpose of this directives is to make the output creation is 
easier ,because you don't have to specify the output configuration from serial of Input or a long
parameters anymore.All directive (except .DIM/.CHECK/.DEFINT) must be specified !.
    
    Directives :
    .OUTPUT Filename$
        - Filename$ is the output filename$ (usually .BAS)

    .OUTSUB SubName$
        - SubName$ is the name of the Sub/Function that call the Assembly routine

    .OUTSTR CodeStr$
        - CodeStr$ is the String Variable that stored the Asm Machine Code datas.

    .DEFINT ..-..
        - Specify the range of integer Variable.

    .BYVAL ON|OFF
        - Specify wether BYVAL Keywords is used or not.

    .DIM ...%,...%,...%
        - Specify Variable that will passed from BASIC to the ASM routine
          note : 1 ".DIM" can contain only 3 Variable, but you can have more than 1 ".DIM"
          Example :

          .DIM V1%,V2%,V3%
          .DIM V4%,V5%,V6%
          ;Will result = SubName$ (V1%,V2%,V3%,V4%,V5%,V6%)

    .CHECK Processor Type
        - Specify error detection for specific type of processor.for example :
          
          SHR AX, 8        ;----> if you do .CHECK 8088 then this will cause error "[need 186]"
                           ;      but if you do .CHECK 186/286/386/+++ then this will not
                           ;      cause an error
          
          Processor Type is :
          1. 8088 or 8086   5. 486
          2. 186            6. Pentium Class
          3. 286            7. Pentium pro
          4. 386
          :: if you don't insert this then the default value is 386.

    .OUTHEX ON|OFF
        - Specify the output format (BASIC Source code or Opcode hex)

[f] Q & A List :
-------------------
Q   = Why the build version is so loooong ?
A   = The Build version is in a date form like 170702 mean 17 July 2002

Q   = Where can I get Update, News about Scratch! ?
A   = Well i often hangin around in QB45 forum (www.QB45.com/forum) or you can go to Auraflow Web       Site and post a message there or you can just e-mail me for update (if there is one).I also       will post the file (newer or older) in the Auraflow web site or QB45.com.

Q   = Are you planning an IDE for Scratch! ?
A   = Yup and it is almost finished :)

Q   = Why the name is Scratch! ?
A   = ...hmmm... Well i just think it is a cool name :)


[g] Credits :
-------------------
1. Peter Holmberg (EC and EC++) for his tutorial and Absolute Assembly (which is not work for me)
2. Rick Elbers for his tutorial too
3. Mark Kim also for his tutorial
4. Jonathan Leger QBASM (inspired me a Lot)
5. William Yu for ABC Packet
6. QB:tm ppl if you guys still exist
7. Paul Vojta (vojta@math.berkeley.edu)
8. RelSoft (Eric Lope) for testing.

