






               BLACKLIGHT MICROBASIC COMPILER  DOCUMENTATION

                                  VERSION 3.20

           Copyright (C) 1995-2001 BlackLight. All rights reserved.

                        For support and updates, visit:
                             www.blacklight.wxs.org








00contentspage01


  chapter                                                              page
  00contents01
  01featureoverview02
  02compilerusage03
  03differencesbetweencomandexefiles04
  04mbffiles04
  05mbxfiles05
  06microbasicstatements06
  06.01microbasicstatements:BEEP06
  06.02microbasicstatements:CHAR07
  06.03microbasicstatements:CLSand CLRSCR07
  06.04microbasicstatements:COLORandANSICOLOR07
  06.05microbasicstatements:CURSOR08
  06.06microbasicstatements:ENDandEXIT08
  06.07microbasicstatements:FLUSHBUFFER08
  06.08microbasicstatements:GOSUB09
  06.09microbasicstatements:GOTO09
  06.10microbasicstatements:IFANSI09
  06.11microbasicstatements:IFKEY10
  06.12microbasicstatements:INKEY10
  06.13microbasicstatements:LOCATE10
  06.14microbasicstatements:PRINTandOUTPUT11
  06.15microbasicstatements:PRINTSCREEN11
  06.16microbasicstatements:RETURN11
  06.17microbasicstatements:SLEEPandDELAY12
  06.18microbasicstatements:VIDEORESET12
  06.19microbasicstatements:LabelName:12
  06.20microbasicstatements:'Comments/REM13
  06.21microbasicstatements:MBX_calls13
  06.22microbasicstatements:$METACOMMANDS14
  07colors14
  08compression15
  09what'snew?16
  10contacttheauthor18
  11requests18
  12relatedproducts19
  13copyright19





01featureoverviewpage02


  This simple BASIC compiler for MS-DOS computers allows you to create full
  standalone executable COM- or EXE-files. Other than with most BASIC com-
  pilers, the MicroBASIC compiler creates REAL system code, not a RunTime
  module with P-code. Therefore, executables created with MicroBASIC are
  always smaller and faster than other executables. In most cases, they are
  even smaller than the original source-code! If you use this compiler, most
  people will think that you wrote your programs using assembly language,
  because your executables will just be a few bytes large.

  The MicroBASIC language looks much like BASIC, although MicroBASIC is less
  complicated than normal BASIC. Some functions are left away, and others are
  added.

  If the standard MicroBASIC statements do not meet your requirements, you
  also have the ability to use MBX-files: MicroBASIC Extensions. They contain
  systemcode to enhance the functionality of your programs. You can create
  your own MBX-files with this compiler, or with the MBX-Editor.

  MicroBASIC Compiler features:

   The compiler can use conventional, EMS or XMS memory when compiling a
    program. By default, it automatically chooses EMS or XMS, according to
    their free size. Use the /Mx parameter to force the compiler to use
    another type of memory.

   It generates pure system code, according to the tiny model, which limits
    your programs to a maximum size of 64kb: code+data reside in the same
    segment. Due to MicroBASIC's limitations, no stack is neccesary.

   Minimum system requirements for compiled programs are: a 8086 processor
    and MS-DOS 2.0. This way you can be sure your programs run on virtually
    *any* personal computer.




02compilerusagepage03


  The compiler is completely operated from the command line. Usage is very
  simple, just enter the following command:

               MBC yourprog

  where yourprog is the MBF-file to be compiled. The extension .MBF is
  implied by default, if no MBF-file is found, the compiler first looks for
  a BAS-file before giving an error message. So if you have a file named
  YOURPROG.MBF in the current directory, it will be compiled to YOURPROG.COM.

  The compiled program will be placed in the current directory, with the same
  name as the source-code file, but with another extension. The extension is
  automatically chosen: COM, EXE or MBX. If you did not specify an output
  filetype on the commandline using the /Cx parameter, the compiler looks in
  the sourcecode for a $COMPILE statement. If none was found, COM is used.

  If you want to create an EXE file, use the /CE parameter:

               MBC yourprog /CE

  Other command-line options are:                                 *=default
   /CC     *compile to .COMCreates a .COM executable file.
   /CE      compile to .EXECreates an .EXE executable file.
   /CM      compile to .MBXCreates a .MBX MicroBASIC Extension.
   /V       verbose modeShows extra information while compiling.
   /NH      no MB headerLeaves out the MicroBASIC header.
   /E       encrypt executableProtects your COM/EXE with encryption.




03differencesbetweencomandexefilespage04


  The COM-file format (also called binary format) is older than the EXE-file
  format. EXE-files can consist of multiple segments, which allows programs
  to be bigger than 64k.

  However, this compiler can only generate programs smaller than 64k, so it
  cannot use the extended functionality of the EXE-format.

  So, the only difference between COM and EXE files made with the MicroBASIC
  compiler is the filesize: EXE-files require a header, which, in this case,
  is 32 bytes.




04mbffilespage04


  MicroBASIC Files are just plain ASCII text-files, which you can write with
  the MS-DOS Editor, or another ASCII text-editor. The most important of the
  MBF-files is that they contain MicroBASIC-commands. These commands look
  like normal BASIC, but they are easier to learn, because there are just a
  few of them. Variables can't be used. In the next version I'll introduce
  variables!

  Because MicroBASIC is so plain, the created COM- or EXE-files are very
  compact. This is comfortable when you want just a little COM- or EXE-file
  with for example usage instuctions.






05mbxfilespage05


  MBX-files are 'MicroBASIC Extensions'. Using these 'extensions', you can
  add your own functions to your programs.
  Many MBX-files are included in the MicroBASIC package. Read MBX_REF.TXT
  for detailed descriptions of these files.

  It's also possible to create your own extensions. There are three ways,
  from easy to difficult:

  BEGINNER: Just write a MBF-program and compile it with the MicroBASIC
            compiler, using the /CM option.

  INTERMEDIATE: If you know a little 8086-assembly language, you can use the
                MBX Editor, which is also included in the MicroBASIC package.

  PROFESSIONAL: Read MBXTECH.TXT to learn the MBX fileformat and use your
                Hex Editor to create the MBX-file.

  The best way (easy, yet productive) is the MBX Editor. It allows you to
  graphically edit the contents of an MBX-file. It has a built-in assembler
  and disassembler.

  You can also download MBX-files from the BlackLight website at:
  http://blacklight.wxs.org
  Or upload your own creations!




06microbasicstatementspage06


  The following commands are supported in MicroBASIC:

     1. BEEP                     11. IFKEY
     2. CHAR                     12. INKEY
     3. CLS / CLRSCR             13. LOCATE y, x
     4. COLOR / ANSICOLOR        14. PRINT / OUTPUT
     5. CURSOR                   15. PRINTSCREEN
     6. END / EXIT               16. RETURN
     7. FLUSHBUFFER              17. SLEEP / DELAY
     8. GOSUB                    18. VIDEORESET
     9. GOTO                     19. LabelName:
    10. IFANSI                   20. 'Comments/REM

  The compiler is extendable using MBX commands:
    21. MBX_???[???]

  There are also some 'meta'-commands, which don't change the way how the
  program runs, but how the COM- or EXE-file is written. These statements
  start with a dollar-sign.

    22. $INCLUDE filename
    23. $ENCRYPT
    24. $COMPILE EXE|COM|MBX
    25. $NOHEADER




06.01microbasicstatements:BEEPpage06


  Function: Play a short beep-tone through the PC-speaker.




06.02microbasicstatements:CHARpage07


  Function: Print one specific character to the screen (for example the
            dollar sign (ascii code 36), which cannot be used in PRINT).
  Syntax:   CHAR ascii
            ascii=The ascii-code of the character.
  Notes:    You can use hexadecimal numbers this way: Decimal    : 36
                                                      Hexadecimal: &h24
            So just place &h before the hexadecimal number.




06.03microbasicstatements:CLSandCLRSCRpage07


  Function: Clear the screen.
  Notes:    The difference between CLS and CLRSCR is that CLS can clear the
            screen into the selected color if you use the COLOR statement
            before the CLS statement. CLRSCR always makes the screen black.
            If you don't have any COLOR statements in your program, the
            compiler interprets CLS as CLRSCR (which takes less space).




06.04microbasicstatements:COLORandANSICOLORpage07


  Function: Change current text-color.
  Syntax:   COLOR fore,back                    ANSICOLOR fore,back
            fore=Foreground color (0-31).
            back=Background color (0-7).
  Notes:  - If the foreground color is 16 or higher, the characters will
            blink. Use BRIGHT.MBX and BLINK.MBX to change this.
          - The difference between COLOR and ANSICOLOR is that ANSICOLOR uses
            ANSI.SYS escape sequences to change the color. Before you use
            ANSICOLOR, you should use IFANSI to test if ANSI.SYS is loaded.
          - Both statements work in graphics mode too.




06.05microbasicstatements:CURSORpage08


  Function: Set the cursor-shape.
  Syntax:   CURSOR start,stop
            start=The top line of the cursor (0-15)
            stop =The bottom line of the cursor (0-15).
  Note:     If you specify a stop value higher than the start value, no
            cursor will be visible.




06.06microbasicstatements:ENDandEXITpage08


  Function: Quit the program and turn back to the operating system.
  Syntax:   END [exitcode]
            exitcode=Unrequired number to exit program with. For usage in
                     .BAT-files with IF ERRORLEVEL etc. See MS-DOS Helpfile.
  Example: See EXITCODE.MBF in the examples-directory for a demonstration.
  Note:    If you're writing an MBX-file, use EXIT instead of END. EXIT will
           return to the calling program.
  Syntax:  EXIT



06.07microbasicstatements:FLUSHBUFFERpage08


  Function: Flush the keyboard buffer, so no keys will remain in memory.
            This is useful for after a SLEEP command, so the user can press
            as many keys as he wants, but after the SLEEP command these keys
            are erased so there won't be done anything with them.




06.08microbasicstatements:GOSUBpage09


  Function: Jump to a specified label in the program.
  Syntax:   GOSUB LabelName
            LabelName=The name of the label to jump to, without semicolon.
  Note:     You can use RETURN with this. See RETURN.MBF for an example.




06.09microbasicstatements:GOTOpage09


  Function: This is almost the same command as GOSUB, except that RETURN
            cannot be used with it. Of course this saves memory, so if you
            don't need RETURN, it's better to use GOTO instead of GOSUB.
  Syntax:   GOTO LabelName
            LabelName=The name of the label to jump to, without semicolon.




06.10microbasicstatements:IFANSIpage09


  Function: Detect ANSI.SYS. Use it before printing ANSI-sequences to the
            screen, because otherway the user screen will become a mess.
  Syntax:   IFANSI LabelName
            LabelName=Name of the label to jump to when ANSI.SYS is detected.
  Example:  IFANSI Okay
            PRINT "No ANSI.SYS found!"
            END
            Okay:
            PRINT "ANSI.SYS detected!"




06.11microbasicstatements:IFKEYpage10


  Function: Jump to the specified label if the specified key was pressed.
  Syntax:   IFKEY Ascii Label
            Ascii=The ascii-code of the key.
            Label=The name of the label.
  Note:     - With the jump, RETURN cannot be used.
            - Only use after an INKEY statement. Otherwise, IFKEY can give
              unexpected jumps.
            - You can also specify the ascii code with a character, for
              example: IFKEY 65 Label is the same as IFKEY "A" Label




06.12microbasicstatements:INKEYpage10


  Function: Wait for keypress and place ascii-code of the pressed key in the
            memory for IFKEY.
  Note:     Don't put too many statements between INKEY and IFKEY, because
            they could erase the key from the memory.




06.13microbasicstatements:LOCATEpage10


  Function: Place the cursor at a given row and column.
  Syntax:   LOCATE y, x
            y=Row to place the cursor on (1-255 (depends on screenmode)).
            x=Column to place the cursor on (1-255).
  Note:     The number of rows on the screen depend on the screenmode. Make
            sure you know how many rows/columns the selected mode has. Use
            VIDEORESET to go into 25rows/80cols mode (see 06.18).




06.14microbasicstatements:PRINTandOUTPUTpage11


  Function: Place a text on the screen.
  Syntax:   PRINT ["Text"[;]]
            Text=The text to place on the screen.
            ;=If you specify this, the cursor will not jump to the next line.
  Example:  PRINT "Blabla...";
            PRINT "OK!"
  Output:   Blabla...OK!
  Note:   - Difference between PRINT and OUTPUT is that OUTPUT uses the DOS
            interrupts to write to the screen, and therefore, the output can
            be redirected. OUTPUT cannot print $-characters, and cannot show
            colors.
          - If you don't have any COLOR statements in your program, PRINT is
            interpreted by the compiler as OUTPUT.




06.15microbasicstatements:PRINTSCREENpage11


  Function: Send the computerscreen to your printer. Exactly the same as
            pressing PrtScrn on your keyboard.
  Note:     This will only work under Windows if your program is running in a
            FULLSCREEN dos-box (not in a window!)




06.16microbasicstatements:RETURNpage11


  Function: Turn back to the command after the GOSUB command.
  Note:     CAUTION! Only for use with GOSUB. If GOSUB was not used, the
            results are unpredictable!




06.17microbasicstatements:SLEEPandDELAYpage12


  Function: Wait a number of seconds.
  Syntax:   SLEEP [secs]   or   DELAY secs
            secs=Number of seconds to wait (0-3600). If no value is given,
                 the program waits for a keypress to continue. DELAY cannot
                 be used without a value.
  Notes:  - The difference between SLEEP and DELAY is that SLEEP can be
            interrupted by the user with a keypress. DELAY will wait for the
            given time, no matter if a key is pressed.
          - All keys which are pressed while waiting, are placed in the
            keyboard buffer, and are transported to your program at the
            following INKEY command. If you want to clear the keyboardbuffer,
            use the command FLUSHBUFFER. It's best to use it after every
            SLEEP/DELAY command.




06.18microbasicstatements:VIDEORESETpage12


  Function: Reset the display, clear all video-pages and place the cursor at
            the top left row and column.
  Note: This does the same as QBASIC's "SCREEN 0" function.




06.19microbasicstatements:LabelName:page12


  Function: Specify a label in your program.
  Note: You can jump to the label with: GOSUB, GOTO, IFKEY and other IF-
        statements.




06.20microbasicstatements:'Comments/REMpage13


  Function: Add comments to your programs.
  Examples: 'This is a comment
            REM This is a comment too
  Note: A commented line must begin with an apostrophe or with "REM ". These
        comments will not appear in compiled executables.
  Note: You can also use the comments after another command, for example:
            PRINT "Hello"   'this line prints Hello




06.21microbasicstatements:MBX_callspage13


  Function: This is a very special command. It calls a subroutine from a
            MBX-file (MicroBASIC Extension). The filename of that file
            (without the .MBX extension) comes on the question marks.
  Syntax without parameters: MBX_RESETMOU
  Syntax with 1 parameter  : MBX_NEWPRINT["Hello World"]
  Syntax with 1+ parameters: MBX_CPRINT[12 "Hello" 5]
  Note: The brackets will let the compiler know that the MBX-file uses para-
        meters. If no brackets are used, but the MBX-file requires them,
        the compiler will exit with an error-message.
  Note: If the MBX-file is not in the current directory, the compiler will
        look for it in the current directories MBX\ subdirectory, and in the
        PATH.
  Note: Have a look at the special chapter 5 about MicroBASIC Extensions.





06.22microbasicstatements:$METACOMMANDSpage14


  There are also some special commands which do not change the way the
  program runs, but they change the outputfile. You can place these commands
  anywhere in the source-file.

    $INCLUDE "filename" Insert another MBF file on this position and compile
                        it.
    $ENCRYPT            Will encrypt the output-file, to prevent it from
                        being viewed or edited by other people.
    $COMPILE ???        Defines the type of output-file (COM, EXE or MBX).
                        This command is only used if no output-type is
                        specified on the compiler's command-line.
    $NOHEADER           Doesn't write the 'Compiled with MicroBASIC' header
                        to the compiled file.

  These commands behave like the metacommands in PowerBASIC (not like meta-
  commands in QuickBASIC, because those require ' or REM before it).




07colorspage14


  The compiled ANSICOLOR-command is the same as a OUTPUT-command. The
  compiler converts the COLOR syntax to an ANSI escape-sequence, and compiles
  it like a OUTPUT-command. That's why you should place the IFANSI command in
  the beginning of the program to check for the installation of ANSI.SYS.

  TIP: If you want to use colors without the requirement for ANSI.SYS, use
       the COLOR statement, or have a look at the COLORS.MBF example, which
       uses a special MBX-file to display texts with a color-attribute.




08compressionpage15


  I'm sure it's possible to compress the created COM/EXE-files with a program
  like PKLITE, LZEXE, DIET, TINYPROG, WWPACK, aPACK, etc, but I couldn't test
  it yet. There's one simple reason for that: The files already were so
  small, that they couldn't be compressed any more (uncompression routine +
  compressedcode >= uncompressed code).

  With other programs like PKZIP, ARJ, RAR etc, the files can be compressed
  very good (ratio  50%), but this way they cannot start right-away.
  Maybe if you write larger programs, they can be compressed.

  The compiler itself uses also a sort of compression, and that is that it
  does not write the same text-string twice. For example this program:

  PRINT "Pietje": PRINT "Klaasje": PRINT "Pietje"

  Then the compiled program will only contain 'Pietje' once.
  It's also good to use large routines just once, for example SLEEP, uses 23
  bytes. That's very much compared with GOSUB and RETURN, which use together
  only 4 bytes. That's why you can make a subroutine yourself, and jump to it
  with GOSUB every time you need it. The same goes for MBX-calls. Have a look
  at the LARGE.MBF and SMALL.MBF examples.

  Note: If you use aPACK to compress MicroBASIC files, you have to take some
        precautions to prevent your program from crashing.
        For COM-programs, you should replace your END-statements with END 0
        statements. aPACK warns for ending with RET instructions, and END
        with an errorlevel doesn't use a RET instruction.
        For EXE-programs, you should use aPACK with the -m option, because
        MicroBASIC's EXE-files are actually COM-files with an EXE-header.
        These solutions should work fine. Let me know if they don't.

  You shouldn't use the $ENCRYPT statement or the /E parameter when you want
  to compress your program, because encrypted EXE's or COM's have an average
  compression ratio of 0%, so in most cases, packing your program will result
  in a bigger filesize...




09what'snew?page16


  v 3.20: PBC/BPC-look and feel ;). Creates MBX files (beta). New look for
          this documentation. Rewrote PRINT, COLOR and CLS (don't require
          ANSI.SYS anymore!), renamed the old versions to respectively
          OUTPUT, ANSICOLOR and CLRSCR. Another major bug fixed in SLEEP and
          added DELAY. Completely rewrote the encryption stuff. Optimized
          IFKEY and IFANSI. Searches the path for MBX file if not in curdir.
          Started with the MicroBASIC IDE (see EXTRA-dir for beta-version).
          Removed the compiler's PB-sourcecode from the package. If you want
          it, just send me an e-mail.
  v 3.00: Completely reviewed every line of sourcecode. Fixed many bugs,
          done great optimizations in every way. Major bugfix in SLEEP
          routine. Added $INCLUDE. Removed $NOCOMPRESSION. Also made a
          Windows helpfile.
  v 2.65: Great optimization in CLS routine (thanks to Jason Downey) which
          results in better reliability and smaller filesize (new routine
          is almost 3 times as small) because the new CLS uses 8 bytes.
          Also optimized the SLEEP routine 35->23 bytes. 12 bytes shorter.
          Some memory optimizations and now it can handle larger sources.
          Added percent-counting with Pass 1 and Pass 2. Header 12 bytes
          shorter.
  v 2.64: 2 new ID's in MBX. Some optimizations. Small parsing-bug fixed.
  v 2.63: /LOGFILE-parameter added. NOCOMPRESSION is now $NOCOMPRESSION
          like all other metacommands. $COMPILE EXE|COM added.
  v 2.62: SLEEP-command improved (also usable without parameter). /QUIET
          parameter added. Some small optimizations. Compiler now gives
          errorlevels at exit. Sourcecode translated to english. MBC.EXE
          contains own version number at offset 29.
  v 2.61:  Removed the internal compression, because it took a lot of me-
            mory, and almost did no compression. MBC.EXE is now about 8000
            bytes smaller and uses absolutely NO temporary files any more,
            and uses almost no memory any more.
           Now possible to place multiple commands on one line using the
            ":"-character between them (eg. CLS: PRINT "Hey").
           You can place comments on the same line as a command, eg:
            PRINT "Hey"   'this command prints Hey




09what'snew?(part2)page17


  v 2.60: Great optimization in EXE-writing routine (thanks to Jason
          Downey) which results in better speed and smaller MBC.EXE size.
          Compiler doesn't use so much memory any more.
  v 2.59: Bug fixed in compression method and optimized speed writing EXE's.
  v 2.58: Added MBX Label-function, useful for detection-routines etc.
  v 2.57: GOTO-bug fixed which was in the program since v2.55.
  v 2.56: Now added an encryption-method: ENCRYPT.
  v 2.55: Added COLOR command. From now on used PowerBASIC instead of QB.
  v 2.54: Not too smart of me: I forgot LOCATE 1,1 in the new CLS. :o
  v 2.53: Improved CLS routine (6 bytes shorter).
  v 2.52: Added CHAR command.
  v 2.51: Possibility to turn of internal compression. REM command added.
  v 2.50: Parameters for MicroBASIC Extensions and internal compression.
  v 2.40: MicroBASIC Extensions added.
  v 2.32: END [exitcode] bug fixed.
  v 2.31: Fixed little IFANSI bug when not used as first command.
  v 2.30: Added IFANSI command.
  v 2.20: Two new commands: FLUSHBUFFER and PRINTSCREEN.
  v 2.1 : New routine to make EXE files with less memory.
  v 2.0 : The option to create EXE-files too.
  v 1.5 : Added SLEEP command.
  v 1.4 : Added CURSOR command.
  v 1.3 : Added GOSUB and RETURN commands.
  v 1.2 : Added IFKEY command.
  v 1.1 : Added GOTO command.
  v 1.0 : First release, only PRINT and INKEY  :)




10contacttheauthorpage18


  This compiler is far from done. So please give me your support: let me know
  what you think of the compiler. If you found a bug or if you want to have a
  look at the PowerBASIC 3.2 sourcecode, just visit my homepage or e-mail me.
  I'd also like you to send your MicroBASIC programs and MBX-files to me. If
  you want I can also include them in new releases of the MicroBASIC Package.
  You can also look at my homepage to check if newer versions of the compiler
  are available. The addresses are at the bottom of this file.




11requestspage18


   Please send me all your self-made MBF-files and MBX-files!
   Looking for someone to review the documentation (for spelling errors etc,
    my english is not too good).
   Send all your bug-reports to microbasic@blacklight.wxs.org

  NEW: I'm working on an 'Integrated Development/Debugging Environment' for
       MicroBASIC, with the best features of all known DOS IDE's combined:
       QuickBASIC, PowerBASIC, TurboPascal. I'm writing it in PowerBASIC (as
       usual, because it RuLeZz :)).
       I included a beta-version in this MicroBASIC package. It's in the
       EXTRA\IDE_BETA\ directory.
       Please have a look at it and tell me what you think. What you see is
       what I wrote in 4 days. I'm planning to create a complete context-
       sensitive help-system, a lot of configuration options (yeah baby :))
       and maybe... maybe I'll add an inline assembler to the compiler (like
       PowerBASIC has) so creating MBX-files goes real easy in the IDE...
       Give me your feedback at microbasic@blacklight.wxs.org




12relatedproductspage19


  MBX Editor:   To create your own MBX-files using assembly language.
  MB IDE:       Integrated Developing Environment. Coming soon!
  Txt2Exe:      To create small executable Read-Me programs.
  MiniComCrypt: Encrypt any COM-file, like the /E parameter does for MBC.




13copyrightpage19


  This program was compiled using PowerBASIC 3.2. It was released as Free-
  ware. The best things in life are free :) You are free to copy it, as long
  as you don't modify the files. You're also allowed to place it on a CD-ROM
  or any other medium, website or BBS, in fact, you are encouraged to.

  If you want it, I can send you the complete source-code of the compiler.
  With some small changes, the source-code is also compatible with QBasic.

  Stay tuned on the following site for newer versions + extensions:

  BlackLight Homepage:  http://www.blacklight.wxs.org

           -=[THIS PRODUCT WAS MADE IN GOIRLE (NB), HOLLAND!]=-

  The programmer cannot be responsible for any damage on your computer. Use
  this program at your own risk. However: I haven't ever seen a program
  created by my compiler, that crashed without an obvious reason, so don't
  worry too much... Btw: if you find/make one: send it to me!
  Copyright (C) 1995-2001 BlackLight. All rights reserved.
