LOCAL DIM

The LOCAL DIM statement is used to define local variables within the scope of a subroutine defined with the DEFSUB' statement. When control returns to the caller on the RETURN the various LOCAL DIM variables of that function will be destroyed and their space recovered.

By default numeric local variables are initialized to 0, strings are initialized to blank and objects are initialized to NULL. Like DIM and COM, string and numeric scalar variables can be explicitely initialized by specifying an expression after an equals sign, for example

LOCAL DIM Value = 10
LOCAL DIM AlphaValue$ = "Hello!"

Note that the syntax only supports the explicit initialization of numerics and basic strings. Arrays and field variables cannot be initialized in this way. OBJECT variables can only be redundantly initialized to NULL.

If a string is explicitly initialized without specifying a type or length then the space allocated for the string will be exactly enough to hold the initializing expression. Thus in this example

LOCAL DIM a$ = "Hello"
LOCAL DIM nBufSize = 12
LOCAL DIM b$nBufSize = "Hello"

the a$ string will be sized to 5 bytes whereas the b$ string will get the specifified 12 bytes and the trailing 7 bytes will space filled.

The space allocation of an unitialized string is deferred until the string is first referenced and then it will be initialized only if used as an expression (lvalue) rather than as a receiver.

Variables defined with LOCAL DIM can be resized with the MAT REDIM statement and with the REDIM qualifier in an assignment. Scalar string variables have their space allocation deferred until they are used in order to avoid unnecessary initialization if that first reference is a REDIM asignment as in the 'tagit() example below. The space requested there is an explicit zero to make it clear to the reader that the variable may not be used without REDIMing

The BYREF keyword can be used to establish a reference variable that actually refers to the variable to which it is initialized. That variable could be another string scalar variable of the same type or more likely it will be the result of some SYM(*)$ operation. Whenever KCML refers to the local reference variable inside this routine it will actually be using the string allocated for that variable. Reference variable are only allowed for scalar strings and they must be typed as consistent records. For example:

// some row buffer
DEFRECORD MyRow
   FLD f1	// some number field
   ...
END RECORD
// context we pass around including the row buffer
DEFRECORD MyContext
   FLD r = SYM(X$_MyRow)	// row buffer
   ...
END RECORD
DIM z$_MyRow, s$_MyContext
'_Init_MyRow(BYREF z$)
'_Init_MyContext(BYREF s$)
// pass the row buffer in the context
FLD(s$.r) = SYM(z$)
// update
'update(SYM(s$))
...
DEFSUB 'update(ps AS SYM(X$_MyContext))
   // make a reference variable for the row byffer
   LOCAL DIM BYREF a$_MyRow = SYM(*FLD(SYM(*ps)$.r))$
   FLD(a$.f1) = 5
END SUB

This example shows building a potentially complex context as a single structure then passing it to functions which can use a local reference variable to refer to its components row with a simple shorthand rather than as a complex SYM(*) expression greatly clarifying the code. Passing context this way reduces the number of subroutine arguments.

Syntax examples:

DEFSUB 'new$(number, size, data$())
   LOCAL DIM record$(number)_somerec
   LOCAL DIM OBJECT parser
   LOCAL DIM nCount = 0
    ... 
   RETURN size$
END SUB
DEFSUB 'tagit$(tag$)
   LOCAL DIM x$0
   REDIM x$ = "<" & tag$ & ">"
   RETURN x$
END SUB

See also:

DEFSUB'
REDIM