manual.txt

open source of basic interpreter of 68

                  asm            marks start of inline assembly language source
                  endasm         marks end of inline assembly language source
                  addr()         returns address of a label, variable, or start of
                                 an array
                  push           pushes a value onto the SB68k data stack
                  pop()          pops a value from the SB68k data stack
                  pull()         synonym for pop()
                  place          change an element in the SB68k data stack
                  pick()         copy an element from the SB68k data stack
                  drop           remove one or more elements from SB68k data stack
                  interrupts     enables or disables system interrupts; also sets
                                 lowest allowed interrupt level
                  gosub          invokes an SB68k subroutine
                  usr()          invokes an SB68k subroutine, returns one value
                  return         returns from an ISR or subroutine
                  end            ends an SB68k program or ISR



















                                       Page 13






                 Remarks

                 SB68k provides two comment delimiters, for imbedding remarks
                 in your source files.  The traditional REM statement can be
                 used to start a comment at nearly any point in an SB68k
                 program.  You can also use the newer ' (single-quote).  All
                 text following a remark delimiter is ignored by the SB68k
                 compiler.

                 You can place a comment at the beginning of any line.  You
                 can also place a comment at the end of any complete SB68k
                 statement.  You cannot place a comment within an SB68k
                 statement.

                 Example:

                      rem  This is a legal comment
                      '    So is this

                      a = c + 5                ' this is a legal comment, too
                      a = c +                  ' this is illegal!

                 Note that you can always insert a blank line anywhere in
                 your source; SB68k always ignores blank lines.
































                                            Page 14






                 Include files and the INCLUDE statement

                 SB68k supports the use of include files to help you organize
                 and maintain your projects.  Include files are simply files
                 containing SB68k source code for commonly-used functions.

                 You can insert any include file into your SB68k program file
                 by using the INCLUDE statement.  SB68k will automatically
                 open the named file, compile the code it contains, then
                 resume compiling your original file.

                 For example, you might keep a single file of SB68k code for
                 controlling servo motors.  You can force SB68k to include
                 the code in this file (call it servo.bas) in your current
                 program file, by using the INCLUDE statement:

                      include  "servo.bas"

                 Note the use of double-quotes around the file name.

                 You can, if you like, supply a full pathname with the file
                 name.  For example:

                      include  "c:\sbasic\inc\servo.bas"

                 forces SB68k to search only the supplied path for the file
                 servo.bas.  If SB68k cannot find the file using this path,
                 it will report an error.

                 You can also, if you wish, set the DOS environment variable
                 SB68K_INCLUDE to contain the full pathname of a directory
                 dedicated to holding your include files.  If SB68K_INCLUDE
                 exists, SB68k will search that directory for any files named
                 in INCLUDE statements, provided that the file name does not
                 itself contain any path information.  If SB68K_INCLUDE does
                 not exist, SB68k defaults to searching the current
                 directory.

                 To summarize:

                 1.  If the file name does not contain any path information,
                 SB68k checks for the existence of a DOS environment
                 variable, SB68K_INCLUDE.  If SB68K_INCLUDE exists, SB68k
                 searches the path in that variable for the named file.  If
                 SB68K_INCLUDE does not exist, SB68k searches the current
                 directory.

                 2.  If the file name contains path information, SB68k checks
                 only the given path, regardless of the existence of
                 SB68K_INCLUDE.

                 Rule 2 above means that you can force SB68k to search the
                 current directory, even if SB68K_INCLUDE exists, by using an
                 INCLUDE statement of the form:


                                       Page 15







                      include  ".\test.bas"

                 Here, the backslash serves as path information, forcing
                 SB68k to search the full path given in the INCLUDE
                 statement.


















































                                            Page 16






                 Labels

                 SB68k does not support line numbers, but it does support
                 line labels.  Line labels consist of a string of up to 20
                 characters, including a required terminating colon (:).
                 Labels must begin with an alphabetic character or an
                 underscore ('_'); remaining characters in a label can also
                 include digits.  Any text following a line label definition
                 is ignored.

                 NOTE:  Though legal, starting labels with an underscore can
                 cause obscure problems if you embed assembly language in
                 your SB68k source file.  See the section below on the ASM
                 statement and the ENDASM statement, regarding references to
                 SB68k variables from within an ASM block.

                 Example:
                      foo:                ' define the line label foo
                           a = 3          ' write a value to A
                           return         ' return from this subroutine

                      main:               ' start of the main program
                           gosub foo      ' execute the subroutine foo

                 This example shows several important points.  Note that
                 labels require a trailing colon only when they are defined,
                 but not when they are referenced.  Thus, the GOSUB to FOO
                 doesn't need a colon at the end of FOO.

                 Also, every SB68k program MUST contain the line label MAIN,
                 even if it contains no other line labels.  The startup code
                 that supports SB68k on the target system always jumps to the
                 label MAIN to begin execution.  If your program does not
                 have a MAIN, the compiler will report an error.

                 Note that the line label MAIN does not mark the first line
                 of your program's code; it only marks the starting point for
                 execution of your program following reset.  You are free to
                 place the line label MAIN anywhere in your file you deem
                 appropriate.
















                                       Page 17






                 Numeric constants

                 SB68k supports decimal, hexadecimal, and  binary numeric
                 constants.  To enter a hexadecimal number in an SB68k file,
                 use the $ prefix.  To enter a binary number in an SB68k
                 file, use the % prefix.

                 Hexadecimal numbers may contain the characters 0-9, A-F, and
                 a-f.  Binary numbers may contain the characters 0 and 1.

                 The following examples show how to enter different numeric
                 constants:

                      foo = 1234          '  assigns decimal 1234 to FOO
                      bar = $1234         '  assigns hexadecimal $1234 to BAR
                      alpha = %10000      '  assigns decimal 16 to alpha
                      cat = $12 + 34      '  adds hex $12 to decimal 34


                 SB68k also supports ASCII character constants.  To enter an
                 ASCII constant, enclose the character in single-quotes.  The
                 value used will consist of the binary equivalent of the
                 quoted character.  An ASCII constant always consists of
                 eight bits; the upper eight bits of the variable involved
                 will always be 0.

                 For example:

                      foo = 'a'           '  assigns lowercase-A (97) to foo



























                                            Page 18






                 Variables, arrays, and named constants

                 SB68k requires you to declare the names of all variables
                 used in your program.  You declare variables with the
                 DECLARE statement.  For example,

                      declare  foo

                 creates the SB68k variable FOO.

                 Variable names must begin with an alphabetic character or an
                 underscore ('_'); remaining characters in a variable name
                 can also include digits.

                 NOTE:  Though legal, starting variable names with an
                 underscore can cause obscure problems if you embed assembly
                 language in your SB68k source file.  See the section below
                 on the ASM statement and ENDASM statement, regarding
                 references to SB68k variables from within an ASM block.

                 All variables use four bytes of RAM (32 bits).  The first
                 variable defined is always located at assembler address
                 VARBEG.  Variables are assigned addresses based on the order
                 of their declarations.

                 You must declare a variable before your code can reference
                 that variable.  This means that you will usually place all
                 DECLARE statements in a block at the beginning of your SB68k
                 source file.