DIM (string array)

Dimension String Array

This directive defines a string array of up to 3 dimensions, allowing for an initial length setting and preset value.

Syntax

DIM array-name[ elem1 [, elem2 [, elem3]]] [(length [,init-value])]
[array-name[ elem1 [, elem2 [, elem3]]] [(length [,init-value])]...]

array-name: is any string variable name.
elem1,2,3: is an index specifying the size of the dimension.
length: is an integer in the range of 0 to 65000 specifying the initial number of characters assigned for each string. The default is 0.
init-value: is any string whose first character is used as the character that fills each string in the array as a default. If this value is omitted but length is specified, the default is the space character.

Remarks

The syntax for elem1,2,3 is:

[low-index:] high-index

low-index: is a signed integer specifying the lower bound of each range. This option is generally available starting with release level 8.1B2. Prior release levels do not have this option and use a lower bound of zero (0).
high-index: is a signed integer specifying the higher bound of each range.

If the low index is not specified, then the default for starting the array element is 0.

The low index and the high index can be negative integers provided that the range does not exceed 65000.

If the low index has a greater value than the high index, an ERR=41 results.

65000 is the maximum number of total entries in the string array as well as the maximum number of any individual dimension.

If elem1,2,3 were 5, 10, and 15 respectively, this array has 6 occurrences in the first dimension, 11 in the second, and 16 in the third for a total of 1056 elements.

Entering a space between array-name and the left bracket ([) is not valid.

LONGVAR mode must be set when this directive is entered into a program (see LONGVAR).

Memory space used to store any string may be released by redimensioning it to 0 with the DIM directive for string arrays.

More than one variable may be dimensioned in a statement if the variables are separated by commas.

If you use the CALL directive to call a public program that will permanently change the value of an array element, you must pass the entire array to the called program. Array elements are passed by value, so any changes to the element will not be reflected in the calling program. For more information and an example, please refer to the description of the CALL directive.

Examples

DIM SALES_ARRAY$[ REGIONS, STATES, PEOPLE]

for REGIONS = 4, STATES = 20, and PEOPLE = 28, could be used to define a string array to hold the names of the sales people to be referenced by state number within region for region-specific and state-specific mailings. Remember that the actual string array has 5 occurrences in the first dimension (0 - 4), 21 in the second (0 - 20), and 29 in the third (0 -

for a total of 3045 elements.

DIM SALES_ARRAY$ (0)

has no effect on the string array defined by the previous example.

DIM SALES_ARRAY$[ 0 ]

clears the string array defined in the first example above.

DIM TABLE_NAME$[ MAKE, MODEL ] (20,"*")

defines a string array of two dimensions and presets each of the 20-character strings to asterisks so that, if this table were printed in a two dimensional format, those entries which had not been updated or changed prints as asterisks.

DIM SALES_ARRAY$[4:10] (10,*)

yields a single dimension string array of 7 elements with 4 as the lowest index.

DIM (string array)

Syntax

Remarks

Examples

See also