Futurebasic/Language/Reference/xref

From Wikibooks, open books for an open world
Jump to navigation Jump to search

XREF[edit | edit source]

Syntax[edit | edit source]

XREF arrayName maxSub1 maxSub2 AS dataType

Description[edit | edit source]

The XREF statement declares an array, and associates the array with the memory pointed to by a particular long-integer variable, called the "link variable." You can use XREF to cause any arbitrary block of memory to be treated as an array. This is especially useful when you need to dynamically create an array whose size can't be determined until runtime, or when you want to impose an array structure on data that was created outside of your FB program.

The link variable must be a simple (non-array, non-field) long-integer variable which has the same name as the array (ignoring any type-identifier suffix). For example, if you specify the following:

XREF diameter#(3,7)

The compiler creates a long-integer variable called diameter&. When you run the program, you should set diameter& equal to some appropriate memory address (you do this after the XREF statement); FB then assumes that the diameter#() array begins at that address. When you examine elements in the array, they are retrieved from the memory pointed to by diameter&. When you alter elements in the array, the memory pointed to by diameter& is altered.

The first subscript is arbitrary
The maxSub1, maxSub2 etc. values must be positive static integer expressions. However, since XREF does not actually allocate any memory, the declared subscripts are used somewhat differently than in a DIM statement. The second and subsequent subscripts (if any) determine the internal structure of the array, and they should exactly match the internal layout of the elements pointed to by the link variable. But the value of the first subscript (maxSub1) is basically ignored, and may be arbitrarily set to any value greater than zero. When you actually reference the array elements, you can use subscript values that are larger than maxSub1, as long as they reference valid elements within the block of memory pointed to by the link variable.

Notes[edit | edit source]

XREF is a non-executable statement, so you can't change its effect by putting it inside a conditional-execution structure such as LONG IF...END IF. However, you can conditionally include it or exclude it from the program by putting it inside a COMPILE LONG IF...COMPILE END IF block. The XREF statement should appear somewhere above the first line where the array is referenced.

XREFs will not behave properly when used with handles.

XREF myHandleList(100) AS HANDLE : REM will not work!

See Also[edit | edit source]

DIM; XREF