This file contains update information that is not included in the 
field test documentation.

The following commands are documented, but have been removed from 
the product:
AADD()
FIXED()  
SET STATUS

The following commands are not documented in the field test 
documentation, please see the details below:
AGROW()
ARESIZE()
SET RELATION



AGROW( )

Memory variables

Adds an element, row, or column to an array and returns a numeric 
value representing the number of added elements.

Syntax
AGROW (<array name>, <expN>)

<array name>
The name of a declared one- or two-dimensional array you want to 
add elements to.

< expN>
Either 1 or 2. When you specify 1, AGROW( ) adds a single element 
to a one-dimensional array or a row to a two-dimensional array. 
When you specify 2, AGROW( ) adds a column to the array.

Description
Use AGROW( ) to insert an element, row, or column into an array 
and change the size of the array to reflect the added elements. 
AGROW( ) can make a one-dimensional array two-dimensional. All 
added elements are initialized to .F. values. To insert .F. values 
without changing the size of the array, use AINS( ).

One-dimensional arrays
When you specify 1 for <expN>, AGROW( ) adds a single element to 
the array. When you specify 2, AGROW( ) makes the array two-
dimensional, and existing elements are moved into the first 
column.

Two-dimensional arrays
When you specify 1 for <expN>, AGROW( ) adds a row to the array 
and adds the row at the end of the array. When you specify 2 for 
<expN>, AGROW( ) adds a column to the array and places .F. into 
each element in the column.
 
Example
The following example initially declares an array of three 
elements, and then uses AGROW( ) to add a fourth element, a second 
column and finally, to add a row to the two dimensional array. 
DISPLAY MEMORY is used to show the values in the array after each 
AGROW( ) operation:

RELEASE ALL
DECLARE A[3]
A[1]="x"
A[2]="y"
A[3]="z"
DISPLAY MEMORY
N=AGROW(A,1)      && adds an element to A
DISPLAY MEMORY
N=AGROW(A,2)      && adds a column to A
DISPLAY MEMORY
N=AGROW(A,1)      && adds a new row to A
DISPLAY MEMORY
 
Portability
Not supported in dBASE IV or dBASE III PLUS.
 
See Also
AINS( )
ALEN( )
ARESIZE( )
DECLARE



ARESIZE( )

Memory variables

Increases or decreases the size of an array according to the 
specified dimensions and returns a numeric value representing the 
number of elements in the modified array.

Syntax
ARESIZE(<array name>, <new rows expN> 
[[,<new cols expN>] [, <retain values expN>]])

<array name>
The name of a declared one- or two-dimensional array whose size 
you want to increase or decrease.

<new rows expN>
The number of rows the resized array should have. <new rows expN> 
must always be a positive, nonzero value.

<new cols expN>
The number of columns the resized array should have. <new cols 
expN> must always be 0 or a positive value. If you omit this 
option, ARESIZE( ) changes the number of rows in the array and 
leaves the number of columns the same.

<retain values expN>
Determines what happens to the values of the array when rows are 
added or removed. If you want to specify a value for <retain 
values expN>, you must also specify a value for <new cols expN>.

Description
Use ARESIZE( ) to change the size of a declared array, making it 
larger or smaller. To determine the number of rows or columns in 
an existing array, use ALEN( ), If you add or remove columns from 
the array, you can use <retain values expN>to specify how you want 
existing elements to be placed in the new array. If <retain values 
expN> is zero or isn’t specified, ARESIZE( ) rearranges the 
elements, filling in the new rows or columns or adjusting for 
deleted elements, and adding or removing elements at the end of 
the array, as needed. You are most likely to want to do this if 
you don’t need to refer to existing items in the array; that is, 
you plan to update the array with new values.

When you use ARESIZE( ) on a one-dimensional array, you might want 
the original row to become the first column of the new array. 
Similarly, when you use ARESIZE( ) on a two-dimensional array, you 
might want existing two-dimensional array elements to remain in 
their original positions. You are most likely to want to do this 
if you need to refer to existing items in the array; that is, you 
plan to add new values to the array while continuing to work with 
existing values.If <retain values expN> is a nonzero value, 
ARESIZE( ) ensures that elements retain their original values. 

Example
The following example initially declares an array of three 
elements, and then uses ARESIZE( ) to resize the array to A[5], 
A[5,2] and finally back to A[3]. DISPLAY MEMORY is used to show 
the values in the array after each ARESIZE( ) operation:

RELEASE ALL
DECLARE A[3]
A[1]="x"
A[2]="y"
A[3]="z"
DISPLAY MEMORY
N=ARESIZE(A,5)         && A now has 5 elements
A[4]="new1"
A[5]="new2"
DISPLAY MEMORY
N=ARESIZE(A,5,2,1)      
* A now has 5 rows and 2 columns. 
* The new cols are all set to .t.
* Old values are retained
DISPLAY MEMORY
N=ARESIZE(A,3,1,1)
* A now is back to the original 3 elements 
* use:
DISPLAY MEMORY
* N=ARESIZE(A,3,1,0) 
* if you don't need the original values
DISPLAY MEMORY
WAIT
 
Portability
Not supported in dBASE IV or dBASE III PLUS.
 
See Also
ADEL( )
AGROW( )
AINS( )
ALEN( )
DECLARE



SET RELATION

Table organization

Links two or more open tables with common fields or expressions.

Syntax
SET RELATION TO 
[<key exp list 1> | <expN 1> 
	INTO <child table alias 1> 
	[, <key exp list 2> | <expN 2> 
		INTO <child table alias 2>] ... ]
[ADDITIVE]]

For dBASE tables, you can also specify options to restrict 
processing of unlinked child table records and specify additional 
data integrity rules:

SET RELATION TO 
[<key exp list 1> | <expN 1> 
	INTO <child table alias 1> 
	[CONSTRAIN]
	[INTEGRITY 
		[CASCADE | RESTRICTED] ]
	[, <key exp list 2> | <expN 2> 
		INTO <child table alias 2>]
		[CONSTRAIN]
		[INTEGRITY 
			[CASCADE | RESTRICTED] ] ... ]
[ADDITIVE]

<key exp list 1>
The key expression or field list that is common to both the 
current table and a child table and links both tables. When 
specifying the INTEGRITY option, you can specify a key field but 
not an expression. The child table must be indexed on the key 
field and that index must be the master index in use for the child 
table. An index based on the same key field must 
also be defined for the parent table but it doesn't need to be the 
master index for that table.

<expN 1> INTO <child table alias>
For dBASE tables only, you can specify <expN>to link records in a 
child table. When <expN> is RECNO( ), Blade Runner links the 
current table to a child table by corresponding record numbers, in 
which case, the child table doesn't have to be indexed.

INTO <child table alias>
<alias> specifies the child table linked to the current table. You 
can specify a work area number (1 through 225), letter (A through 
J), or alias name. The work area letter or alias name must be 
enclosed in quotes.

<key exp list 2> | <expN 2> INTO <alias 2> ...]
Specifies additional relationships from the current table into 
other tables.

CONSTRAIN
Limits records processed in the child table to those matching the 
key expression in the parent table.

INTEGRITY [CASCADE | RESTRICTED]
Specifies rules that control the addition or deletion of records 
in the child table. If INTEGRITY is specified, key fields of 
records added to child tables via APPEND, APPEND BLANK, BROWSE, 
EDIT, or INSERT commands are set to values matching those of the 
parent table. Also, when you delete records or change the value of 
key fields in the parent table, a dialog box appears, in which you 
can choose to delete all related child records (performing a 
cascade delete).
The CASCADE and RESTRICTED options specify rules to follow when 
adding or deleting records in a program (so the dialog box does 
not appear). The CASCADE option specifies that all child table 
records with matching key field values are deleted when you delete 
a record or change the key value of a record in the parent table. 
The RESTRICTED option prevents deletions or changes to records in 
the parent table if the child table contains records with matching 
key field values.

ADDITIVE
Adds the new relation to any existing ones. Without ADDITIVE, SET 
RELATION clears existing relations before establishing the new 
relation.

Description
Use SET RELATION to establish a link between open tables based on 
common fields or expressions. Remember that you can also define 
relations and link tables automaticaly by using the CREATE|MODIFY 
QUERY or VIEW commands, which let you save relations to a .QBE 
file.

Before setting a relation, open each table in a separate work 
area. When a relation is set, the table in the current work area 
is referred to as the parent table, and a table linked to the 
parent table by the specified key is called a child table. The 
child table must be indexed on the fields or expressions that link 
tables and that index must be the master index in use for the 
child table. An index with a key expression that matches <key exp 
list 1> must also be defined for the parent table but doesn't need 
to be the master index in use for that table.

A relation between tables is usually set through common keys 
specified by <key exp list>. The relating expression can be any 
expression derived from the parent table that matches the keys of 
the child table master index. The keys may be a single field or a 
set of concatenated fields contained in each table. The fields in 
each table can have different names but must contain the same type 
of data. For Paradox and SQL tables, you can specify single or 
composite index key fields.

For dBASE tables only, if you specify a numeric expression to link 
tables, the parent table is always linked to record numbers in a 
child table specified by the numeric expression (typically, the 
RECNO( ) function). This causes record 1 in the parent table to be 
linked to record 1 in the child table, record 2 in the parent 
table linked to record 2 in the child table, and so on.

SET RELATION clears existing relations before establishing a new 
one, unless you use the ADDITIVE option. SET RELATION TO without 
any arguments clears existing relations from the current table 
without establishing any new relations.

For dBASE tables, the CONSTRAIN and INTEGRITY options control 
processing of linked records. Using these options requires that 
the parent table not contain any records with duplicate key 
values. If a parent table has duplicate records, copy the table to 
a temporary table, index the temporary table using the UNIQUE 
option, and then use COPY to copy the table back to the original 
table name. After setting up a relation with either CONSTRAIN or 
INTEGRITY, the uniqueness of key values in the parent table is 
strictly enforced.

The CONSTRAIN option restricts access in the child table to only 
those records whose key values match records in a parent table. 
This is the same as using SET KEY TO on the key field of the child 
table. As a result, you can't use SET KEY TO and CONSTRAIN at the 
same time. If a SET KEY TO operation is in effect on the child 
table when you specify CONSTRAIN 
with SET RELATION, Blade Runner returns a "SET KEY in use in 
alias" message. If the CONSTRAIN option is in effect when SET KEY 
TO is specified, Blade Runner returns the error "CONSTRAIN is 
active." You can use SET FILTER with the CONSTRAIN option, if you 
want to specify additional conditions to qualify records in a 
child table.

The INTEGRITY option specifies rules that control the addition or 
deletion of records in the child table. If INTEGRITY is specified, 
when you add records using APPEND, APPEND BLANK, BROWSE, EDIT, or 
INSERT commands, the key fields of records added to child tables 
are set to values matching those of the parent table. If you add 
new records to the parent table, values in the key field must be 
unique; otherwise, Blade Runner returns the error "Key already 
exists." When you edit records in the child table, key fields in 
the child table are read-only.

Integrity rules assume SET DELETED is ON. Setting DELETED OFF is 
not recommended when using the INTEGRITY option since it could 
show linked records already marked for deletion.
 
If you specify the INTEGRITY option without the CASCADE or 
RESTRICTED keywords, when you delete records or change the value 
of key fields in the parent table, a dialog box appears, in which 
you can choose to delete all related child records (performing a 
cascade delete).

If you specify INTEGRITY with the CASCADE option, Blade Runner 
automatically deletes all records in the child table that match 
the key value of records that are deleted or changed in the parent 
table. If a key value of a record in the parent table is changed 
to a value that already exists, Blade Runner returns the error 
"Key already exists."

If you specify INTEGRITY with the RESTRICTED option, Blade Runner 
prevents you from deleting records in the parent table with linked 
child table records. If you attempt to delete records or change 
the key value of records in the parent table while records with 
matching key values still exist in the child table, Blade Runner 
returns the error "Linked records still exist in alias" and the 
parent table record is not deleted or changed. You can delete 
records in a child table unless that table is itself a parent and 
an integrity rule is defined that restricts deletions to its child 
table records.

More than one relation can be defined from the same table. Also, 
more than one relation can be set from the same parent table if 
you use the ADDITIVE option or if you specify multiple relations 
with the same SET RELATION command. You can also establish 
additional relations from a child table, thus defining a chain of 
relations. Cyclic relations aren't allowed; that is, Blade Runner 
returns an error if you attempt to define a relation from a child 
table back into its parent table.

When a relation is set from a parent table to a child table, the 
relation can be accessed only from the work area that contains the 
parent table. To access fields of the child table from the current 
work area, use the alias pointer (->) and prefix the name of 
fields in the child table by its alias name.

If a matching record can't be found in a linked table, the linked 
table is positioned at the end-of-file, and EOF( ) returns .T. The 
setting of SET NEAR does not affect positioning of the record 
pointer in child tables. When the INTEGRITY option is used, if the 
parent table is positioned at the end of file, Blade Runner 
returns the error "No matching parent record."

When a SET SKIP list is active, the record pointer is advanced in 
each table, starting with the last work area in the relation chain 
and moving up the chain toward the parent table.
 
Example
The following example uses SET RELATION to create a relationship 
based on the key field, CompCode, between the parent table, 
Company, and the child table, Contact:

CLOSE ALL
USE Contact EXCLUSIVE
INDEX ON Compcode TAG Compcode
SELECT 2
USE Company EXCLUSIVE
INDEX ON Company TAG Company
SET RELATION TO CompCode INTO Contact

Now the contact and the company for which they are a contact are 
connected. Contact, the child table, must be indexed on Compcode. 
Company does not need to be indexed on Compcode.

If you want to add a second relationship for Company, use the 
ADDITIVE clause. In this example, a relationship to the TypeCo 
table is added. TypeCo is a code table that contains the TYPE 
field used in the company table (for example, "ISV") and a 
description in the TYPE_DESC field (for example, "Independent 
Software Vendor"):

SELECT SELECT()       && Select the next open work area
USE TypeCo EXCLUSIVE  && Contains a description of
                      && the type of company  
INDEX ON TYPE TAG TYPE
SELECT Company
SET RELATION TO Type INTO TypeCo ADDITIVE

Now Company is simulaneously related to Contact via field Compcode 
and to TypeCo via the Type field.
DISPLAY ALL Company,Contact->Contact,;
  TypeCo->Type_desc
* All three tables are accessed
 
See Also
CREATE VIEW FROM ENVIRONMENT
JOIN
SELECT
SET FIELDS
SET FILTER
SET SKIP
SET VIEW
SKIP
