The Usage of Variables in BCX

Declaring Variables

A variable is a declaration consisting of a declarator, an identifier, and a data type that is used to allocate space for storage of a scalar or array value. In BCX, as in the C language, before a variable can be assigned a value, it must be declared.

The chief BCX variable declarator is

• DIM

A BCX variable declaration is made, most commonly, in this syntax format.

• DIM VariableName AS DataType

which, also, can be expressed in this order

• DIM AS DataType VariableName

As well as DIM, the following keywords can be used as variable declarators

• GLOBAL
• SHARED
• LOCAL
• AUTO
• REGISTER
• RAW
• STATIC
• EXTERN

BCX Data Types

BOOL

 DIM BoolVar AS BOOL

CHAR

 DIM ChrVar AS CHAR

UCHAR

 DIM UChrVar AS UCHAR

SHORT

 DIM ShortVar AS SHORT

USHORT

 DIM UShortVar AS USHORT

INTEGER

 DIM IntVar AS INTEGER

 DIM IntVar AS INT

 DIM IntVar

 DIM IntVar%

UINT

 DIM UIntVar AS UINT

LONG

 DIM LongVar AS LONG

ULONG

 DIM ULongVar AS ULONG

LONGLONG

 DIM LLongVar AS LONGLONG

ULONGLONG

 DIM ULLongVar AS ULONGLONG

FLOAT

 DIM FltVar!

 DIM FltVar AS FLOAT

 DIM FltVar AS SINGLE

DOUBLE

 DIM DblVar#

 DIM DblVar AS DOUBLE

LDOUBLE

 DIM LDblVar AS LDOUBLE

STRING (Default Size)

 DIM DfltStrVar$

 DIM DfltStrVar AS STRING

STRING (Custom Size)

 DIM CustStrVar AS STRING * 4096

 DIM CustStrVar [4096] AS CHAR

In addition to the above data type keywords, a sigil suffix appended to the variable name, can be used to inform the BCX translator of the data type of the variable.

• % signifies an INTEGER data type
• ! signifies an FLOAT data type
• # signifies an DOUBLE data type
• $ signifies an STRING data type

More than one variable can be declared on a single line. For example, this code

 DIM a AS INTEGER, b AS INTEGER, c AS INTEGER

is equivalent to this code

 DIM a AS INTEGER
 DIM b AS INTEGER
 DIM c AS INTEGER

☞ However, the BCX parser will not parse, correctly, this code

 DIM AS INTEGER a, AS INTEGER b, AS INTEGER c

but, because the declaration of variables with forward propagation of variable type is allowed in BCX, the above declarations can be expressed as

 DIM AS INTEGER a, b, c 

Here are some other examples showing the declaration of variables with forward propagation of variable type.

Example:

 DIM AS DOUBLE A, B, C[2]                    ' all variables are doubles
 
 DIM AS INTEGER A[] = {4,5}, B, C[2] = {0,1} ' all variables are integer
 
 DIM AS CHAR PTR PTR A, B[3]                 ' all variables are POINTERS to POINTERS of CHAR

BCX also allows declaring different data type variables with one statement.

Example:

 DIM A%, B!, D$ * 1000, E[10,10]

creates an integer, a single, a string, and a 2 dimensional integer array.

Declaring Global Variables

Variables declared with DIM at the module level of the program are automatically given GLOBAL scope. They can be used anywhere in a program.

Also, using the GLOBAL or SHARED keywords will create GLOBAL variables anywhere in a program .

All variable names with GLOBAL scope must be unique, including variables created using DIM in the main portion of the program. That means that a program cannot have a GLOBAL variable named A$ and another named A%. However, a variable named A$ and another named a$ can co-exist as GLOBAL variables because BCX variable names are case sensitive. Therefore, A$ and a$ are seen as different variables.

When declared within a SUB or FUNCTION, a GLOBAL variable, in the C translation, is moved to the module level and, there, is declared as a static data type.

 DIM add1more%, i%, int1%
  
 add1more% = 1
  
 FOR i% = 1 TO 5
  int1% = Count%(add1more%)
  PRINT "Total is "; int1%
 NEXT i%
 ?
 PRINT "total%,", total%, ", is accessible from module level."
  
 FUNCTION Count%(it%)
  GLOBAL total%
  total% = total% + it%
  FUNCTION = total%
 END FUNCTION

Result:

 Total is  1
 Total is  2
 Total is  3
 Total is  4
 Total is  5

 total%, 5, is accessible from module level.

If, in the above example, the

 GLOBAL total%

is changed to

 LOCAL total%

the program would be translated by BCX but the C compiler would error the 'total' identifier, as undeclared, when used outside of the 'Count%' function.

Declaring Local Variables

When DIM or LOCAL is used within a SUB or FUNCTION to declare a variable, the variable is LOCAL in scope to that SUB or FUNCTION, or in other words, the variable is unknown to the rest of the program.

A variable declared with DIM or LOCAL in a subroutine or function retains, and can return, the value on exit, but will lose it on re-entry due to automatic initialization to NULL. This is not the case with returning a local scope variable pointer.

☞ The only time it is "safe" to return the address of a local scope variable, declared inside a SUB or FUNCTION, is when that variable is declared STATIC.

STATIC ensures that a variable's storage location and memory allocation will not change. The contents may change under your app's control but the address of the variable won't.

Returning the address of a DIM or LOCAL variable is, at least, unreliable and, at most, dangerous because when the function concludes, those variables go out of scope. Those variables were created on the Windows memory stack which is constantly changing and being reused. In fact, most compilers try to warn you of this in one way or another:

• Pelles C: warning #2173: Pointer to local 'A' is an invalid return value.
• GCC : warning: address of local variable 'A' returned
• Clang : warning: address of stack memory associated with local variable 'A' returned
• MSVC : warning C4172: returning address of local variable or temporary: A

This is important when returning pointers, as demonstrated in the following example.

 GLOBAL B AS CHAR PTR
 
 B = foo("Hello")
 'B$ is now using the storage provided by
 'STATIC A$ in function foo
 B$ = B$ + " World"
 PRINT B$
 
 PRINT foo$("Second call to foo")
 PRINT B$
 
 END
 
 FUNCTION foo(text$) AS LPSTR
 STATIC A$ ' If this were changed to 
 ' DIM  A$, LOCAL A$, or RAW A$
 ' a compile warning would occur with unpredictable results on execution.  
 A$ = "(" + text$ + ")"
 FUNCTION = A
 END FUNCTION

Result:

 (Hello) World
 (Second call to foo)
 (Second call to foo)

Example:

 DIM A!            ' Global
 DIM B!            ' Global
 DIM C!            ' Global

 C! = 100.123      '<<< This value Should Not Change!
 B! = 123          '<<< This Value Should Not Change!
 A! = Fun!(B!, C!) '<<< "C" allows type translation automatically!

 PRINT "The Value Of A! = ", A!
 PRINT "The Value Of B! Should Still Be <123> ...", B!
 
 FUNCTION Fun!(Y%, Z%)
   DIM A$
   DIM B!
   A$ = "Hello from inside our function!"  ' A$ is a local string variable 
   PRINT A$
   ' On the next line, B! is of local scope, only accessible in FUNCTION Fun 
   ' C! is global, accessible from anywhere
   ' Z% and Y% are function parameter variables of local scope 
   B! = 3 * Z% + C! + Y%
   FUNCTION  = B!
 END FUNCTION

Result:

 Hello from inside our function!
 The Value Of A! =  523.123
 The Value Of B! Should Still Be <123> ... 123

Remarks:

Quoted string literal initializations inside a SUB or FUNCTION can be made.
☞ This will not work for GLOBAL strings. It will not work for dynamic strings that are created using any of the memory allocation functions: malloc/calloc/realloc. String functions and concatentations are not allowed -- only plain quoted string literals will work, like in the examples below:

 $BCXVERSION "7.7.2"

 DIM A$     = "This is handy!"    
 DIM RAW A$ = "This is too!"
 LOCAL A$   = "This also works!"

BCX translates the following initialized quoted string literal:

 DIM A$ = "This is handy!"

to the following C language code.

 char A[BCXSTRSIZE]; strcpy(A,"This is handy"); 

For more examples with LOCAL declaration, see S52.bas S56.bas S61.bas.

Declaring Dynamic Strings

BCX provides dynamically sized, one dimensional strings.

Dynamically declared strings are limited only by available memory. A string sized as

 DIM DynaVar$ * 5000000

would allocate five megabytes for the string variable DynaVar$.

It is important to remember, when sizing a dynamic string, that BCX uses C strings which are terminated with a single byte NULL character to mark the end of the string. All BCX strings must be sized large enough to include this terminator. For example, if a string contains 15 characters then it must be sized to at least 16 bytes.

FREE statement

It is possible to create huge  dynamically declared string variables which can consume multi-megabytes of memory. When a dynamic string variable is declared and used inside a SUB or FUNCTION, BCX takes care of the string memory deallocation code.

☞ When a dynamic string variable has been declared and used outside of a SUB or FUNCTION, after the variable is no longer needed, the memory space allocated must be returned back to Windows by using the FREE keyword. It is up to the programmer to determine at what point in the program to FREE the variable. This must be done to guard against memory leaks which can adversely affect system performance, and in worse cases cause a crash due to an out of memory condition.

Here is a complete example:

 
 DIM Buffer$ * (1000 * LEN("Line No. ") + 1000 * 10)
 DIM A AS INTEGER

 FOR A = 1 TO 1000
  Buffer$ = Buffer$ & "Line No. " & STR$(A) & CHR$(13) & CHR$(10)
 NEXT

 PRINT Buffer$
 A = LEN(Buffer$)
 PRINT "The length of Buffer$ = ", A , " bytes."
 FREE Buffer$        'release memory back to Windows

Result:

 Line No.  1
  ...
 Line No.  1000

 The length of Buffer$ = 14893 bytes.

Remarks:

Freeing strings is very important if they are in a loop or in a procedure that may be called several times. If the variable is not freed before it is declared again, a "memory leak" occurs with an additional chunk of memory allocated in which to store the string each time the dynamic variable is declared. Unless deallocated with FREE, the last chunk of memory is not available for use. If this happens in an often repeated loop, the memory can be used up to the point of causing the machine to crash. Finding the appropriate point to FREE a variable is not simple and requires a thorough understanding of how the program is structured.

Declaring Dynamic Strings inside a SUB or FUNCTION

You can declare dynamic strings inside a SUB or FUNCTION using the following syntax:

Syntax: DIM A3$ * 2048
  Purpose: Allocates space for a 2048 byte LOCAL dynamic string.

Syntax: GLOBAL Buffar$ * lenbuf%
  Purpose: Allocates space the size of lenbuf% for a GLOBAL dynamic string

Syntax: DIM LOCAL A4$ * 1
  Purpose: Allocates space for a 1 byte local dynamic string

Syntax: LOCAL A5$ * 1024
  Purpose: Allocates space for a 1024 byte local dynamic string

BCX uses C strings which are terminated with an NULL character. A string must be sized large enough to include this terminator.

If declared in a SUB or FUNCTION, the variable will be local in scope. Locally declared dynamic strings must exist on the base level of the SUB or FUNCTION. They must not be declared inside any IF...ENDIF, FOR...NEXT, SELECT...END SELECT, or LOOP structures. The most appropriate place for these statements is immediately after the SUB or FUNCTION declaration.

Although it is perfectly legal to declare GLOBAL dynamic strings within a FUNCTION or SUB procedure, it is best if the string is declared in the initialization section of the program and REDIM then is used to modify the size of the string in the procedure. Be sure to FREE the memory allocated for the GLOBAL dynamic string when it is no longer needed.

 GLOBAL Z$ * 1000              ' Z$ is global

 SUB FOO
  DIM    a$ * 1000             ' a$ is LOCAL with automatic Free
  LOCAL  b$ * 1000             ' b$ is LOCAL with automatic Free
  GLOBAL c$ * 1000, d$ * 1000  ' c$ and d$ are global 
  DoSomeThing()
  FREE c$                      ' GLOBAL MUST be freed before exit
  FREE d$                      ' GLOBAL MUST be freed before exit
 END SUB

Declaring Dynamic Strings outside of a SUB or FUNCTION (Console mode only)

Creating a dynamic variable using DIM or GLOBAL outside of a SUB or FUNCTION will create a GLOBAL dynamic string.

Dynamic strings outside of a SUB or FUNCTION procedure can be declared with the following syntaxes:

 DIM DynStrVar$ * 2048

 GLOBAL Buffar$ * lenbuf%

Remarks:

Dynamically declared string and array variables can be cleared and resized, increasing or decreasing a variable's size, using the REDIM statement.

☞ In GUI programs, a dynamic string must be declared inside a BEGIN EVENTS ... END EVENTS structure or inside a FUNCTION or a SUB procedure.

☞ When using $NOMAIN

• do not declare dynamic strings outside of a SUB or FUNCTION.
• FREE must be used to deallocate memory when a dynamic string has been declared within a FUNCTION MAIN().

Storage Class Specifiers

BCX recognizes the AUTO, REGISTER, EXTERN and STATIC storage class specifiers. Variables declared with the AUTO or REGISTER specifier have local persistence, that is, the values in those variables are lost when the subroutine or function in which they were declared is exited. Variables declared with the EXTERN or STATIC specifier have global persistence that is, the values in those variables are retained when the subroutine or function in which they were declared is exited.

AUTO storage class specifier

☞ Do not use AUTO if compiling with C++. Since 2010, the AUTO keyword is no longer a C++ storage-class specifier and has been repurposed.

When AUTO is used, an automatic variable, a variable with a local lifetime, is declared. The scope of an AUTO variable is limited to the block in which it was declared. AUTO is the default storage class for local variables but must be explicitly specified when programming threads.

 AUTO AutoVar AS data type

EXTERN storage class specifier

When EXTERN is used, the variable declared with EXTERN becomes a reference to a variable with the same name defined externally in any source files of the program. The EXTERN declaration makes the external-level variable definition visible within the block. A variable declared with the EXTERN keyword is visible only in the block in which it is declared unless the external variable has been declared as a global.

 EXTERN ExtVar AS data type

STATIC storage class specifier

When STATIC is used within a SUB or FUNCTION, to declare a variable, the variable will retain its value from call to call. When DIM or LOCAL is used within a SUB or FUNCTION to declare a variable, the variable will not retain its value from call to call. STATIC variables are automatically initialized (set to zero value) only the first time they are declared.

 STATIC StatVar AS data type

An example showing the STATIC difference:

 DIM add1more%, i%, int1%

 add1more% = 1

 FOR i% = 1 TO 5
  int1% = Count%(add1more%)
  PRINT "Total is "; int1%
 NEXT i%

 FUNCTION Count%(it%)
  STATIC total%
  total% = total% + it%
  FUNCTION = total%
 END FUNCTION

Result:

 Total is  1
 Total is  2
 Total is  3
 Total is  4
 Total is  5

Here is the same example without STATIC

 DIM add1more%, i%, int1%

 add1more% = 1

 FOR i% = 1 TO 5
  int1% = Count%(add1more%)
  PRINT "Total is "; int1%
 NEXT i%

 FUNCTION Count%(it%)
  DIM total%
  total% = total% + it%
  FUNCTION = total%
 END FUNCTION

Result:

 Total is  1
 Total is  1
 Total is  1
 Total is  1
 Total is  1

REGISTER storage class specifier

☞ Do not use REGISTER if compiling with C++. It was deprecated in the C++11 standard and removed from C++17 standard.

REGISTER is used to define local variables to be stored in a register instead of RAM.

 REGISTER RegVar AS DataType

Remarks:

A REGISTER variable has a maximum size equal to the register size. The unary address-of operator(&) can not be applied to a REGISTER variable nor can the REGISTER keyword be used on arrays. REGISTER is best used with variables that need quick access.

☞ Specifying REGISTER does not mean that the variable will be stored for certain in a register.

VOLATILE data type qualifier

The VOLATILE data type qualifier specifies that the memory access to the variable, array or other data object is to be consistent. VOLATILE data can have its value changed without the control or detection of the compiler, for example, the system clock or other program updating a variable.

Here are some examples of data declarations with the VOLATILE data type qualifier.

 TYPE z
  DIM VOLATILE a AS INTEGER
  DIM c[20] AS CHAR
 END TYPE
  
 DIM VOLATILE ddd
 GLOBAL VOLATILE aaa AS INTEGER
 SHARED VOLATILE BBB AS z
 EXTERN VOLATILE ccc AS INTEGER
  
 SUB v()
  STATIC VOLATILE zz AS z
  
 END SUB
 

RAW statement

Purpose: RAW can be used to create uninitialized variables. RAW does not clear the memory block of the created variable by filling it with zeros. A RAW variable created in a subroutine or function is not STATIC in retaining a value between calls to the procedure.

 RAW VariableName

Remarks:

RAW does not initialize variables inside SUB or FUNCTION procedures, for example,

 SUB RawSub1()
  RAW str1$
 END SUB

translates to C source code

 void RawSub1 (void)
 {
   char    str1[BCXSTRSIZE];
 }

while

 SUB RawSub1()
  DIM str1$
 END SUB

translates to C source code

 void RawSub1 (void)
 {
   char    str1[BCXSTRSIZE]={0};
 }

RAW used outside of a SUB or FUNCTION procedure is the same as STATIC, for example,

 RAW a$

translates to C source code

 static char    a[BCXSTRSIZE];

LOCAL variables slow things down a bit because they need to be zero'd out each time. RAW are the fastest but require that you give them meaningful values as needed. Consider this ... why take the time to zero an integer if you unconditionally assign it a value.

Variable Scope

BEGINBLOCK ... ENDBLOCK statements

Purpose: The BEGINBLOCK ... ENDBLOCK statements allow BCX to limit the scope of allocated varibles. A BEGINBLOCK statement is placed before the section to which you want to limit the scope and an ENDBLOCK statement specifies the end of the scope limited section.

 BEGINBLOCK
  Variables defined here will be limited in scope
  to the section between the BEGINBLOCK ... ENDBLOCK statements.
 ENDBLOCK

Example:

 DIM sProg$
 
 sProg$ = "This Program will show two MSGBOXs with different results" & CRLF$
 sProg$ = sProg$  &  "DIM i" & CRLF$
 sProg$ = sProg$  &  "i = 2" & CRLF$
 sProg$ = sProg$  &  "BEGINBLOCK" & CRLF$
 sProg$ = sProg$  &  "DIM i" & CRLF$
 sProg$ = sProg$  &  "i = 5" & CRLF$
 sProg$ = sProg$  &  "MSGBOX " & ENC$("i =") & " & STR$(i)" & CRLF$
 sProg$ = sProg$  &  "ENDBLOCK" & CRLF$
 sProg$ = sProg$  &  "MSGBOX " & ENC$("i =") & " & STR$(i)" & CRLF$
 
 MSGBOX sProg$
 DIM i
 i = 2
 
 BEGINBLOCK
  DIM i
  i = 5
  MSGBOX "i =" & STR$(i)
 ENDBLOCK
 
 MSGBOX "i =" & STR$(i)
 

Declaring and Dimensioning Arrays

As with BCX common variables, an array declaration is made, most commonly, using this syntax.

 
 DIM ArrayName[Elements] AS DataType

An array declaration also can be made, with a forward propagation of variable type, using this syntax

 DIM AS DataType ArrayName[Elements] 

In a declaration without a data type as, for example,

 DIM ArrayName[Elements] 

the array is considered to be an INTEGER data type.

Any BCX sigil (%, !, # or $) can be used to indicate the data type of the array as, for example, the % sigil appended to ArrayName

 DIM ArrayName%[Elements] 

specifies that the array is to be declared as an INTEGER data type.

• ☞ In BCX, brackets,

  
   [ ]
  
  

  not parentheses,

  
   ( )
  
  

  are used for delimiting array dimensions and elements.
• In BCX, if an array is declared as

  
   DIM TheArray[10]
  
  

  a one dimensional array of 10 elements, indexed from TheArray[0] to TheArray[9] will be created for data storage.
  ☞ This differs from QBASIC which will allocate storage for 11 elements, indexed from TheArray[0] to TheArray[10].

Dimensions

 DIM TheArray[Elements] AS DataType

 DIM TheArray[10] AS INTEGER
 
 TheArray[0] = 1
 TheArray[1] = 2
 TheArray[2] = 3
 TheArray[3] = 4
 TheArray[4] = 5
 TheArray[5] = 6
 TheArray[6] = 7
 TheArray[7] = 8
 TheArray[8] = 9
 TheArray[9] = 10
 
 FOR INTEGER i = 0 TO 9
  PRINT TheArray[i]
 NEXT i

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10

 DIM TheArray[Elements, Elements2] AS DataType

 DIM TheArray[Elements][Elements2] AS DataType

 DIM TheArray[3, 3] AS INTEGER
  
 TheArray[0, 0] = 1
 TheArray[0, 1] = 2
 TheArray[0, 2] = 3
 TheArray[1, 0] = 4
 TheArray[1, 1] = 5
 TheArray[1, 2] = 6
 TheArray[2, 0] = 7
 TheArray[2, 1] = 8
 TheArray[2, 2] = 9
  
 FOR INTEGER i = 0 TO 2
  FOR INTEGER i2 = 0 TO 2
   PRINT TheArray[i, i2]
  NEXT i2
 NEXT i

 1
 2
 3
 4
 5
 6
 7
 8
 9

Initialization of Arrays

The elements of an array can be initialized, that is, given a value, at the time of declaration by using a brace-enclosed list of comma-separated constant expressions. The one-dimensional array definition in Example 1 is a completely initialized demonstration of this technique.

Example 1:

 DIM TheArray%[3] = { 2, 4, 8 }
  
 PRINT "TheArray%[0] =", TheArray%[0]
 PRINT "TheArray%[1] =", TheArray%[1]
 PRINT "TheArray%[2] =", TheArray%[2]

Result:

 TheArray%[0] = 2
 TheArray%[1] = 4
 TheArray%[2] = 8

☞ There is a length limitation of 128 bytes for the total length of the initializers list between the first brace "{" and the final brace "}". For arrays containing larger sets of elements, use the SET ... END SET statements.

Example 2: shows a partially initialized one dimensional array.

 DIM TheArray%[3] = { 2, 4 }
  
 PRINT "TheArray%[0] =", TheArray%[0]
 PRINT "TheArray%[1] =", TheArray%[1]
 PRINT "TheArray%[2] =", TheArray%[2]

Result:

 TheArray%[0] = 2
 TheArray%[1] = 4
 TheArray%[2] = 0

Example 3: shows how to specify which elements of an array are to be initialized.

 DIM TheArray%[3] = { [0] = 2, [2] = 8 }
  
 PRINT "TheArray%[0] =", TheArray%[0]
 PRINT "TheArray%[1] =", TheArray%[1]
 PRINT "TheArray%[2] =", TheArray%[2]

Result:

 TheArray%[0] = 2
 TheArray%[1] = 0
 TheArray%[2] = 8

Example 4: shows how to initialize elements of an array in which the index size is not specified.

 DIM TheArray%[ ] = { 2, 4, 8 }
  
 PRINT "TheArray%[0] =", TheArray%[0]
 PRINT "TheArray%[1] =", TheArray%[1]
 PRINT "TheArray%[2] =", TheArray%[2]

Because no index size was specified for array2%, three initialized elements are defined by the compiler.

Result:

 TheArray%[0] = 2
 TheArray%[1] = 4
 TheArray%[2] = 8

Example 5: shows how to use variables as elements in an array in which both the array and the element variables have global scope. The example also shows how to access the values efficiently using the CRT function "memmove", which is wrapped into a macro.

 DIM Ind0
 DIM Ind1
 DIM Ind2
  
 DIM RAW TheArray[3]= {&Ind0, &Ind1, &Ind2} AS LPVOID
  
 Ind0 = 1
 Ind1 = 2
 Ind2 = 3
  
 CALL Ordinate()
  
 SUB Ordinate()
   DIM i AS INTEGER
  
   STORE (i,TheArray[0]) : PRINT i
   STORE (i,TheArray[1]) : PRINT i
   STORE (i,TheArray[2]) : PRINT i
 END SUB
  
 CONST STORE(src,des) memmove(&src,des,SIZEOF(src))

Result:

 1
 2
 3

Dimensioning DYNAMIC Arrays

DYNAMIC arrays can be any data type and may be global or local. DYNAMIC arrays differ from static arrays in that DYNAMIC arrays can be resized by using REDIM.

☞ In GUI programs, when declaring a DYNAMIC array, the DIM DYNAMIC, LOCAL DYNAMIC, or GLOBAL DYNAMIC statement must appear inside a BEGIN EVENTS ... END EVENTS structure or inside a FUNCTION or a SUB.

If a GLOBAL DYNAMIC array is to be used inside a FUNCTION or a SUB, it is best if the string is declared in the initialization section of the program and REDIM then is used to modify the size of the string in the procedure.

Syntax: DIM DYNAMIC A[10,10]
  Purpose: Allocates a two dimensional array of integers

Syntax: DIM DYNAMIC B![10,10]
  Purpose: Allocates a two dimensional array of single floating point numbers

Syntax: DIM DYNAMIC C#[10,10]
  Purpose: Allocates a two dimensional array of double floating point numbers

Syntax: DIM DYNAMIC D$[10,10]
  Purpose: Allocates a two dimensional 10 by 10 array of 2048 byte strings

Syntax: DIM DYNAMIC E[10,10] AS CHAR
  Purpose: Allocates an single dimensioned array of 10 10 byte strings

The default string length of each element in a DYNAMIC string array is 2048 bytes, consistent with the rest of BCX. However, the default can be overridden by adding the AS CHAR data type qualifier. This causes the second parameter to define the string length of each element, similiar to declaring static string arrays:

 Default:      DIM DYNAMIC A$[1000] ' 2048 bytes per cell
 User defined: DIM DYNAMIC A$[1000,80] AS CHAR ' 80 bytes per cell

LOCAL DYNAMIC arrays in most instances are automatically freed. However, one exception to this is that DYNAMIC arrays are not automatically freed when they are declared within a FUNCTION MAIN() under a $NOMAIN directive.

☞ When declaring a DYNAMIC array of files, the data type must be specified as AS FILE PTR.

GLOBAL DYNAMIC arrays must be deallocated using

 FREE ArrayName

Also, please note that DYNAMIC arrays are not automatically freed when they are declared within a FUNCTION MAIN() under a $NOMAIN directive.

☞ When dimensioning a DYNAMIC variable length array, do not append a % sigil to an array index subscript variable name.

 
 DIM DYNAMIC A$[E]

is legal, but

 
 DIM DYNAMIC A$[E%]

is not legal and will cause compiler errors.

☞ When dimensioning a DYNAMIC variable length array, using a floating point variable as an index subscript in an array will result in undefined behavior.

Here is a program that demonstrates resizing a DYNAMIC array.

 CLS
 
 DIM DYNAMIC Buffer$[7,5] AS CHAR 'Seven cells, 5 bytes each 
 
 FOR INTEGER i = 0 TO 6
  Buffer$[i] = "No" & STR$(i)
  PRINT Buffer$[i]
 NEXT
 
 ? "******************"
 ? "Resizing ..."
 ? "******************"
 
 REDIM Buffer$[20,10] AS CHAR 'twenty cells, 10 bytes each 
 
 FOR INT i = 0 TO 19
  Buffer$[i] = "No" & STR$(i)
  PRINT Buffer$[i]
 NEXT
  
 FREE Buffer

 KEYPRESS

Result:

 No 0
 No 1
 No 2
 No 3
 No 4
 No 5
 No 6
 ******************
 Resizing ...
 ******************
 No 0
 No 1
 No 2
 No 3
 No 4
 No 5
 No 6
 No 7
 No 8
 No 9
 No 10
 No 11
 No 12
 No 13
 No 14
 No 15
 No 16
 No 17
 No 18
 No 19

OPTION BASE directive

The default lower bound for an index in a user defined array in a BCX program, normally 0, can be set to another value using the OPTION BASE directive.

☞ Arrays defined in the runtime functions such as SPLIT and DSPLIT can not use the value set by OPTION BASE but always will use the BCX default lower bound of 0.

 OPTION BASE Number%

Here are a few comments and a small sample explaining how BCX treats this directive.

OPTION BASE works with static and dynamic arrays. Whenever BCX detects an OPTION BASE directive, BCX sets a global integer variable named "OptionBase" to the size of the OPTION BASE. This process can be seen in the following snippet from the BCX translator:

 IF L_Stk_1$ = "option" AND L_Stk_2$ = "base" THEN
  OptionBase = VAL(Stk$[3])
  Ndx = 0
  EXIT SUB
 END IF

Later on in the translation process, this code takes over:

 IF OptionBase THEN
  IF Stk$[i] = "[" THEN Stk$[i] = "[" & LTRIM$(STR$(OptionBase)) & "+"
 END IF

This means that you can use numerous OPTION BASE directives in your BCX source code. The thing to remember is that the current OPTION BASE value is a function of its location (line number) in your BASIC source code. Also remember that BCX reads source code in a linear manner, including BASIC source files that are merged into your main BASIC source code file using the $INCLUDE directive.

Here is a GUI example using OPTION BASE

 OPTION BASE 20
 GLOBAL MyStrings$[10]   ' Translated to MyStrings[20+10][2048]

 GUI "OpBase"

 SUB FORMLOAD
  DIM F AS CONTROL
  F = BCX_FORM("Option Base")
  CENTER(F)
  SHOW(F)
  OPTION BASE 1
  DIM a[10]  ' Translated to a[1+10]
 END SUB

 OPTION BASE 0

 SUB FOO
  DIM b[10]   ' Translated to b[10]
 END SUB

 SUB MOO

  OPTION BASE 5

  DIM c[10]  ' Translated to c[5+10]
 END SUB

 BEGIN EVENTS
 END EVENTS

For another example of using OPTION BASE see S145.bas.

The default lower bound for all array indexes in the program can be set using the OPTION BASE statement. A complete explanation for using OPTION BASE is above in the OPTION BASE section.

Here is an example using a DYNAMIC variable length array.

 OPTION BASE 1
 
 DIM DYNAMIC A$[5] 

 FOR INTEGER I = 1 TO 5
   A$[I] = "A$[] ... THIS IS LINE " & STR$(I)
   PRINT A$[I]
 NEXT
 
 FREE A$  ' Release memory back to the operating system
 FREE A$  ' An intentional error -- BCX handles it automatically
 
 CALL FOO_TEST
 
 SUB FOO_TEST()
   DIM RAW E = 5
   DIM DYNAMIC A$[E]
   DIM DYNAMIC B$[E]
   DIM DYNAMIC C$[E]
   DIM DYNAMIC D$[E]
 
   PRINT "Storing Items In A$[]"
   FOR INTEGER I = 1 TO E
     A$[I] = "A$[] ... THIS IS LINE " & STR$(I)
   NEXT
 
   PRINT "Storing Items In B$[]"
   FOR INTEGER I = 1 TO E
     B$[I] = "B$[] ... THIS IS LINE " & STR$(I)
   NEXT
 
   PRINT "Storing Items In C$[]"
   FOR INTEGER I = 1 TO E
     C$[I] = "C$[] ... THIS IS LINE " & STR$(I)
   NEXT
 
   PRINT "Storing Items In D$[]"
   FOR INTEGER I = 1 TO E
     D$[I] = "D$[] ... THIS IS LINE " & STR$(I)
   NEXT
 
   FOR INTEGER I = 1 TO E
     PRINT A$[I]
     PRINT B$[I]
     PRINT C$[I]
     PRINT D$[I]
   NEXT
 
 END SUB

Result:

 A$[] ... THIS IS LINE  1
 A$[] ... THIS IS LINE  2
 A$[] ... THIS IS LINE  3
 A$[] ... THIS IS LINE  4
 A$[] ... THIS IS LINE  5
 Storing Items In A$[]
 Storing Items In B$[]
 Storing Items In C$[]
 Storing Items In D$[]
 A$[] ... THIS IS LINE  1
 B$[] ... THIS IS LINE  1
 C$[] ... THIS IS LINE  1
 D$[] ... THIS IS LINE  1
 A$[] ... THIS IS LINE  2
 B$[] ... THIS IS LINE  2
 C$[] ... THIS IS LINE  2
 D$[] ... THIS IS LINE  2
 A$[] ... THIS IS LINE  3
 B$[] ... THIS IS LINE  3
 C$[] ... THIS IS LINE  3
 D$[] ... THIS IS LINE  3
 A$[] ... THIS IS LINE  4
 B$[] ... THIS IS LINE  4
 C$[] ... THIS IS LINE  4
 D$[] ... THIS IS LINE  4
 A$[] ... THIS IS LINE  5
 B$[] ... THIS IS LINE  5
 C$[] ... THIS IS LINE  5
 D$[] ... THIS IS LINE  5

UBOUND function

Purpose: UBOUND will return the largest index value of an array subscript. This only works with single dimensioned, static arrays.

 RetVal% = UBOUND(ArrayName)

Example 1:

 DIM ArrayInt% [5]
 
 DIM ArrayStr$ [10]

 ArrayStr$ [0] = "zero"
 
 ArrayInt% [0] = 0

 PRINT UBOUND(ArrayInt%)
 
 PRINT UBOUND(ArrayStr$)

Result:

 4
 9

Example 2:

 SET Province$[] AS CHAR PTR
   "Alberta", "AB",
   "British Columbia", "BC",
   "Manitoba", "MB",
   "New Brunswick", "NB",
   "Newfoundland", "NL",
   "Northwest Territories", "NT",
   "Nova Scotia", "NS",
   "Nunavut", "NU",
   "Ontario", "ON",
   "Prince Edward Island", "PE",
   "Quebec", "QC",
   "Saskatchewan", "SK",
   "Yukon Territory", "YT"
 END SET
 
 PRINT UBOUND(Province$)

Result:

 25

ISPTR macro

ISPTR is a macro that simply says, if this is a valid element belonging to a dynamic string array, return it, otherwise return zero. This eliminates the need to know how many elements are being passed to a SUB or FUNCTION.

STRARRAY data type-declaration

STRARRAY, instructs BCX to generate code specifying that a dynamic string array is being passed to a user defined SUB or FUNCTION.

 DIM DYNAMIC Buf$ [10]

 Buf$[0] = "Zero"
 Buf$[1] = "One"
 Buf$[2] = "Two"
 Buf$[5] = "Five"

 CALL Foo(Buf$)

 SUB Foo(A$ AS STRARRAY)
  LOCAL i
  WHILE ISPTR(A$[i])
    IF A$[i] > "" THEN PRINT A$[i]
     INCR i
  WEND
 END SUB

Result:

 Zero
 One
 Two
 Five

Using PTR to create pointer variables

Pointer variables can be created using the reserved keyword PTR.

Any of the integer, floating point or string data types listed above can be used with AS PTR appended to create a pointer variable of that data type. Here are two examples:

Syntax: DIM LOCAL a AS INTEGER PTR
  Purpose: Allocates space for a pointer to integer

Syntax: DIM STATIC a AS SINGLE PTR
  Purpose: Allocates space for a pointer to single floating point number

PTR also can be used in SUB and FUNCTION parameter lists, for example,

 DIM rct AS RECT
 
  rct.left = 1
  rct.top = 2
  rct.right = 100
  rct.bottom = 100
 
  rectProc(&rct) ' The argument being passed by reference
                 ' must be preceded by an ampersand.
 PAUSE
 
  SUB rectProc(rct AS RECT PTR)
   ? rct->left
   ? rct->top
   ? rct->right
   ? rct->bottom
  END SUB

Result:

 1
 2
 100
 100

Using PTR PTR to create pointers to pointer variables

Pointers to pointer variables can be created using the reserved keyword PTR PTR. Any of the integer, floating point or string data types listed above can be used with AS PTR PTR appended to create a a pointer to a pointer variable of that data type. Here are two examples:

Syntax: DIM LOCAL a AS INTEGER PTR PTR
  Purpose: Allocates space for a pointer to a pointer to integer

Syntax: DIM STATIC a AS SINGLE PTR PTR
  Purpose: Allocates space for a pointer to a pointer to single floating point number

PTR PTR also can be used in SUB and FUNCTION parameter lists, for example,

  DIM str1$
  
  str1$ = "Hello worlds"
  
  DIM pstr1 AS CHAR PTR
  
  pstr1 = str1$
  
  CALL Increment(&pstr1) 
  
  PRINT pstr1$
  
  SUB Increment(ppstr1 AS CHAR PTR PTR)
   ++*ppstr1    
  END SUB

Result:

 ello worlds

REDIM statement

Purpose: Dynamically declared arrays and string variables can be cleared and resized, increasing or decreasing an array's size, using the REDIM statement.

 REDIM ArrayTypeX[Index]

Remarks:

When REDIM is used, the values in the array or string variable are not preserved because a new array is created.

☞ Although the number of elements in a dimension can be altered, the number of dimensions can not be changed, for example, a two dimensional array can not be changed to a three dimensional array with REDIM.

Also, here is a warning to remember that when REDIM is used to resize a global variable in a function or subroutine, the initial declaration code must physically precede the code where REDIM is used. For example,

This is valid

 SUB YaGood1()
  GLOBAL DYNAMIC Buffer$[100]
 END SUB

 SUB YaGood2
  REDIM Buffer$[200]
 END SUB

while this is not valid.

 SUB NoGood1()
  REDIM Buffer$[200]
 END SUB

 SUB NoGood2
  GLOBAL DYNAMIC Buffer$[100]
 END SUB

Here are two console mode samples.

The first example resizes a dynamic string.

 DIM A$ * 14
 A$ = "Hello, World!"
 PRINT A$

 REDIM A$ * 26
 A$ = REPEAT$(25,"A")
 PRINT A$
 FREE A$

Result:

 Hello, World!
 AAAAAAAAAAAAAAAAAAAAAAAAA

This example resizes a single dimension array.

 DIM DYNAMIC A$[10]
 REDIM       A$[20]
 A$[19] = "Hello"
 PRINT A$[19]

Result:

 Hello

REDIM PRESERVE statement

Dynamically declared variables and arrays can be resized, increasing or decreasing the size of a dimension, with the contents of the object unchanged using the REDIM PRESERVE statement.

 REDIM PRESERVE DynaString$ * Length%

 REDIM PRESERVE ArrayX[Index]

 REDIM PRESERVE Array[Index1, Index2, Index3, Index4] AS data type

Remarks:

When REDIM PRESERVE is used, the values in the string or array variable are preserved up to the lesser of the new and old sizes.

☞ Although the size of a dimension can be altered, the number of dimensions can not be changed, for example, a two dimensional array can not be changed to a three dimensional array with REDIM PRESERVE.

REDIM PRESERVE supports all data types in both single and multiple dimension arrays.

Example 1: shows that data is preserved after REDIM PRESERVE has been applied to an array.

 TYPE Foo
   A$
   B$
 END TYPE
 
 DIM DYNAMIC myfoo[3] AS Foo
 
 myfoo[2].A$ = "This is our initial data"
 myfoo[2].B$ = "prior to REDIM and is preserved."
 
 REDIM PRESERVE myfoo[9]
 
 myfoo[8].A$ = "This data has been added "
 myfoo[8].B$ = "after REDIM has been applied to the array."
 
 PRINT myfoo[2].A$
 PRINT myfoo[2].B$
 PRINT
 PRINT myfoo[8].A$
 PRINT myfoo[8].B$
 

Result:

 This is our initial data
 prior to REDIM and is preserved.

 This data has been added
 after REDIM has been applied to the array.

Example 2: This example resizes a dynamic string.

 DIM b$ * 11
 b$ = "1234567890"
 ?  b$
 REDIM b$ * 15
 b$ = b$ & "ABCD"
 ?  b$
 REDIM PRESERVE b$ * 21
 b$ = b$ & "EFGHIJKLMNOPQRST"
 ?  b$

Result:

 1234567890
 ABCD
 ABCDEFGHIJKLMNOPQRST

Example 3: This example resizes a single dimension array.

 DIM DYNAMIC a$[4]
 
 a$[0] = "This"
 a$[1] = "is"
 a$[2] = "a"
 a$[3] = "test"
 
 ? "Initial values"
 ? "a$[0] = ", a$[0]
 ? "a$[1] = ", a$[1]
 ? "a$[2] = ", a$[2]
 ? "a$[3] = ", a$[3]
 
 REDIM PRESERVE a$[6]
 
 a$[4] = "that shows the above"
 a$[5] = "contents preserved."
 
 ? "After REDIM PRESERVE"
 ? "a$[0] = ", a$[0]
 ? "a$[1] = ", a$[1]
 ? "a$[2] = ", a$[2]
 ? "a$[3] = ", a$[3]
 ? "a$[4] = ", a$[4]
 ? "a$[5] = ", a$[5]
 
 REDIM a$[10]
 
 a$[6] = "the contents above"
 a$[7] = "are not preserved."
 
 ? "After REDIM"
 ? "a$[0] = ", a$[0]
 ? "a$[1] = ", a$[1]
 ? "a$[2] = ", a$[2]
 ? "a$[3] = ", a$[3]
 ? "a$[4] = ", a$[4]
 ? "a$[5] = ", a$[5]
 ? "a$[6] = ", a$[6]
 ? "a$[7] = ", a$[7]

Result:

 Initial values
 a$[0] = This
 a$[1] = is
 a$[2] = a
 a$[3] = test
 After REDIM PRESERVE
 a$[0] = This
 a$[1] = is
 a$[2] = a
 a$[3] = test
 a$[4] = that shows the above
 a$[5] = contents preserved.
 After REDIM
 a$[0] =
 a$[1] =
 a$[2] =
 a$[3] =
 a$[4] =
 a$[5] =
 a$[6] = the contents above
 a$[7] = are not preserved.

Example 4: This example resizes a multiple dimension array.

 GLOBAL DYNAMIC a[6,7,4,4] AS INTEGER

 a[0,0,0,0] = 4
 a[1,1,0,0] = 1
 a[2,2,1,0] = 3
 a[3,3,0,0] = 2

 ? a[0,0,0,0] 
 ? a[1,1,0,0]
 ? a[2,2,1,0]
 ? a[3,3,0,0]

 REDIM PRESERVE a[7,7,4,4] AS INTEGER
 ? a[0,0,0,0]
 ? a[1,1,0,0]
 ? a[2,2,1,0]
 ? a[3,3,0,0]

 REDIM a[5,5,4,4] AS INTEGER
 ? a[0,0,0,0]
 ? a[1,1,0,0]
 ? a[2,2,1,0]
 ? a[3,3,0,0]

 PAUSE

Result:

 4
 1
 3
 2
 4
 1
 3
 2
 0
 0
 0
 0

$GENFREE directive

To free all global variables place the $GENFREE directive at the beginning of the program then CALL FREEGLOBALS from the point at which the global variables are to be freed.

Here is a complete example.

 $GENFREE
 
 GLOBAL DYNAMIC aa$[100] AS CHAR
 DIM DYNAMIC bb$[100] AS CHAR
 aa$ = REPEAT$(20, "aa$") 
 bb$ = REPEAT$(20, "bb$") 
 
 PRINT "Before FREEGLOBALS"
 PRINT "aa$ = ", aa$
 PRINT "bb$ = ", bb$
 
 CALL x()
  
 CALL FREEGLOBALS
 
 PRINT " "
 PRINT "After FREEGLOBALS"
 PRINT "aa$ = ", aa$
 PRINT "bb$ = ", bb$
 PRINT "cc$ = ", dd$
 PRINT "dd$ = ", dd$ 
 
 SUB x()
   GLOBAL DYNAMIC cc$[100] AS CHAR
   GLOBAL dd$ * 100
   cc$ = REPEAT$(20, "cc$") 
   dd$ = REPEAT$(20, "dd$")
   PRINT "cc$ = ", cc$
   PRINT "dd$ = ", dd$   
 END SUB

Result:

 Before FREEGLOBALS
 aa$ = aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$aa$
 bb$ = bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$bb$
 cc$ = cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$cc$
 dd$ = dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$dd$

 After FREEGLOBALS
 aa$ = (null)
 bb$ = (null)
 cc$ = (null)
 dd$ = (null)

$TYPEDEF directive

 $TYPEDEF <simple one line C/C++ typedef> 

 $TYPEDEF long(CALLBACK *CPP_FARPROC)(char *)

 typedef long(CALLBACK *CPP_FARPROC)(char *);

User Defined Type (UDT)

BCX supports individual and arrays of User Defined Types.

It is important to remember, when declaring a string within a UDT, that BCX uses C strings which are terminated with a single byte NULL terminator character to mark the end of the string. All BCX strings must be sized large enough to include this terminator. For example, if a string contains 15 characters then it must be sized to at least 16 bytes.

A SUB can be included in a UDT, as can a FUNCTION, however, OVERLOADED or OPTIONAL FUNCTION or SUB procedures are NOT allowed in a user defined type structure.

 TYPE FOO 
  MyVar
  SUB Process(ME AS Foo_CLASS)
  FUNCTION Calc(ME AS Foo_CLASS, Arg AS DOUBLE) AS DOUBLE
 END TYPE

BCX automatically creates a structure pointer by prepending *LP to the name of your UDT.
For example, this BCX code,

 TYPE SPC
  self   AS VOID*
  parent AS VOID*
  child  AS VOID*
  daDaTa AS VOID*
  mtbl   AS VOID*
 END TYPE

produces this "C" structure

 typedef struct _SPC
 {
   VOID*  self;
   VOID*  parent;
   VOID*  child;
   VOID*  daDaTa;
   VOID*  mtbl;
 }SPC, *LPSPC;

Example 1:

 TYPE MYBOX
   Top%
   Left%
   Width%
   Height%
   Fill AS BOOL
 END TYPE
 
 DIM abc AS MYBOX
 
 abc.Top%     = 100
 abc.Left%    = 300
 abc.Width%   = 100
 abc.Height%  = 100
 abc.Fill     = TRUE
 
 PRINT abc.Top%
 PRINT abc.Left%
 PRINT abc.Width%
 PRINT abc.Height%
 PRINT abc.Fill

Result:

 100
 300
 100
 100
 1

Example 2:

 TYPE MYREC
  B$ [2083] AS CHAR
 END TYPE

 DIM Test AS MYREC
 DIM A$ * 2083

 A$ = "test string"
 Test.B$ = "Next"

 PRINT A$
 PRINT Test.B$

Result:

 test string
 Next

Example 3: Here is a short example in which a user defined type is used to return multiple values from a FUNCTION.

 TYPE test
  a$[5] AS CHAR
  b$[5] AS CHAR
 END TYPE

 DIM x$

 DIM v AS test

 x$ = "ABC and XYZ"

 v = dfunc(x$)
 PRINT v.a$
 PRINT v.b$

 FUNCTION dfunc(d$) AS test
  LOCAL f AS test
  f.a$ = LEFT$(d$,3)
  f.b$ = RIGHT$(d$,3)
  FUNCTION = f
 END FUNCTION

Result:

 ABC
 XYZ

Example 4: Here is a more complex program showing off multi-dimensional user defined type.

 TYPE QWERTY
   DIM a
   DIM b!
   DIM c$[80] AS CHAR
   DIM q AS RECT
 END TYPE
 
 GLOBAL MyType [10,10,10] AS QWERTY
 
 MyType [2,3,4].a   =  1
 MyType [2,3,4].b!  =  2.345
 MyType [2,3,4].c$  = "hello world from a poly-dimensional udt!"
 
 PRINT         MyType[2,3,4].a
 PRINT         MyType[2,3,4].b!
 PRINT UCASE$(MyType[2,3,4].c$)

Result:

  1
  2.345
 HELLO WORLD FROM A POLY-DIMENSIONAL UDT!

Example 5: Using the WITH ... END WITH control flow statement, the multi-dimensional user defined types Example 4 above can be written as follows.

 TYPE QWERTY
 DIM a
 DIM b!
 DIM c$ [80] AS CHAR
 DIM q AS RECT
 END TYPE

 GLOBAL MyType [10,10,10] AS QWERTY

 WITH MyType[2,3,4]
  .a = 1
  .b! = 2.345
  .c$ = "hello world from a poly-dimensional udt!"
  PRINT .a
  PRINT .b!
  PRINT UCASE$(.c$)
 END WITH
 

Result:

  1
  2.345
 HELLO WORLD FROM A POLY-DIMENSIONAL UDT!

Example 6: Here is an example demonstrating dynamic memory allocation of the members in a user defined type.

 TYPE NODE_TYP
   id AS INTEGER 'element number
   name$[32] AS CHAR 'Storage area
   A1 AS CHAR PTR    'Storage area determined at run-time
   A2 AS CHAR PTR    'Storage area determined at run-time
   A3 AS CHAR PTR    'Storage area determined at run-time
   next_node AS NODE_TYP PTR
   previous_node AS NODE_TYP PTR
 END TYPE

 DIM F AS NODE_TYP
 DIM X AS NODE_TYP PTR
 
 CALL AllocateStringSpace(&F, 100, 1000, 10000)
 F.A1 = "this holds 99"
 F.A2 = "this holds 999"
 F.A3 = "this holds 9999"
 ? F.A1$
 ? F.A2$
 ? F.A3$

 F.next_node = AllocateNode()
 X = F.next_node
 CALL AllocateStringSpace(X, 1000, 2000, 80000)
 X->A1 = "this holds 999"
 X->A2 = "this holds 1999"
 X->A3 = "this holds 79999"
 ? X->A1$
 ? X->A2$
 ? X->A3$

 PAUSE

 SUB AllocateStringSpace(Node AS NODE_TYP PTR, _
                             A1Length AS LONG, _
                             A2Length AS LONG, _
                             A3Length AS LONG)
  !Node->A1 = calloc(1,A1Length);
  !Node->A2 = calloc(1,A2Length);
  !Node->A3 = calloc(1,A3Length);
 END SUB

 FUNCTION AllocateNode() AS NODE_TYP PTR
  !RETURN calloc(1,SIZEOF(NODE_TYP));
 END FUNCTION

Result:

 this holds 99
 this holds 999
 this holds 9999
 this holds 999
 this holds 1999
 this holds 79999

Example 7: Like Example 6, this example also demonstrates dynamic memory allocation of the members in a user defined type. The syntax in this example is much simpler because of new code introduced in BCX version 5.12 to allow the use of the DYNAMIC type qualifier a with member of a user defined type.

 TYPE NODE_TYP
  id AS INTEGER 'element number
  name$[32] AS CHAR 'Storage area
  DYNAMIC A1$ 'Storage area determined at run-time
  DYNAMIC A2$ 'Storage area determined at run-time
  DYNAMIC A3$ 'Storage area determined at run-time
  DYNAMIC next_node[] AS NODE_TYP
  DYNAMIC prev_node[] AS NODE_TYP
 END TYPE
 
 DIM F AS NODE_TYP
 DIM X AS NODE_TYP PTR
 
 REDIM F.A1$ * 100
 REDIM F.A2$ * 1000
 REDIM F.A3$ * 10000
 
 F.A1$ = "this holds 99"
 F.A2$ = "this holds 999"
 F.A3$ = "this holds 9999"
 ? F.A1$
 ? F.A2$
 ? F.A3$
 
 REDIM F.next_node[1]
 X = &F.next_node[0]
 
 REDIM X->A1$ * 1000
 REDIM X->A2$ * 2000
 REDIM X->A3$ * 80000
 
 X->A1$ = "this holds 999" 
 X->A2$ = "this holds 1999"
 X->A3$ = "this holds 79999" 
 
 ? X->A1$
 ? X->A2$
 ? X->A3$
 
 PAUSE
 

Result:

 this holds 99
 this holds 999
 this holds 9999
 this holds 999
 this holds 1999
 this holds 79999

Example 8: How to REDIM a dynamic array inside a user defined type.

 TYPE First
  a$
  b%
 END TYPE

 TYPE Second
  c%
  DIM Something AS First PTR
 END TYPE

 DIM i
 
 DIM DYNAMIC Third[0] AS Second 'need an array size [0] will do
 
 REDIM Third[6]
 
 Third[0].Something = calloc(10,SIZEOF(First))
 FOR i = 0 TO 9
  Third[0].Something[i].b% = i
  Third[0].Something[i].a$ = "this" + STR$(i)
 NEXT
 FOR i = 0 TO 9
  ? Third[0].Something[i].b%
  ? Third[0].Something[i].a$
 NEXT
 
 PAUSE

Result:

  0
 this 0
  1
 this 1
  2
 this 2
  3
 this 3
  4
 this 4
  5
 this 5
  6
 this 6
  7
 this 7
  8
 this 8
  9
 this 9

Example 9: Like Example 8, this example also demonstrates how to REDIM a dynamic array inside a user defined type. The syntax in this example is much simpler because of new code introduced in BCX version 5.12 to allow the use of the DYNAMIC type qualifier a with member of a user defined type.

 TYPE First
   a$
   b%
 END TYPE
 
 TYPE Second
   c%
   DYNAMIC Something[] AS First 
 END TYPE
 
 DIM DYNAMIC Third[6] AS Second 
 DIM i, ii
 
 FOR ii = 0 TO 5
   REDIM Third[ii].Something[10]
   FOR i = 0 TO 9
     Third[ii].Something[i].b% = i
     Third[ii].Something[i].a$ = "this is Something" + _
                                             STR$(i) + _
                                         " of Third" + _
                                             STR$(ii)
   NEXT
 NEXT
 
 FOR ii = 0 TO 5
   FOR i = 0 TO 9
     ? Third[ii].Something[i].b%
     ? Third[ii].Something[i].a$
   NEXT
 NEXT
 
 FOR ii = 0 TO 5
   FREE Third[ii].Something
 NEXT
 
 FREE Third
 
 PAUSE

Result:

  0
 this is Something 0 of Third 0
  1
 this is Something 1 of Third 0
  2
 this is Something 2 of Third 0
  3
 this is Something 3 of Third 0
  4
 this is Something 4 of Third 0
  5
 this is Something 5 of Third 0
  6
 this is Something 6 of Third 0
  7
 this is Something 7 of Third 0
  8
 this is Something 8 of Third 0
  9
 this is Something 9 of Third 0
  0
 this is Something 0 of Third 1
  1
 this is Something 1 of Third 1
  2
 this is Something 2 of Third 1
  3
 this is Something 3 of Third 1
  4
 this is Something 4 of Third 1
  5
 this is Something 5 of Third 1
  6
 this is Something 6 of Third 1
  7
 this is Something 7 of Third 1
  8
 this is Something 8 of Third 1
  9
 this is Something 9 of Third 1
  0
 this is Something 0 of Third 2
  1
 this is Something 1 of Third 2
  2
 this is Something 2 of Third 2
  3
 this is Something 3 of Third 2
  4
 this is Something 4 of Third 2
  5
 this is Something 5 of Third 2
  6
 this is Something 6 of Third 2
  7
 this is Something 7 of Third 2
  8
 this is Something 8 of Third 2
  9
 this is Something 9 of Third 2
  0
 this is Something 0 of Third 3
  1
 this is Something 1 of Third 3
  2
 this is Something 2 of Third 3
  3
 this is Something 3 of Third 3
  4
 this is Something 4 of Third 3
  5
 this is Something 5 of Third 3
  6
 this is Something 6 of Third 3
  7
 this is Something 7 of Third 3
  8
 this is Something 8 of Third 3
  9
 this is Something 9 of Third 3
  0
 this is Something 0 of Third 4
  1
 this is Something 1 of Third 4
  2
 this is Something 2 of Third 4
  3
 this is Something 3 of Third 4
  4
 this is Something 4 of Third 4
  5
 this is Something 5 of Third 4
  6
 this is Something 6 of Third 4
  7
 this is Something 7 of Third 4
  8
 this is Something 8 of Third 4
  9
 this is Something 9 of Third 4
  0
 this is Something 0 of Third 5
  1
 this is Something 1 of Third 5
  2
 this is Something 2 of Third 5
  3
 this is Something 3 of Third 5
  4
 this is Something 4 of Third 5
  5
 this is Something 5 of Third 5
  6
 this is Something 6 of Third 5
  7
 this is Something 7 of Third 5
  8
 this is Something 8 of Third 5
  9
 this is Something 9 of Third 5

UNION ... END UNION statement

A UNION is similiar to a User Defined Type(UDT) but a UNION can hold the value of only one of its members at any one time but the active member can be changed at runtime and the UNION will then hold the value of the active member. The total size of a UNION is the size of the data type of its largest member.

In the sample below, you might think that the size of the UNION Foo would be 4 + 2048 + 4, counting the integer, the string and the single members of the UNION Foo, but that is not the case. The size of the UNION Foo will be the size of the largest member, that is, the string b$, which has a size of 2048 bytes.

 UNION Foo
   a  AS INTEGER
   b$
   c  AS SINGLE
 END UNION
 
 DIM Bloof AS Foo
  
 Bloof.a  = 1               
 PRINT Bloof.a
 
 Bloof.b$ = "Hello, World!" 
 PRINT Bloof.b$
 
 PRINT Bloof.a
 
 Bloof.c! = 3.14159         
 PRINT Bloof.c!

Result:

 1
 Hello, World!
 1819043144
 3.14159

The result above shows that a UNION can hold the value of only one of its members at any one time. After Bloof.b$ has been been made the active member of the UNION, and assigned a string "Hello World", the original value of 1 assigned to the UNION member Bloof.a is no longer valid. The value, 1819043144, that PRINT Bloof.a then produces is a 32 bit integer representing, in little endian order, the first 4 bytes of the string "Hello World".

 
 1819043144 = 0x6C6C6548 Hex

 6C = ASCII l
 6C = ASCII l
 65 = ASCII e
 48 = ASCII H

Here's another example. If you create a union like this:

 UNION Blurf
  A$
  B$
  C$
 END UNION

 DIM Quarf AS Blurf

you might think that the size of Quarf would be 3 x 2048 bytes but, in fact, it is only 1 x 2048 bytes, since a UNION can hold only one value at a time.

A UNION can hold any type of data, even other UNION or user defined types.

Example: TYPE and UNION can be nested as in the following program.

 TYPE BE_CONFIG
   dwConfig AS DWORD
   UNION format
     TYPE mp3
       dwSampleRate AS DWORD
       byMode AS BYTE
       wBitrate AS WORD
       bPrivate AS BOOL
       bCRC AS BOOL
       bCopyright AS BOOL
       bOriginal AS BOOL
     END TYPE
     TYPE aac
       dwSampleRate AS DWORD
       byMode AS BYTE
       wBitrate AS WORD
       byEncodingMethod AS BYTE
     END TYPE
   END UNION
 END TYPE
 
 DIM T AS BE_CONFIG
 
 T.format.mp3.byMode = 1
 T.format.mp3.bPrivate = 2
  
 T.format.aac.byEncodingMethod = 3
 T.format.aac.dwSampleRate = 44100
 
 PRINT T.format.mp3.byMode
 PRINT T.format.mp3.bPrivate
  
 PRINT T.format.aac.byEncodingMethod
 PRINT T.format.aac.dwSampleRate

Result:

 1
 3
 3
 44100