Dynamic Arrays

A 'dynamic array' is a multi-element string variable in which data is divided into elements by attribute marks, value marks and subvalue marks, matching the structure of a Reality file item. The entire array is referenced and stored as a single variable. Also, an element of a dimensioned array can be a dynamic array. The main purpose of a dynamic array is the processing of Reality items. Dynamic arrays do not need to be dimensioned before use.

An array element is accessed by entering the array name with up to three integer numbers, separated by commas within chevrons < >, which specify the number of an attribute, value and subvalue element, respectively.

Syntax

dyn-array{<attr#{,value#{,subval#}}>}

where:

dyn-array is an expression that evaluates to a dynamic array.

attr# is an expression that evaluates to the attribute number to be referenced within the dynamic array.

value# is an expression that evaluates to a value number within the attribute.

subval# is an expression that evaluates to a subvalue number within the specified attribute and value.

The expressions attr#, value#, and subval# are called positional expressions, and identify the particular element being referenced. Attributes, values and subvalues are numbered starting at 1. If no positional expressions are specified, then the entire dynamic array is referenced.

If subval# is not referenced (or if it is zero), then the whole specified value is referenced. If both value# and subval# are omitted (or are zero), then the whole attribute is referenced.

See Rules for Dynamic Array References for a description of the results when positional expressions are fractional or negative.

A dynamic array element cannot be specified in an EQUATE statement.

Element Delimiters

The number of elements making up an array are defined by attribute marks, value marks and subvalue marks held in the array. An example of how a dynamic array is stored is shown below:

ABC^DEF]GHI]JKL^MNO\PQR\STU]VWX^YZ

The special characters used to delimit attribute, value and subvalue elements are defined as follows:

Attribute Mark Represented by a caret (^). It is entered by pressing CTRL+^ (CHAR(254) = X'FE'). It delimits an attribute in a dynamic array and file item.

Value Mark Represented by a right bracket (]). It is entered by pressing CTRL+] (CHAR(253) = X'FD'). It delimits an value within an attribute in a dynamic array and file item. Attributes may contain a number of values, separated by value marks.

Subvalue Mark Represented by a backslash (\). It is entered by pressing CTRL+\ (CHAR(252) = X'FC'). It delimits an subvalue within an attribute in a dynamic array and file item. Values may contain a number of subvalues, separated by subvalue marks.

It is strongly recommended that when creating a dynamic array string in a program, that you use the appropriate predefined symbols to represent attribute, value and subvalue marks. For example:

ARRAY = N:@AM:'Price':@AM:'33 Bolton Road':@VM:'Preston':@VM
ARRAY = ARRAY:'Lancs':@VM:'PR7':@SM:'6ZX'

It is not good practice to include CTRL characters in your program. The attribute mark (CTRL+^) will not even compile, as it functions as an end-of-line character.

Data Extraction and Replacement

An attribute, value or subvalue can be extracted from or replaced in a dynamic array by specifying a dynamic array reference (as described in the Syntax description) as an expression within a DataBasic statement.

To extract data, the dynamic array is referenced on the right-side of the assignment statement and the variable to which the extracted data is assigned is on the left-side. For example:

variable = array<attr#,value#,subval#>

To replace data into a specified attribute, value or subvalue of a dynamic array, the expression providing the data is placed on the right-side of an assignment statement and the dynamic array element to receive the data is referenced on the left-side of the statement. For example:

dyn-array<attr#,value#,subval#> = expression

Data Insertion and Deletion

An attribute, value or a subvalue can be inserted into and deleted from a dynamic array by specifying a dynamic array reference as part of the INS and DEL statements, respectively. See also the topic Rules for Dynamic Array References.

Dynamic Array Examples

Example 1

Dynamic array ITEM is: XY^1000^53D^799^CDF. This contains five attributes, but no values or subvalues.

ITEM<3> references the third attribute (53D).

Example 2

Dynamic array ABC is: XYZ^21A00^45]34]67]89]XX^3000

ABC contains four attributes:

XYZ, 21A00, 45]34]67]89]XX and 3000

The third attribute contains five values:

45, 34, 67, 89 and XX

X=3; Y=5
Z=ABC<X,Y>

When this code is run, ABC<3,5> references the fifth value in the third attribute, assigning XX to the variable Z.

Example 3

Dynamic array DYNARRAY is: Q56^99^3.22]3.56\88]C. This contains three attributes:

Q56, 99 and 3.22]3.56\88]C

The third attribute contains three values:

3.22, 3.56\88 and C

The second value of the second attribute contains two subvalues:

3.56 and 88

I=3; J=2; K=1
VAR = DYNARRAY<I,J,K+1>

When this code is run, DYNARRAY<3,2,2> references the second subvalue in the second value in the third attribute, assigning the value 88 to variable VAR.

Program Examples

The following examples show simple DataBasic programs used to create dynamic arrays and the resulting array structures.

Example 1

EQU AM TO CHAR(254)
SIMPLE.DYN.ARRAY = 55:AM:"ABCD":AM:"732XYZ":100000.33

This defines the dynamic array 55^ABCD^732XYZ^100000.33 comprising attributes: 55, ABCD, 732XYZ and 100000.33.

Example 2

STAFF.INFO = "" 
STAFF.INFO<1> = "N"
STAFF.INFO<2> = "Price"
STAFF.INFO<3,1> = "33 Bolton Road"
STAFF.INFO<3,2> = "Preston"
STAFF.INFO<3,3> = "Lancs"
STAFF.INFO<3,4,1> = "PR7"
STAFF.INFO<3,4,2> = "6ZX"

The following program is equivalent to the above:

STAFF.INFO = N:@AM:'Price':@AM:'33 Bolton Road':@VM:'Preston':@VM
STAFF.INFO = STAFF.INFO:'Lancs':@VM:'PR7':@SM:'6ZX'

Both example programs define the following dynamic array, STAFF.INFO:

N^Price^33 Bolton Road]Preston]Lancs]PR7\6ZX

comprising three attributes:

1. N
2. Price
3. 33 Bolton Road]Preston]Lancs]PR7\6ZX

The third attribute (the address) contains four values:

1. 33 Bolton Road
2. Preston
3. Lancs
4. PR7\6ZX

The last value (the post-code) contains two subvalues:

1. PR7
2. 6ZX

Data Extraction Examples

Example 1

QTY = ITEM<3>

Assigns the value of the third attribute in dynamic array ITEM to variable QTY.

Example 2

PRINT STRING<5,3>

Prints the third value in the fifth attribute in dynamic array STRING.

Example 3

POSTCODE=ADDRESSES<3,4,1>

Assigns to the variable POSTCODE the first subvalue in the fourth value in the third attribute of dynamic array ADDRESSES.

Data Replacement Examples

Example 1

A<6,1>=PRICE

Replaces the first value in the sixth attribute in dynamic array A with the current value of PRICE.

Example 2

ORDER<2,5,3> = YR*365

Replaces the third subvalue in the fifth value in the second attribute in dynamic array ORDER with the value of YR multiplied by 365.

Example 3

IF PART<1,X+2> = 0 THEN PART<1,X+2> = 1

If the content found inside the dynamic array PART at the first attribute, value position x+2, is zero, it is replaced with literal value 1.

Rules for Dynamic Array References

Dynamic array references (array<attr#,value#,subval#>) containing values other than nonzero positive integers are not directly valid for data extraction or replacement in dynamic arrays. Before they can be used by the DataBasic processor, they are converted according to a set of rules. Some rules apply to both data extraction and replacement, others apply to only one operation. The rules are as follows:

1. Non-numeric expressions display a warning message and default to zero.
2. Non-integer expressions truncate the decimal value. For example, 1.7 and 1.2
   become 1.
3. All trailing zero-valued positional expressions (except attribute) are ignored.
4. Any remaining zero-valued positional expressions default to one.
5. Negative integers in attribute references, -1, -2, -3 etc., return the last attribute, second to last attribute, third to last attribute etc., respectively.

6. Negative integers in values and subvalue references return null.
7. If the positional expressions specify a nonexistent position, or if the dynamic array is initially null, a null value is returned.

8. The first negative value is converted to minus one. Any subsequent negative values are converted to plus one.
9. If the dynamic array is null, the minus one is replaced by plus one, and Rule 9 is applied. If the dynamic array is not null, the replacement value is appended to the array or to a component of the array as a new attribute, value or subvalue (according to which position is negative). The remaining positional expressions (if any) are treated as usual.
10. If the positive positional expressions specify a nonexistent position, nulls are created where needed to put the replacement value in the indicated position. A trailing delimiter is not added.

Example 1

The following examples illustrate the operation of the rules when array specifications <attr#,value#,subval#> other than nonzero integers are used to extract data from a dynamic array.

Dynamic array S is: "1\2\3]11\22]333^A\B\C]AA"

Rn represents the rule number n that applies.

Original Expression	Intermediate Expression	Returns
S<0,0,0>	S<0>  (R3)
S<1>  (R4)	1\2\3]11\22]333
S<0,0,2>	S<1,1,2>  (R4)	2
S<0,2,0>	S<0,2>  (R3)
S<1,2>  (R4)	11\22
S<2,0,0>	S<2>  (R3)	A\B\C]AA
S<"ABC">	S<0>  (R1)	Error Message
	S<1>  (R4)	1\2\3]11\22]333
S<1.9>	S<1>  (R2)	1\2\3]11\22]333
S<1,-1>	null (R6)	null
S<5>	null (R7)	null

Example 2

The following examples illustrate the operation of the rules when array specifications <attr#,value#,subval#> other than nonzero integers are used to replace data in a dynamic array (S). Rn represents the rule number n that applies.

In the following examples, S and X have the following values:

Dynamic array S is "1\2\3]11\22]333^A\B\C]AA"
Variable X="DDD"

Original Expression	Intermediate Expression	Resulting String in First Variable
S<2,0>=X	S<2> (R3)	1\2\3]11\22]333^DDD
S<0,2,0>=X	S<0,2> (R3) S<1,2> (R4)	1\2\3]DDD]333^A\B\C]AA
S<1,1.6>=X	S<1,1> (R2)	DDD]11\22]333^A\B\C]AA
S<"ABC">=X	S<0> (R1) S<1> (R4)	Error Message DDD^A\B\C]AA
S<-5>=X	S<-1> (R8, R9)	1\2\3]11\22]333^A \B\C]AA^DDD
S<-5,3,-2>=X	S<-1,3,1> (R8)           (R9, R10)	1\2\3]11\22]333^A\ B\C]AA^]]DDD