GET Location, Variable {, Variable, ... }

Function
Copy value(s) from RAM into Variables(s), starting at Location.

• Location  is the starting address to be copied.
• Variable  is byte variable, byte array element, or word variable.

Explanation
The GET instruction provides a convenient method of copy multiple consecutive values from RAM into individual byte variables. For example,

  hrs = clock(0)
  mins = clock(1)
  secs = clock(2)

... can be simplified to a single line of code:

  GET clock(0), hrs, mins, secs 

Note that this works because array elements are stored as addresses.

When Variable is a word, its LSB is read from Location and its MSB from Location + 1. For example:

loVal    VAR     Byte
hiVal    VAR     Byte
result   VAR     Word

Start:
  loVal = $33
  hiVal = $CC
  GET @loVal, result                            ' result = $CC33

Using GET with Subroutine Parameters
When a simple variable is passed to a subroutine by address (using @), as in:

  GOSUB Some_Routine, @aValue                   ' pass address of 'aValue'

... GET can be used to retrieve the value from that address within the subroutine:

Some_Routine:
  rtnAddr = __PARAM1                            ' save return address
  GET rtnAddr, theValue                         ' get value from address
  ...                                           ' do something with the value
  PUT rtnAddr, newValue                         ' update value at passed address
  RETURN

This technique allows the subroutine to accept (and potentially modify) any defined variable. Note that for single-parameter instances, the __RAM() system array may be used in place of GET and PUT:

Some_Routine:
  rtnAddr = __PARAM1                            ' save return address
  theValue = __RAM(rtnAddr)                     ' get value from address
  ...                                           ' do something with the value
  __RAM(rtnAddr) = newValue                     ' update value at passed address
  RETURN

Note: As of SX/B 1.2, Subroutines (and now Functions in SX/B 1.5) can return a value directly so passing the address of a variable (with @) is not required unless multiple variable addresses are to be passed to the Subroutine/Function.

Related instruction: PUT