SYM(

General Forms:

The first form of the SYM( function is used to extract the index of a KCML string, numeric, field variable or array, or the index of a KCML subroutine. The index is returned as a unique number identifying the variable or subroutine, which can be used with the second form to recall the values or access the subroutine. The index number is valid only for the current program and may become invalid if a LOAD operation occurs. However the SYM of a common variable will be preserved across a LOAD and as of KCML 6.20 the SYM of a library subroutine will also be persisted. The index value returned is encoded in such a way that the Workbench can recognise SYM values and dereference them in tooltips.

The first form of the SYM( function is valid wherever a numeric expression is valid. The second form is valid within an alpha or numeric expression, depending on the variable type returned and everywhere 'subroutine is valid.

See below for some examples and explanations of the different uses for the SYM( function. Refer to the Tutorial for a more detailed explanation of this function.

The following tables show how to obtain and reuse the index of different variable and subroutine types:

Examples of the SYM( function.

Symbol Type	Obtaining the index value	Usage example	Description
Numeric	n=SYM(a)	SYM(n)=100 PRINT SYM(n)	Sets the variable a to 100. Prints the value of a.
Alpha	n=SYM(a$)	SYM(n)$="TEST" PRINT SYM(n)$	Sets the variable a$ to "TEST". Prints the value of a$.
Numeric Field	n=SYM(.a)	.SYM(n)=(4,"##.##") FLD(a$.SYM(n))=100	Sets the field variable .a to start at position 4 with the specified image. Places the value 100 into the variable a$ using the field specification.
Alpha Field	n=SYM(.a$)	.SYM(n)$=(4,10) FLD(a$.SYM(n)$="TEST"	Sets the field variable .a$ to start at position 4 for a length of 10. Places the word TEST into the variable a$ at the position specified by the field specification.
Numeric Array	n=SYM(a())	SYM(n)(1,4)=100 PRINT SYM(n)(1,4)	Sets element 1,4 of the array a() to 100. Prints the value of a(1,4).
Alpha Array	n=SYM(a$())	SYM(n)$(1,4)="TEST" PRINT SYM(n)$(1,4)	Sets element 1,4 of the array a$() to "TEST". Prints the value of a$(1,4).
Numeric Field Array	n=SYM(.a())	.SYM(n)(1,4)=(4,"#.#") FLD(a$.SYM(n)(1,4))=10	Sets element 1,4 of the field variable .a() to start at position 4 for the specified image. Places the value 10 into the variable a$ at the position specified by the field specification held in .a(1,4).
Alpha Field Array	n=SYM(.a$())	.SYM(n)$(1,4)=(4,10) FLD(a$.SYM(n)$(1,4))="TEST"	Sets element 1,4 of the field variable .a$() to start at position 4 for a length of 10. Places the word "TEST" into the variable a$ at the position specified by the field specification held in .a$(1,4).
Numeric Subroutine	n=SYM('sub1)	a= 'SYM(n)(12,"A") 'SYM(n)(12,"A")	Assigns the numeric expression returned from the subroutine 'sub1 to the variable a. The number 12 and the letter A are passed into the subroutine. Branches to the subroutine 'sub1. The number 12 and the letter A are passed into the subroutine.
Alpha Subroutine	n=SYM('sub2$)	a$='SYM(n)$("YZ") 'SYM(n)$("YZ")	Assigns the alpha expression returned from the subroutine 'sub2$ to the variable a$. The string "YZ" is passed into the subroutine. Branches to the subroutine 'sub2$. The string "YZ" is passed into the subroutine.
Object variable	n = SYM(OBJECT a)	OBJECT a = SYM(n) 'myfn(OBJECT SYM(n))	Sets the object variable a to reference the object specified by the variable n Call a subroutine expecting an object parameter

Note that 'SYM(* cannot be used with the ON GOSUB statement.

Example using the SYM( function with variables which avoid copying the huge buffer:

DIM buff$(1000)1000
'get_rec(hd,rec,SYM(buff$()))
...

DEFSUB'get_rec(hd, rec, pointer_sym)
RETURN READ #hd,(rec) SYM(*pointer_sym)$
END SUB

However this example might be more readable if BYREF were used instead.

DIM buf$1000000
'get_rec(hd, rec, BYREF buf$)
...

DEFSUB'get_rec(hd, rec, BYREF buf$)
RETURN READ #hd,(rec) buf$
END SUB

The following contrived but more useful example shows the use of the subroutine form of SYM(:

DIM numbers(10)
MAT READ numbers()
DATA 1,2,3,4,5,6,7,8,9,0
p_odd = SYM('odd)
p_even = SYM('even)
'list_numbers(p_odd, 5)
'list_numbers(p_even, 8)
END

DEFSUB 'list_numbers(pointer, top)
    RETURN 'SYM(*pointer)(top)
END SUB

DEFSUB 'odd(n)
LOCAL DIM loop
FOR loop = 1 TO n/2
     PRINT numbers((loop*2)+1)
NEXT loop
END SUB

DEFSUB 'even(n)
LOCAL DIM loop
FOR loop = 1 TO n/2
     PRINT numbers((loop*2))
NEXT loop
END SUB

In the previous example the subroutine 'list_numbers first uses the 'SYM(* of the subroutine 'odd to produce a list of odd numbers, then next time it is called it uses the 'SYM(* of the subroutine 'even.