



                         BSBASIC v1.0  DOCUMENTATION
                              by BlackLight 2001




WHAT IS BSBASIC?


It's a simple BASIC compiler, designed especially for diskette-bootsectors.
This way, you can write your own funny bootsector, which will be executed
when you leave the disk in your computer when you start it up.


HOW TO USE IT?

If you know the BASIC programming-language, this is easy for you. Write a
BASIC program with a standard DOS text-editor, and type the following DOS
command:

   BSBASIC yourfile A:

Then the program will be compiled into the bootsector of the disk which is
in drive A:.


PARAMETERS

Of course, BSBASIC.EXE has more command-line parameters:

    BSBASIC inputfile[.BSB] [x:] [/F] [/I] [/B]

inputfile    Name of the BASIC program. If no extension is given, .BSB will
             be assumed.
x:           The diskdrive to write to: this can only be A: or B:
/F           Also compile to a .BIN-file with the same name as the inputfile.
/I           Use DOS incompatibility mode. This gives you the complete 510
             available bytes, but will make your disk unreadable for MS-DOS.
/B           Backup original bootsector to file BACKUP.BIN before writing the
             new compiled bootsector.

To backup a bootsector without compiling anything:

    BSBASIC a: /B                or:
    BSBASIC b: /B

You can use the /R parameter to restore the BACKUP.BIN file to disk:

    BSBASIC a: /R                or:
    BSBASIC b: /R


BASIC-LANGUAGE DETAILS

Of course, you cannot use all BASIC language elements and statements. This is
because a bootsector can contain a maximum of 512 bytes, of which 2 bytes are
used to indicate that it is bootable. This leaves you with 510 bytes, if there
wasn't such a thing as Micro$oft. They thought it would be nice to require
another 62 bytes to store some disk-info (use the /I parameter to overwrite
these 62 bytes, if you don't use the diskette to store files on).

So because of the size, the following things are left out:
  - Variables
  - Comments (not yet...)
  - IF/THEN/ELSE, FOR/NEXT, DO/LOOP etc.
uhm... let's just tell what you CAN use.... ;)
  - PRINT ["text"[;]]         for example: PRINT "Hello world!"
                                       or: PRINT
                                       or: PRINT "Press any key...";
  - CLS
  - Label:
  - GOTO label                for example: Hang:
                                           GOTO Hang
  - GOSUB label
  - RETURN                    for example: GOSUB DoIt
                                           ....
                                           DoIt:
                                           RETURN
(Read the QBASIC manual for more info on these statements)

also some MicroBASIC statements:
  - INKEY
  - IFKEY "?" label
(Read the MicroBASIC manual for more info on these statements)

so far the standard BASIC statements. I added some statements especially for
bootsectors:
  - RETRY         -> Retry computer-startup. If the disk is still in the
                     diskdrive, this will restart the bootsector. Otherwise
                     it will start the C:-bootsector (just like the standard
                     DOS bootsector does when you 'press a key')
  - REBOOT        -> Reboot the computer. Same as pressing Ctrl+Alt+Del.


EXAMPLES

I included two example bootsector-programs so you can learn how BsBASIC works.
They are named EXAMPLE.BSB and FAKEDOS.BSB. Compile them like this:

       BSBASIC example A:
  or:  BSBASIC fakedos A:

You can view/edit them with any standard DOS text-editor.


THE RUNBIN.EXE PROGRAM

RunBin.Exe can load and execute a bootsector, without writing it to a diskette
and rebooting first.
This program is still in experimental phase (beta), so I cannot guarantee that
it works perfectly.
Don't run it under Windows, because it's possible that it overwrites some
essential memory contents!

BsBASIC-compiled bootsectors are unlikely to cause any problems, but Micro-
soft's bootsectors will *always* lock-up your computer, requiring a cold-
reboot.

Syntax:   RUNBIN filename.bin

It first checks if the bootsectorfile is executable. Then, it will search
for the BsBASIC's REBOOT and RETRY instructions, and replace them with an
exit-call. Then it starts the 'BIOS emulator', which looks like a real BIOS
(BIOS=Basic Input/Output System, which loads the bootsector when you startup
a computer).

WARNING: If your bootsector appeared to be executed correctly, and RUNBIN
         ends with a normal exit-message, you cannot be 100% sure that the
         computer will function correctly. Some parts of the memory could
         have been overwritten, which can cause problems with other programs.
         Please e-mail me if you have more info on this issue.


CREDITS

BsBASIC and RUNBIN were both written and compiled using PowerBASIC 3.2.
BsBASIC is based on the MicroBASIC Compiler (also written by me).
System-opcodes were acquired using MS-DOS Debug.exe.

Copyright (C) 1995-2001 BlackLight. All rights reserved. You are free to
copy this program, as long as all files are included and unmodified.
You can download new versions from: www.blacklight.wxs.org

Compiled bootsectors do not contain copyrighted elements, you can freely
modify and distribute them in any way you like.
