Arrays passed to ActiveX methods must be of the safearray type. These arrays are safe because you cannot accidentally assign values outside the array bounds and cause a data exception to occur. Use the vlax-make-safearray function to create a safearray and use vlax-safearray-put-element or vlax-safearray-fill to populate a safearray with data.
The vlax-make-safearray function requires a minimum of two arguments. The first argument identifies the type of data that will be stored in the array. Specify one of the following constants for the data type:
- vlax-vbInteger
- vlax-vbLong
- vlax-vbSingle
- vlax-vbDouble
- vlax-vbString
- vlax-vbObject
- vlax-vbBoolean
- vlax-vbVariant
The constants evaluate to integer values. Because the integer values can change, you should always refer to the constant, not the integer value. See the entry for vlax-make-safearray in the AutoLISP Reference for the current integer value assigned to each constant.
The remaining arguments to vlax-make-safearray specify the upper and lower bounds of each dimension of the array. You can create single or multidimensional arrays with vlax-make-safearray. The lower bound for an index can be zero or any positive or negative integer.
For example, the following function call creates a single-dimension array consisting of doubles, with a starting index of 0:
_$ (setq point (vlax-make-safearray vlax-vbDouble '(0 . 2)))
#<safearray...>
The upper bound specified in this example is 2, so the array will hold three elements (element 0, element 1, and element 2).
Different dimensions can have different bounds. For example, the following function call creates a two-dimension array of strings. The first dimension starts at index 0 and contains two elements, while the second dimension starts at index 1 and contains three elements:
_$ (setq mat2 (vlax-make-safearray
vlax-vbString '(0 . 1) '(1 . 3)))
#<safearray...>
You can use either vlax-safearray-fill or vlax-safearray-put-element to populate arrays with data.
The vlax-safearray-fill function requires two arguments: the variable containing the array you are populating and a list of the values to be assigned to the array elements. You must specify as many values as there are elements in the array. For example, the following code populates a single-dimension array of three doubles:
(vlax-safearray-fill point '(100 100 0))
You can display the contents of this array in list form with the vlax-safear-ray->list function:
_$ (vlax-safearray->list point)
(100.0 100.0 0.0)
If you do not specify a value for every element in the array, vlax-safear-ray-fill results in an error.
To assign values to a multi-dimensional array, specify a list of lists to vlax-safearray-fill, with each list corresponding to a dimension. For example, the following command assigns values to a two-dimension array of strings that contains three elements in each dimension:
_$ (vlax-safearray-fill
mat2 '(("a" "b" "c") ("d" "e" "f")))
#<safearray...>
Use the vlax-safearray->list function to confirm the contents of mat2:
_$ (vlax-safearray->list mat2)
(("a" "b" "c") ("d" "e" "f"))
Using vlax-safearray-put-element
The vlax-safearray-put-element function can be used to assign values to one or more elements of a safearray. The number of arguments required by this function depends on the number of dimensions in the array. The following rules apply to specifying arguments to vlax-safearray-put-element:
- The first argument always names the safearray to which you are assigning a value.
- The next set of arguments identifies index values pointing to the element to which you are assigning a value. For a single-dimension array, specify one index value; for a two-dimension array, specify two index values, and so on.
- The final argument is always the value to be assigned to the safearray element.
For example, the following code populates a single-dimension array of three doubles:
(vlax-safearray-put-element point 0 100)
(vlax-safearray-put-element point 1 100)
(vlax-safearray-put-element point 2 0)
To change the second element of the array to a value of 50, issue the following command:
(vlax-safearray-put-element point 1 50)
The following example populates a two-dimension array of strings. The first dimension of the array starts at index 0, while the second dimension starts at index 1:
(vlax-safearray-put-element mat2 0 1 "a")
(vlax-safearray-put-element mat2 0 2 "b")
(vlax-safearray-put-element mat2 0 3 "c")
(vlax-safearray-put-element mat2 1 1 "d")
(vlax-safearray-put-element mat2 1 2 "e")
(vlax-safearray-put-element mat2 1 3 "f")
You can use vlax-safearray->list to confirm the contents of the array:
_$ (vlax-safearray->list mat2)
(("a" "b" "c") ("d" "e" "f"))