RUN

Syntax: RUN ProgramSlot

Function

Switches execution to another BASIC Stamp program (in a different program slot).

• ProgramSlot is a variable/constant/expression (0 – 7) that specifies the program slot to run.

Quick Facts

^†The BS2pe has 16 slots, but only slots 0 - 7 are available for programs. Slots 8 - 15 may be used for data storage.

Explanation

The BS2e, BS2sx, BS2p, and BS2px have a total of 16 kilobytes of code space; the BS2pe has 16 kilobytes of code space and an additional 16 kilobytes of data space. This EEPROM space is organized into slots of 2 kilobytes (2048 bytes) each. Up to eight different programs can be downloaded to the BASIC Stamp (one program per slot). When the BASIC Stamp powers up, or is reset, the program in slot 0 is executed.

The RUN command allows you to activate another program and causes the BASIC Stamp to stay in the newly activated program until it receives another RUN command, or until a power-down or reset condition occurs. The RUN command is similar to a GOTO command in that it allows you to "goto" another program. Normally a master-type program will be used in program slot 0 (since slot 0 runs first) and will control initial execution of the other programs.

Look at the following example (there are two programs here, make sure to download them into program slots 0 and 1, respectively). See the special use of the $STAMP directive in Defining Multi-File Projects for more information.

Download the following two lines into program slot 0:

  DEBUG "Hello "
  RUN 1

Download the following three lines into program slot 1:

  DEBUG "World!", CR
  PAUSE 1000
  RUN 0

The above two programs (assuming they have been downloaded into program slots 0 and 1, respectively) will display "Hello World!" on the screen. Program 0 is the first to run and it displays "Hello ", then issues a RUN 1 command. The BASIC Stamp then starts execution of program 1, from its first line of code, which causes "World!" to be displayed. Program 1 then pauses for one second and the runs program 0 again.

What Happens To I/O Pins And RAM When Using RUN?

The I/O pins retain their current state (directions and output latches) and all Variable and Scratchpad RAM locations retain their current data during a transition between programs with the RUN command. If sharing data between programs within Variable RAM, make sure to keep similar variable declarations (defined in the same order) in all programs so that the variables align themselves on the proper word, byte, nibble and bit boundaries across programs. The following programs illustrate what happens with mismatched variable declarations:

' Download this program to Slot 0

cats    VAR     Byte
dogs    VAR     Byte

Setup:
  cats = 3
  dogs = 1

Main:
  DEBUG "In Slot 0", CR
  DEBUG ? cats
  DEBUG ? dogs
  RUN 1

' Download this program to Slot 1

cats    VAR     Byte
dogs    VAR     Byte
fleas   VAR     Word

Main:
  DEBUG "In Slot 1", CR
  DEBUG ? cats
  DEBUG ? dogs
  DEBUG ? fleas
  END

When the Slot 1 program runs you may be surprised to see that cats and dogs are now zero and fleas are up to 259! - even though we didn't explicitly define them. What happened? The key to remember is that variable names are simply pointers to RAM addresses, and the PBASIC compiler assigns variable names to RAM in descending order by size. This means that in the Slot 1 program, fleas was assigned to RAM locations 0 and 1 which are holding the values 3 and 1 respectively. Since words are stored low-byte first, the value 259 for fleas makes sense (3 + (1 * 256)).

Any program number specified above 7 will wrap around and result in running one of the 8 programs (RUN 8 will run program 0, RUN 9 will run program 1, etc). The current program slot can be read from the last byte of the Scratchpad RAM. Example:

  #SELECT $STAMP
    #CASE BS2
      pgmSlot = 0                       ' everything in slot 0
      rwSlot = 0
    #CASE BS2E, BS2SX
      READ 63, pgmSlot                  ' read current slot
      rwSlot = pgmSlot                  ' READ/WRITE slot is same
    #CASE BS2P, BS2PE, BS2PX
      READ 127, pgmSlot                 ' get slot control byte
      rwSlot = rwSlot.HIGHNIB           ' READ/WRITE in high nibble
      pgmSlot = pgmSlot.LOWNIB          ' pgm slot in low nibble
  #ENDSELECT