Skip to content

Create_Field

See Also: Defining Columns in the Studio, Set_Attribute, DF_FILE_PHYSICAL_NAME for examples of creating a new table.

Purpose

To add or insert a column into the structure of a database table.

Syntax

Create_Field {table-handle} [at {column-num}]

Where

  • {table-handle} is a handle to the database table where the new column should be added.
  • {column-num} is the number to use for the new column. {column-num} should be passed as a variable, since the number of the column created will be returned here.

What It Does

This command creates a new column. If {column-num} is omitted or 0, the column will be appended to the end of the existing record structure (if any). The column number assigned is returned in {column-num}. {table-handle} must be the handle of a database table currently being restructured or created.

The numbers of all columns above {column-num} (if any) will be incremented by one. Thus, if {column-num} is 4, the current column number 4 will become column number 5, column number 5 becomes 6, etc.

By default, the column created will be of type ASCII with a length of 0 (zero) bytes. The name of the column will be FIELDn, where n is equal to {column-num}. Use the Set_Attribute command to change these defaults.

Example

Handle  hTable
Integer iNewColumn

// Open the Employee table, and retrieve its number to hTable
Open employee
Move (RefTable(employee)) to hTable
Structure_Start hTable

// Add a new column to the Employee table
Move 0 to iNewColumn
Create_Field hTable at iNewColumn

// Set the attributes of the newly created column
// iNewColumn now contains the new column number that was added
Set_Attribute DF_FIELD_NAME of hTable iNewColumn to "Hire_Date"
Set_Attribute DF_FIELD_TYPE of hTable iNewColumn to DF_DATE
Structure_End hTable

This example creates a new column, Hire_Date, in the table Employee as a date column.

Notes

  • This command must be used within a Structure_Start ... Structure_End block. If not, you will get an error message.
  • If you specify a column number greater than the last existing column, you will receive an error. Thus, if the table currently contains five columns, the maximum value for {column-num} would be 5.
  • To create columns in a new table that has no columns, use {column-num} of zero to create the first column, and to append columns, in the order they are listed in your code, to the record structure.
  • You can use the Table Editor in the Studio to create your tables instead of doing it programmatically.