MDAC 2.5 SDK - Visual FoxPro ODBC Driver


 

ALTER TABLE - SQL Command

Programmatically modifies the structure of a table.

Syntax

ALTER TABLE TableName1
   ADD | ALTER [COLUMN] FieldName1
      FieldType [(nFieldWidth [, nPrecision])]
      [NULL | NOT NULL]
      [CHECK lExpression1 [ERROR cMessageText1]]
      [DEFAULT eExpression1]
      [PRIMARY KEY | UNIQUE]
      [REFERENCES TableName2 [TAG TagName1]]
      [NOCPTRANS]

  Or

ALTER TABLE TableName1
   ALTER [COLUMN] FieldName2
      [NULL | NOT NULL]
      [SET DEFAULT eExpression2]
      [SET CHECK lExpression2 [ERROR cMessageText2]]
      [DROP DEFAULT]
      [DROP CHECK]

  Or

ALTER TABLE TableName1
   [DROP [COLUMN] FieldName3]
   [SET CHECK lExpression3 [ERROR cMessageText3]]
   [DROP CHECK]
   [ADD PRIMARY KEY eExpression3 TAG TagName2]
   [DROP PRIMARY KEY]
   [ADD UNIQUE eExpression4 [TAG TagName3]]
   [DROP UNIQUE TAG TagName4]
   [ADD FOREIGN KEY [eExpression5] TAG TagName4
      REFERENCES TableName2 [TAG TagName5]]
   [DROP FOREIGN KEY TAG TagName6 [SAVE]]
   [RENAME COLUMN FieldName4 TO FieldName5]
   [NOVALIDATE]

Arguments

TableName1

Specifies the name of the table whose structure is modified.

ADD [COLUMN] FieldName1

Specifies the name of the field to add.

ALTER [COLUMN] FieldName1

Specifies the name of an existing field to modify.

FieldType [(nFieldWidth [, nPrecision]])

Specifies the field type, field width, and field precision (number of decimal places) for a new or modified field.

FieldType is a single letter indicating the field's data type. Some field data types require that you specify nFieldWidth or nPrecision or both.

nFieldWidth and nPrecision are ignored for D, G, I, L, M, P, T, and Y types. nPrecision defaults to zero (no decimal places) if nPrecision isn't included for the B, F, or N types.

NULL | NOT NULL

Allows or prevents null values in the field.

If you omit NULL and NOT NULL, the current setting of SET NULL determines whether null values are allowed in the field. However, if you omit NULL and NOT NULL and include the PRIMARY KEY or UNIQUE clause, the current setting of SET NULL is ignored and the field defaults to NOT NULL.

CHECK lExpression1

Specifies a validation rule for the field. lExpression1 must evaluate to a logical expression and can be a user-defined function or a stored procedure. Whenever a blank record is appended, the validation rule is checked. An error is generated if the validation rule doesn't allow for a blank field value in an appended record.

ERROR cMessageText1

Specifies the error message displayed when the field validation rule generates an error.

DEFAULT eExpression1

Specifies a default value for the field. The data type of eExpression1 must be the same as the data type for the field.

PRIMARY KEY

Creates a primary index tag. The index tag has the same name as the field.

UNIQUE

Creates a candidate index tag with the same name as the field.

Note   Candidate indexes (created by including the UNIQUE option, provided for ANSI compatibility in ALTER TABLE or CREATE TABLE) are not the same as indexes created with the UNIQUE option in the INDEX command. An index created with UNIQUE in the INDEX command allows duplicate index keys; candidate indexes do not allow duplicate index keys.

Null values and duplicate records are not permitted in a field used for a primary or candidate index.

If you are creating a new field with ADD COLUMN, Visual FoxPro will not generate an error if you create a primary or candidate index for a field that supports null values. However, Visual FoxPro will generate an error if you attempt to enter a null or duplicate value into a field used for a primary or candidate index.

If you are modifying an existing field and the primary or candidate index expression consists of fields in the table, Visual FoxPro checks the fields to see whether they contain null values or duplicate records. If they do, Visual FoxPro generates an error and the table is not altered.

REFERENCES TableName2 TAG TagName1

Specifies the parent table to which a persistent relationship is established. TAG TagName1 specifies the parent table's index tag on which the relationship is based. Index tag names can contain up to 10 characters.

NOCPTRANS

Prevents translation to a different code page for character and memo fields. If the table is converted to another code page, the fields for which NOCPTRANS has been specified are not translated. NOCPTRANS can be specified only for character and memo fields.

The following example creates a table named mytable containing two character fields and two memo fields. The second character field, char2, and the second memo field, memo2, include NOCPTRANS to prevent translation.

CREATE TABLE mytable (char1 C(10), char2 C(10) NOCPTRANS,;

memo1 M, memo2 M NOCPTRANS)

ALTER [COLUMN] FieldName2

Specifies the name of an existing field to modify.

SET DEFAULT eExpression2

Specifies a new default value for an existing field. The data type of eExpression2 must be the same as the data type for the field.

SET CHECK lExpression2

Specifies a new validation rule for an existing field. lExpression2 must evaluate to a logical expression and may be a user-defined function or a stored procedure.

ERROR cMessageText2

Specifies the error message displayed when the field validation rule generates an error. The message is displayed only when data is changed within a Browse or Edit window.

DROP DEFAULT

Removes the default value for an existing field.

DROP CHECK

Removes the validation rule for an existing field.

DROP [COLUMN] FieldName3

Specifies a field to remove from the table. Removing a field from the table also removes the field's default value setting and field validation rule.

If index key or trigger expressions reference the field, the expressions become invalid when the field is removed. In this case, an error isn't generated when the field is removed but the invalid index key or trigger expressions will generate errors at run time.

SET CHECK lExpression3

Specifies the table validation rule. lExpression3 must evaluate to a logical expression and may be a user-defined function or a stored procedure.

ERROR cMessageText3

Specifies the error message displayed when the table validation rule generates an error. The message is displayed only when data is changed within a Browse or Edit window.

DROP CHECK

Removes the table's validation rule.

ADD PRIMARY KEY eExpression3 TAG TagName2

Adds a primary index to the table. eExpression3 specifies the primary index key expression, and TagName2 specifies the name of the primary index tag. Index tag names can contain up to 10 characters. If TAG TagName2 is omitted and eExpression3 is a single field, the primary index tag has the same name as the field specified in eExpression3.

DROP PRIMARY KEY

Removes the primary index and its index tag. Because a table can have only one primary key, it isn't necessary to specify the name of the primary key. Removing the primary index also deletes any persistent relations based on the primary key.

ADD UNIQUE eExpression4 [TAG TagName3]

Adds a candidate index to the table. eExpression4 specifies the candidate index key expression, and TagName3 specifies the name of the candidate index tag. Index tag names can contain up to 10 characters. If you omit TAG TagName3 and if eExpression4 is a single field, the candidate index tag has the same name as the field specified in eExpression4.

DROP UNIQUE TAG TagName4

Removes the candidate index and its index tag. Because a table can have multiple candidate keys, you must specify the name of the candidate index tag.

ADD FOREIGN KEY [eExpression5] TAG TagName4

Adds a foreign (nonprimary) index to the table. eExpression5 specifies the foreign index key expression, and TagName4 specifies the name of the foreign index tag. Index tag names can contain up to 10 characters.

REFERENCES TableName2 [TAG TagName5]

Specifies the parent table to which a persistent relationship is established. Include TAG TagName5 to establish a relation based on an existing index tag for the parent table. Index tag names can contain up to 10 characters. If you omit TAG TagName5, the relationship is established using the parent table's primary index tag.

DROP FOREIGN KEY TAG TagName6 [SAVE]

Deletes a foreign key whose index tag is TagName6. If you omit SAVE, the index tag is deleted from the structural index. Include SAVE to prevent deletion of the index tag from the structural index.

RENAME COLUMN FieldName4 TO FieldName5

Allows you to change the name of a field in the table. FieldName4 specifies the name of the field that is renamed. FieldName5 specifies the new name of the field.

Caution   Exercise care when renaming table fields—index expressions, field and table validation rules, commands, functions, and so on may reference the original field names.

NOVALIDATE

Specifies that Visual FoxPro allows changes to be made to the structure of the table; these changes might violate the integrity of the data in the table. By default, Visual FoxPro prevents ALTER TABLE from making changes that violate the integrity of the data in the table. Include NOVALIDATE to override this default behavior.

Remarks

ALTER TABLE can be used to modify the structure of a table that has not been added to a database. However, Visual FoxPro generates an error if you include the DEFAULT, FOREIGN KEY, PRIMARY KEY, REFERENCES, or SET clauses when modifying a free table.

ALTER TABLE may rebuild the table by creating a new table header and appending records to the table header. For example, changing a field's type or width might cause the table to be rebuilt.

After a table is rebuilt, field validation rules are executed for any fields whose type or width is changed. If you change the type or width of any field in the table, the table rule is executed.

If you modify field or table validation rules for a table that has records, Visual FoxPro tests the new field or table validation rules against the existing data and issues a warning on the first occurrence of a field or table validation rule or of a trigger violation.

If the table you modify is in a database, ALTER TABLE - SQL requires exclusive use of the database. To open a database for exclusive use, include EXCLUSIVE in OPEN DATABASE.

See Also

CREATE TABLE - SQL

INDEX