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 do not 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 into the command where the variable is needed. However, it is good practice to "dimension" all byte variables and to use #OPTION EXPLICIT. #OPTION EXPLICIT mandates the "dimensioning" of all variables in the user program. Using #OPTION EXPLICIT will improve the quality of the program.

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 to 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 =.

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

    #OPTION EXPLICIT

    dim myByteVarible as Byte
    myByteVarible = 127       'assign the value of 127

GCBASIC supports bitwise assignments, as 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)

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 follows:

    '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. If you need a string of a certain size, it is good practice to set the length of the string, 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          ' <<< printing a string containing embedded quote marks

Key line: HSerPrint myString — prints myString, which was built with doubled quotation marks ("") standing in for each literal quote character; GCBASIC collapses each "" pair back to a single " when the string is compiled, so the printed output reads with normal single quote marks.

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 an alias for the variable, then you must ensure the bytes that construct the variable are consecutive.

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 and 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 causes two byte variables added together to be treated as a word variable.

    Dim MyWord As Word
    MyWord = [word]ByteVar + AnotherByteVar          ' <<< the [word] cast preventing an 8-bit overflow

Key line: MyWord = [word]ByteVar + AnotherByteVar — forces GCBASIC to add ByteVar and AnotherByteVar using word-width arithmetic; without the cast, the addition would be done as a byte operation and silently overflow whenever the true sum exceeds 255.

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 is also possible to cast the second value instead of the first:

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

The result will be exactly the same.

See Also: