GCBASIC documentation
Variables

About Variables and Variable Types

A variable is an area of memory on the microcontroller that can be used to store a number or a series of letters. This is useful for many purposes, such as taking a sensor reading and acting on it, or counting the number of times the microcontroller has performed a particular task.

Each variable must be given a name, such as "MyVariable" or "PieCounter". Choosing a name for a variable is easy - just don’t include spaces or any symbols (other than _), and make sure that the name is at least 2 characters (letters and/or numbers) long.

Variable Types

There are several different types of variable, and each type can store a different sort of information. These are the variable types that GCBASIC can currently use:

Using Variables

Byte variables do not need any special commands to set them up - just put the name of the variable in to the command where the variable is needed.

Other types of variable can be used in a very similar way, except that they must be "dimensioned" first. This involves using the DIM command, to tell GCBASIC that it is dealing with something other than a byte variable.

A key feature of variables is that it is possible the have the microcontroller check a variable, and only run a section of code if it is a given value. This can be done with the IF command.

Number Variables

You can assign values to number variables using &#160`=`.  

A simple, but typical example follows.  This is the typical for numeric variable assignment.

    myByteVarible = 127       'assign the value of 127

GCBASIC support bitwise assignments s follows:

    portc.0 = !porta.1  'set a single bit to the value of another bit

The function FnLSL performs the shift operation found in other languages. Here is an example:

    MyVar = FnLSL( 1, BitNum)`  is Equivalent to `MyVar = 1<<BitNum`

To set a bit of a port and to prevent glitches during operations, use #option volatile as folllows:

    'add this option for a specific port.
    #option volatile portc.0

    'then in your code
    portc.0 = !porta.1

To set a bit of a port or variable, encapsulate it in the SetWith method. Using this method also eliminates any glitches during the update.

    SetWith(MyPORT, MyPORT OR FnLSL( 1, BitNum))

To clear a bit of a port, use this method:

    MyPORT = MyPORT AND NOT FnLSL( 1, BitNum))

To set a bit within an array, use this method:

    video_buffer_A1(video_adress) = video_buffer_A1(video_adress) OR FnLSL( 1, BitNum)

To set a bit within a variable, use this method:

    Dim my_variable as byte
    Dim my_bit_address_variable as byte

    'example
    my_variable = 0
    my_bit_address_variable = 7

    my_variable.my_bit_address_variable = 1   ' where 1 or 0 or any bit address is valid

    'Sets bit 7 of my_variable therefore 128

String Variables

Strings are defined as follows:

    'Create buffer variables to store received messages

    Dim Buffer As String

String variables default to the following rules and the RAM constraints of a specific chip.

You cannot store a string 20 characters long in a chip with 16 bytes of RAM.

You can change the default string size handled internally by the GCBASIC compiler by changing the STRINGSIZE constant:

    'set the default string to 24 bytes
    #define STRINGSIZE 24

Defining a length for the string is the best way to limit memory usage. It is good practice if you need a string of a certain size to set the length of a strings, since the default length for a string variable changes depending on the amount of memory in the microcontroller (see above).

To set the length of a string, see the example below:

    'Create buffer variables to store received messages as 16 bytes long
    Dim OutBuffer As String * 16

To place quotation marks (" ") in a string of text. For example:

    She said, "You deserve a treat!"

To place quotation marks (") in a string of text, use two quotation marks in a row instead of one for each quote mark. The following example shows two ways of printing She said, "You deserve a treat!". This technique works for all output methods (HSerPrint, Print, etc.)

    HSerPrint "She said, ""You deserve a treat!"" "

    Dim myString As String * 39
    myString = "She said, ""You deserve another treat!"" "
    HSerPrint myString

Variable Aliases

Some variables are aliases, which are used to refer to memory locations used by other variables. These are useful for joining predefined byte variables together to form a word variable.

Aliases are not like pointers in many languages - they must always refer to the same variable or variables and cannot be changed.

When setting a register/variable bit ( i.e my_variable.my_bit_address_variable ) and using a alias for the variable then you must ensure the bytes that construct the variable are consective.

The coding approach should be to DIMension the variable (word, integer, or long) first, then create the byte aliases:

    Dim my_variable as LONG
    Dim ByteOne   as Byte alias my_variable_E
    Dim ByteTwo   as Byte alias my_variable_U
    Dim ByteThree as Byte alias my_variable_H
    Dim ByteFour  as Byte alias my_variable

    Dim my_bit_address_variable as Byte
    my_bit_address_variable = 23

    'set the bit in the variable
    my_variable.my_bit_address_variable = 1

    'then, use the four byte variables as you need to.

To set a series of registers that are not consecutive, it is recommended to use a mask variable then apply it to the registers:

    Dim my_variable as LONG
    Dim my_bit_address_variable as Byte
    my_bit_address_variable = 23

    'set the bit in the variable
    my_variable.my_bit_address_variable = 1

    porta =  my_variable_E
    portb =  my_variable_E
    portc =  my_variable_E
    portd =  my_variable_E

Casting

Casting changes the type of a variable or value. To tell the compiler to perform a type conversion, put the desired type in square brackets before the variable. The following example will cause two byte variables added together to be treated as a word variable.

    Dim MyWord As Word
    MyWord = [word]ByteVar + AnotherByteVar

Why do this? Suppose that ByteVar is 150, and AnotherByteVar is 231. When added, this will come to 381 - which will overflow, leaving 125 in the result. However, when the cast is added, GCBASIC will treat ByteVar as if it were a word, and so will use the word addition code. This will cause the correct result to be calculated.

It is good practice to cast when calculating an average:

    MyAverage = ([word]Value1 + Value2) / 2

It’s also possible to cast the second value instead of the first:

    MyAverage = (Value1 + [word]Value2) / 2

The result will be exactly the same.

To apply operations to individual bits of variables see, Set, Rotate

To check variables and apply logic based on their value, see If, Do, For, Conditions

For more help, see: Declaring variables with DIM, Setting Variables