Synopsis: 

       result=array_dim(array_name,dim0[,dim1,dim2..],size)

Arguments:

       array_name - The name of the array

       dim0 - The size of the first dimension of the array

       [dim1] - Optional size of second array dimension

       [dim2] - Optional size of the third array dimension

       .. ETC

       size - Size of the string element of the array

Description:   This function allows for a multi-dimensional array (with the name array_name) to be created where the dimensions are specified by dim0, dim1, dim2... etc.    The size argument defines the size of the string for the array elements.

The array_name can be up to 32 characters long and is used to reference the array in the other array function calls such as array_set(), array_get() etc.

Arrays of any number of dimensions can be defined by specifying more dimension parameters in the dim0, dim1, dim2... etc list.

Below is an example of a one dimensional array:

       // Creates a one dimensional array for resource management (element string length =1)

       x=array_dim("RESOURCE_ARRAY",1024,1);

       // Set an element of this array to 1 to mark the resource as "in-use"

       array_set("RESOURCE_ARRAY",0,"1");

Below is an example of a two dimesional array:

       // Create an array to hold data for a text screen console (25 rows x 80 cols)

       x=array_dim("SCREEN1",25,80,1);

       // Set the characters of the top line of the screen array to "_"

       for(i=0;i<80;i++)        

               array_set("SCREEN1",0,i,"_");

       endfor

Below is an example of a three dimensional array

       // Create an array to hold 3d co-ordinate space (100x100x100)

       x=array_dim("3DSPACE",100,100,100,1);

       // Set co-ordinate (10,20,5) to 1

       array_set("3DSPACE",10,20,5,"1");

Returns:    Returns 0 if successful or -1 if the array failed to be allocated (E.g. out of memory error)