Dim

Syntax

Dim Variable as Size

or

Dim Label as Code = comma delimited data

or

Dim Label as Flash = comma delimited data

Overview

Declare a RAM variable or RAM alias or a Flash memory table. Note. flash memory is the code storage memory on a PIC microcontroller. The directives Code and Flash perform exactly the same operation, but newer devices now call the program space Flash Memory, not Code Memory.

Parameters

Variable can be any alphanumeric character or string. Size is the physical size of the variable, it may be Bit, Pin, Byte, Word, Long, Dword, SByte, SWord, SDword, Float, or String. Label is a valid label name that will be associated with a flash memory table.

Example

' Declare different sized variables
  Dim MyByte as Byte          ' Create an unsigned 8-bit Byte variable
   Dim MyWord as Word          ' Create an unsigned 16-bit Word variable
  Dim MyDword as Dword        ' Create an unsigned 32-bit Dword variable

  Dim MySByte as SByte        ' Create a signed 8-bit SByte variable
   Dim MySWord as SWord        ' Create a signed 16-bit SWord variable
  Dim MySDword as SDword      ' Create a signed 32-bit SDword variable

  Dim MyPin as Pin             ' Create an unsigned 8-bit Byte pin mask
  Dim MyBit as Bit             ' Create a 1-bit Bit variable
  Dim MyFloat as Float        ' Create a 32-bit floating point variable
  Dim MyString as String * 20  ' Create a 20 character string variable
  Dim MyCode as Code = 1,2,3,4,5,6,7 ' Place 7 bytes in flash memory
  Dim MyFlash as Flash = 1,2,3,4,5,6,7 ' Place 7 bytes in flash memory

Notes

Any variable that is declared without the 'as' text after it, will assume an 8-bit Byte type.

Dim should be placed near the beginning of the program. Any references to variables not declared or before they are declared may, in some cases, produce errors.

Variable names, as in the case or labels, may freely mix numeric content and underscores.

Dim bMyVar as Byte

or

Dim wMY_Var as Word

or

Dim tMy_Var2 as Bit

View original PDF page 441

Open page in PDF

Variable names may start with an underscore, but must not start with a number. They can be no more than 32 characters long. Any characters after this limit will cause a syntax error.

Dim 2bMyVar is not allowed.

Variable names are not case sensitive, which means that the variable: -

Dim MYVar

Is the same as…

Dim MYVar

Dim can also be used to create Alias’s to other variables: -

Dim MyByte as Byte        ' Create a Byte sized variable
Dim Var_Bit as MyByte.1   ' Var_Bit now represents Bit-1 of MyByte

Alias’s, as in the case of constants, do not require any RAM space, because they point to a variable, or part of a variable that has already been declared.

RAM space required.

Each type of variable requires differing amounts of RAM memory for its allocation. The list below illustrates this.

Each type of variable may hold a different minimum and maximum value.

• String type variables are only useable with 18F and enhanced 14-bit core devices, and

can hold a maximum of 255 characters.

• Bit type variables may hold a 0 or a 1. These are created 8 at a time, therefore declaring

a single Bit type variable in a program will not save RAM space, but it will save code space, as Bit type variables produce the most efficient use of code for comparisons etc.

• Pin type variables may hold an unsigned value from 0 to 255, and are used to store a

value mask for a Port.Pin. They are unique to the Positron8 compiler and offer a huge range of flexibility when interfacing with peripheral devices.

• Byte type variables may hold an unsigned value from 0 to 255, and are the usual work

horses of most programs. Code produced for Byte sized variables is very low compared to signed or unsigned Word, DWord or Float types, and should be chosen if the program requires faster, or more efficient operation.

View original PDF page 442

Open page in PDF

• SByte type variables may hold a 2's complemented signed value from -128 to +127.

Code produced for SByte sized variables is very low compared to SWord, Float, or SDword types, and should be chosen if the program requires faster, or more efficient operation. However, code produced is usually larger for signed variables than unsigned types.

• Word type variables may hold an unsigned value from 0 to 65535, which is usually large

enough for most applications. It still uses more memory than an 8-bit Byte variable, but not nearly as much as a Dword or SDword type.

• SWord type variables may hold a 2's complemented signed value from -32768 to

+32767, which is usually large enough for most applications. SWord type variables will use more code space for expressions and comparisons, therefore, only use signed variables when required.

• Long type variables may hold an unsigned value from 0 to 16777215, which is a very

large value for the majority of applications. It still uses more memory than a 16-bit Word variable, but not as much as a Dword or SDword type.

• Dword type variables may hold an unsigned value from 0 to 4294967295 making this

the largest of the variable family types. This comes at a price however, as Dword calculations and comparisons will use more code space within the microcontroller Use this type of variable sparingly, and only when necessary.

• SDword type variables may hold a 2's complemented signed value from -2147483648 to

+2147483647, also making this the largest of the variable family types. This comes at a price however, as SDword expressions and comparisons will use more code space than a regular Dword type. Use this type of variable sparingly, and only when necessary.

• Float type variables may theoretically hold a value from -1e37 to +1e38, making this the most versatile of the variable family types. However, more so than Dword types, this comes at a price as floating point expressions and comparisons will use more code space within the microcontroller. Use this type of variable sparingly, and only when strictly necessary. Smaller floating point values usually offer more accuracy.

There are modifiers that may also be used with variables. These are HighByte, LowByte, Byte0, Byte1, Byte2, Byte3, Word0, Word1, SHighByte, SLowByte, SByte0, SByte1, SByte2, SByte3, SWord0, and SWord1,

Word0, Word1, Byte2, Byte3, SWord0, SWord1, SByte2, and SByte3 may only be used in conjunction with 32-bit Dword or SDword type variables.

HighByte and Byte1 are one and the same thing, when used with a Word or SWord type variable, they refer to the unsigned High byte of a Word or SWord type variable: -

  Dim Wrd as Word        ' Create an unsigned Word variable
  Dim Wrd_Hi as Wrd.HighByte
' Wrd_Hi now represents the unsigned high byte of variable Wrd

View original PDF page 443

Open page in PDF

Variable Wrd_Hi is now accessed as a Byte sized type, but any reference to it actually alters the high byte of Wrd.

SHighByte and SByte1 are one and the same thing, when used with a Word or SWord type variable, they refer to the signed High byte of a Word or SWord type variable: -

  Dim Wrd as SWord        ' Create a signed Word variable
  Dim Wrd_Hi as Wrd.SHighByte
' Wrd_Hi now represents the signed high byte of variable Wrd

Variable Wrd_Hi is now accessed as an SByte sized type, but any reference to it actually alters the high byte of Wrd.

However, if Byte1 is used in conjunction with a Dword type variable, it will extract the second byte. HighByte will still extract the high byte of the variable, as will Byte3. If SByte1 is used in conjunction with an SDword type variable, it will extract the signed second byte. SHighByte will still extract the signed high byte of the variable, as will SByte3.

The same is true of LowByte, Byte0, SLowByte and SByte0, but they refer to the unsigned or signed Low Byte of a Word or SWord type variable: -

  Dim Wrd as Word        ' Create an unsigned Word variable
  Dim Wrd_Lo as Wrd.LowByte
' Wrd_Lo now represents the low byte of variable Wrd

Variable Wrd_Lo is now accessed as a Byte sized type, but any reference to it actually alters the low byte of Wrd.

The modifier Byte2 will extract the 3rd unsigned byte from a 32-bit Dword or SDword type variable as an alias. Likewise Byte3 will extract the unsigned high byte of a 32-bit variable.

Dim Dwd as Dword        ' Create a 32-bit unsigned variable named Dwd
Dim Part1 as Dwd.Byte0  ' Alias unsigned Part1 to the low byte of Dwd
Dim Part2 as Dwd.Byte1  ' Alias unsigned Part2 to the 2nd byte of Dwd
Dim Part3 as Dwd.Byte2  ' Alias unsigned Part3 to the 3rd byte of Dwd
Dim Part4 as Dwd.Byte3  ' Alias unsigned Part3 to the high (4th) byte of Dwd

The modifier SByte2 will extract the 3rd signed byte from a 32-bit Dword or SDword type variable as an alias. Likewise SByte3 will extract the signed high byte of a 32-bit variable.

Dim sDwd as SDword        ' Create a 32-bit signed variable named sDwd
Dim sPart1 as sDwd.SByte0 ' Alias signed Part1 to the low byte of sDwd
Dim sPart2 as sDwd.SByte1 ' Alias signed Part2 to the 2nd byte of sDwd
Dim sPart3 as sDwd.SByte2 ' Alias signed Part3 to the 3rd byte of sDwd
Dim sPart4 as sDwd.SByte3 ' Alias signed Part3 to the 4th byte of sDwd

The Word0 and Word1 modifiers extract the unsigned low word and high word of a Dword or SDword type variable, and is used the same as the Byten modifiers.

Dim Dwd as Dword          ' Create a 32-bit unsigned variable named Dwd
Dim Part1 as Dwd.Word0   ' Alias unsigned Part1 to the low word of Dwd
Dim Part2 as Dwd.Word1   ' Alias unsigned Part2 to the high word of Dwd

View original PDF page 444

Open page in PDF

The SWord0 and SWord1 modifiers extract the signed low word and high word of a Dword or SDword type variable, and is used the same as the SByten modifiers.

Dim sDwd as SDword          ' Create a 32-bit signed variable named sDwd
Dim sPart1 as sDwd.SWord0   ' Alias Part1 to the low word of sDwd
Dim sPart2 as sDwd.SWord1   ' Alias Part2 to the high word of sDwd

RAM space for variables is allocated within the microcontroller in the order that they are placed in the BASIC code. For example: -

Dim Var1 as Byte
Dim Var2 as Byte

Places Var1 first, then Var2: -

Var1 equ n
Var2 equ n

This means that on a device with more than one RAM Bank, the first n variables will always be in Bank0 (the value of n depends on the specific PICmicro™ used).

The position of the variable within Banks is usually of little importance if BASIC code is used, however, if assembler routines are being implemented, always assign any variables used within them first.

View original PDF page 445

Open page in PDF