DIM

Related Commands

CLEAR
SET

Syntax:

       Then: DIM array[n]

Defines an array of "n" fields.

Version Ref:  3.x

Description:

DIM (dimension) defines arrays for use in repetitive operations and with MENU (see the MENU command for details). You can also use DIM to match an array to a list of real, dummy, or lookup fields.

Mapping array fields to real fields is another way to give fields aliases. It is also a way to override the real fields' types and lengths with arrays, you can create fields with more than one length and edit within a single file.

IMPORTANT:  In the below examples note that the brackets [ ] can be used only for the number of array elements where as parentheses ( ) must be used for the length and edit of the array.  DIM array[n](l,e)

Examples:

Then: DIM cats[5]

Dimensions (or builds) an array of 5 elements called "cats". The five array elements are referred to as cats["1"], cats["2"], cats["3"], cats["4"] and cats["5"]. They can also be referred to as cats[n] as long as n has a value between 1 and 5. For any size array (any number of elements), the subscript value [n] can NOT be less than or equal to 0 and can not be higher than the highest element number. If this happens, a fatal error will occur and the processing table will exit you from the program with the error message "array index out of range."

IMPORTANT: A non-literal number is used to actually dimension an array. In the example shown above, the number 5 in DIM cats[5] does NOT mean the contents of field 5. This is the only place throughout all of filePro where a 5 not surrounded by quotes does not mean the contents of field 5. Be very aware of this, as it will cause you great difficulty if you use this index subscript improperly. After an array is defined (the actual DIM statement itself), you should never use a non-quoted number as a subscript for that array. You should always use a literal or a dummy field. If you use a number not surrounded by quotes, filePro will use the value found in that field and substitute it for the array index, and it had better be within the boundaries of the array size or you will be dumped out of the processing table. There are rare, very rare times when you might want to use a real field as the subscript of an array. Just be aware of how this will work if you do ever do it.

The fact that the subscript (or index) of the array can be an expression is the feature which makes arrays so valuable. You can start a variable equal to "1" and use it as the index, do something with that element of the array, increment the variable by "1" and do something to or with the next element of the array. You can repeat this loop for as many elements as there are in the array, being careful not to go past the highest element number. Looping through arrays in this fashion is a powerful programming construct that you will use often to reduce the number of lines of code you must write.

Other DIM formats

Then:  DIM array[n](l,e)

Array of "n" fields with length "l" & edit "e"

Examples:

Then: DIM prods[3](5,.2)

Array of 3 fields, making them all 5-character, two-decimal-place numbers.

Then: DIM array((l,e)(l,e)... )

Array with fields each having individual length "l" and individual edit type "e". Has as many terms as you specify.

Example:

       Then: dim fred((8,.2) (1,yesno) (8,mdy/ ))

The example above creates a three-field array, the first of which is an eight-digit decimal number, the second of which is a one-character "yesno" field, and the third of which is an eight character date field.

NOTE: When you use this option, you may run out of space on a line before you come to the end of your assignments. You can continue from line to line, however, by breaking the line of assignments between sets of parentheses, and by making sure that you don't add the final outside parenthesis until you're done with the list:

       Then:  DIM ants((10,*)(5,sex)(8,mdy/)

Then: (12,*) (8,mdy/) (20,allup) )

Then:  DIM address((30,uplow)(30,uplow)(15,uplow)(2,state)(5,zip))

Then: DIM array[n]:m

Array of n fields starts with its field 1 at the file's field number "m".

       Then: dim items[10]:44

The code shown above builds a ten-element array that starts at field 44 of the current file (the file in which the processing resides). This means that the array elements "overlay" or are congruent with fields 44 through 53. Referring to or assigning to field 45 is the very same thing as referring to or assigning to items["2"]. Field 47 is equivalent to items["4"], etc.

DIM array[n]:lookup(m)

Maps to (overlay) a looked-up file's fields.

Then: dim phones[4]:CLIENTS(3)

A 4-field array taken from a lookup named CLIENTS starting at field 3 in CLIENTS. The elements (fields) of this array would coincide with fields 3 through 6 of the CLIENTS file. Changing any of the fields in this array will change the coinciding field in the CLIENTS file.

The following statement would change field 5 in the CLIENTS file to this phone number.

     Then: phone["3"]="(201) 427-3311"

Commands used with Arrays

clear array

Sets each element of "array" to blank.

      Then: clear phones <- clears the array named "phones".

v6.1 ( 6.0.02 USP )

EXTERN and GLOBAL arrays

DIM GLOBAL name(size)

DIM EXTERN name

Only non-aliased arrays can be declared GLOBAL/EXTERN. Functions similar to GLOBAL/EXTERN longvars.

v6.1 ( 6.0.02 USP )

Added new array size function to get the size of an array. Can be used with GLOBAL, EXTERN, LOCAL, and SYSTEM arrays.

x=ARRAYSIZE(array)

Where array is the name of the array.

Where x is the returned size of the passed array.

v6.1 ( 6.1.01 USP )

Added initial support for multi-dimensional arrays.

DIM array[n1,n2,...,n8](l,e)

Multi-Dimensional array of fields with length "l" & edit "e". Array edit is optional.

Example:

Existing array functions can also use multi-dimensional arrays by referencing one of an array's sub arrays.

Example: