CreateTable()

Summary

Creates an empty table and opens it as a view.

 

Changes

In Version 2013 added field types "Date", "Time", and "DateTime." In Version 2016 added MEM class and optional field_info_array elements 5 and 6. Added optional eighth element to field_info_array in Version 2018.

 

Syntax

new_view_name = CreateTable(string view_name, string filename, string class, array field_info_array)

 

Argument	Contents
view_name	Desired name for the new view
filename	File name for the new table
class	Class of new table to create (dBASE, FFA, FFB, CSV, or MEM)
field_info_array	An array that contains one element for each field in the new table, where each element is an array defined as:

 

Element	Type	Contents
1	String	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	Field width
4	Integer	Number of decimals; can be null (defaults to zero)
5 (optional)	Boolean	A flag indicating whether the field should be internally (permanently) indexed; the default is "False"
6 (optional)	String	Description of the field
7 (optional)	Same type as field	The default value of the field
8 (optional)	String	The display format of the field, see Format()

 

Returns

A string containing the name of the view.

 

Notes

• The only supported file-based classes are dBASE, FFA (fixed-format text), FFB (fixed-format binary) and CSV (comma-separated text). CreateTable() cannot be used to create an empty geographic file or a new ODBC or EXCEL table.

• The input filename is the primary filename for the data file. For FFA, FFB or CSV classes, a dictionary file is also created and it has the default dictionary file name. If an internal index on some field is specified, an index file is also created and it has the default index file name.

• The width and number of decimals for a field may indicate display characteristics, actual limitations in the file structure, or both, depending on the limitations and file structures of each specific class.

• CreateTable() creates an empty file and immediately opens that file as a view.

• The tables created with the MEM class are stored in memory instead of being stored on disc, and persist in memory until closed with CloseView() or until the program is closed.

• file_name is ignored for tables created with the MEM class.

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

• The field_info_array cannot be null. CreateTable() cannot create an empty table with no fields.

• The field_info_array required by CreateTable() has the same format as that is returned by GetViewStructure(). These two functions can be used together to create an empty table that has the same field characteristics as an existing table.

• In creating a new table, various class-specific restrictions may limit the field name, field width, number of fields, and total widths of all fields. (dBASE, for instance, limits the field name to 10 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, the program changes the specifications in some minimal way to conform to the restrictions. For instance, field widths may be reduced, or fields may be dropped. The program still succeeds in creating the slightly modified table.

Example

employees = CreateTable("Employees", "employee.dbf", "DBASE", {

     {"LNAME", "String", 16, null, "Yes"},

     {"FNAME", "String", 12, null, "No"},

     {"PAYRATE", "Real", 12, 2, "No"},

     {"ID", "Integer", 8, null, "Yes"}

     })

 

Error Codes

Error Type	Meaning
Error	Input view_name, filename, class or field_info_array is null; or input class is not one of the supported classes; or field_info_array has a wrong format; or a file I/O error occurred (e.g., out of disk space); or the user does not have file access, or some of the new files would overwrite an existing file in use

 

See Also

Function	Summary
OpenTable()	Opens a table from a file on disk and creates a view
GetViewStructure()	Retrieves a listing and description of the fields in a view