ModifyTable()

Summary

Modifies the file structure of a dBASE, fixed-format text, or fixed-format binary table.

 

Changes

In Version 2013 added field types "Date", "Time", and "DateTime."

 

Syntax

ModifyTable(string view_name, array field_info_array)

 

Argument	Contents
view_name	Name of an open table; if null, the current view is used
field_info_array	An array with one element for each field in the modified table, where each element is an array as follows:

 

Element	Type	Contents
1	String	Modified field name
2	String	Field type - "Integer" (long integers), "Real" (double-precision floating point numbers), "String", "Short" (short integers), "Tiny" (one-byte integers), "Float" (single-precision floating point numbers), "Date" (4-byte date), "Time" (4-byte time), or "DateTime" (8-byte date and time)
3	Integer	Internal field width
4	Integer	Number of decimals
5	Boolean	Whether or not the field should be internally (permanently) indexed
6	String	Field format; ignored for dBASE tables and string fields of non-dBASE tables
7	Array of arrays	The aggregation rules for the field; each rule is in a subarray
8	String	A description of the field
9	Same as field type	The default value
10	Array	Aggregation rule when joining/splitting features for geographic editing
11	String	The display name
12	String	Original field name; null if a new field

 

Notes

• ModifyTable() works only on dBASE, fixed-format text and fixed-format binary tables. It cannot be used on any other view classes, such as comma-separated text, ODBC, or joined views, including tables that are currently joined to geographic layers.

• The field names, widths and decimals are values internal to the table, like those returned by GetTableStructure(). They are not view settings, which can be changed by RenameField(), SetFieldWidth(), or SetFieldDecimals(), except for decimals for a fixed-format binary table, which is a view setting.

• Field widths should be the actual numbers of characters (bytes) per record for dBASE or fixed-format text tables. For fixed-format binary tables, the number of bytes is determined by the number type (Integer - 4 bytes, Short - 2 bytes, Tiny - 1 byte, Real - 8 bytes, or Float - 4 bytes).

• For dBASE and fixed-format text files, the field type can only be Integer, Real, or String.

• Only fixed-format binary tables can have Date, Time, or DateTime field types.

• ModifyTable() may rewrite data files, dictionary files, and index files associated with the table.

• ModifyTable() cannot be used if the table is read-only or not open for exclusive access, or if it is part of any joined view. All joined views containing the table must be closed (with CloseView()) before the table can be modified.

• Add new fields by specifying a field_info sub-array with the last element (original internal field name) null. A new field has all missing values.

• An existing field that is not in the field_info_array is dropped.

• An existing field is retained if it is included in the field_info_array:

• • To change its (internal) name, specify a field name (first element) different from the original field name (last element).

  • To change its type, internal width, etc., specify the new values.

• Some settings are ignored for certain types of tables. For example, dBASE has no display name, default value, or aggregation rules.

• To convert string-typed fields to numeric fields, and vice versa, use ModifyTable(). Some loss of data or precision may result when a string-typed field is converted to numeric, when a field's internal width is reduced, or (in case of dBASE files only) when the number of decimals is changed.

• In modifying a table, various class-specific restrictions may limit the field name, field width, number of fields, total widths of all fields, etc. (dBASE, for instance, limits the field name to 11 characters, without spaces or special characters, and the number of fields to 255 or smaller; the full list is in the Table Limits topic in the program help.). Whenever the input field_info_array violates some class-specific restrictions, ModifyTable() changes the specifications minimally to conform to the restrictions. For example, field widths may be reduced, some fields may be dropped, etc.

• ModifyTable() does not guarantee to shrink a data file when fields are dropped. In the case of fixed-format text or fixed-format binary tables, if some fields are dropped but there are no other changes, ModifyTable() may rewrite only the dictionary file. To physically reduce the size of a data file (to free up disk space, for instance), use ExportView().

• The field_info_array cannot be null; ModifyTable() cannot create a table with no fields. The field_info_array can be of the old type, with nine elements.

• The field format, for a numeric field, can be any of those described in Format().

• An aggregation rule specifies that a new field should be created when this table is used in a join, and describes how the field is filled based on values from the records that are collapsed into one record in a join. The rules can be one or more of the following: {"Max"}, {"Min"}, {"Dom"}, {"Count"}, {"Sum"}, or {"Avg"}, meaning that the field is the maximum, the minimum, the first value, the count of the values, the sum of values, or the average of values, respectively. The rules {"Avg", orig_field}, and {"Avg", new_field, "new"} indicate that the average is to be weighed, either by a field whose name is orig_field before this call to ModifyTable(), or by a field whose name will be new_field after this call to ModifyTable().

• The aggregation rule array for joining/splitting is in the format of a single element of the aggregation rules array for the field. The rule can be only one of the following: {"Max"}, {"Min"}, {"Dom"}, {"Count"}, {"Sum"}, or {"Avg"}, meaning that the field is the maximum, the minimum, the first value, the count of the values, the sum of values, or the average of values, respectively. The rules {"Avg", orig_field}, and {"Avg", new_field, "new"} indicate that the average is to be weighed, either by a field whose name is orig_field before this call to ModifyTable(), or by a field whose name will be new_field after this call to ModifyTable().

Example

// First open customer.dbf in the Tutorial folder for exclusive access

view_name = GetView()

strct = GetTableStructure(view_name, {{"Include Original", "True"}})

// Add a field for 2002 Sales data

strct = strct + {{"Sales2000", "Real", 12, 2, "True", , , , , , , null}}

// Modify the table

ModifyTable(view_name, strct)

Error Codes

Error Type	Meaning
Error	Field_info_array is null or invalid; the table is not modifiable because it is read-only, part of a joined view, or not a dBASE, fixed-format text, or fixed-format binary table; or a file I/O error occurred that prevented rewriting of some files, (e.g., the user does not have write access, some files are in use, or there is not enough disk space for temporary files)
NotFound	The named view does not exist, or table_name is null and there is no current view

 

See Also

Function	Summary
CreateTable()	Creates an empty table and opens it as a view
GetFieldAggregations()	Gets the aggregation rules for a field
GetFieldDescription()	Gets the description of a field
GetTableModifyFlag()	Tests whether a table can be modified by ModifyTable()
GetTableStructure()	Gets a list and description of the fields in a table