Skip to content

Structure_Start

See Also: Database API Attributes, Structure_Abort Command, Structure_End Command, Creating and Modifying Table Structures in the Database Essentials section of the Developing Database Applications book, DF_FILE_PHYSICAL_NAME for examples of creating a new table.

Purpose

This command begins the creation of a new table or modification of an existing one.

Syntax

Structure_Start
tableNum
[
driverName
]

Argument Explanation

tableNum

Must be a variable. It must have a value of 0 if starting a new table, or the number of a table being modified. In either case, a handle to the structure is written back into tableNum so that attributes of the new structure can be queried.

driverName

Required when creating a new table. Name of the driver to use when creating the new table. If this parameter is not supplied, it defaults to the embedded database (DataFlex) driver. The names of drivers available from Data Access Worldwide are:

  • DATAFLEX for the embedded database
  • DB2_DRV for the DB2 Driver
  • DFBTRDRV for the Pervasive.SQL Driver
  • MSSQLDRV for the SQL Server Driver
  • ODBC_DRV for the ODBC Driver

If you are using drivers provided by other vendors, check the driver documentation for the driver name.

What It Does

This command is used to change a table's physical structure, such as adding, deleting, or modifying indexes. Inside a Structure_Start...Structure_End block, Database API Attributes are used to specify the specific attributes, including table, field, and index attributes. See Execute Structure_Start for default attribute values and DF_FILE_PHYSICAL_NAME for examples of creating a new table.

Handle hTable
Move 0 to hTable
Structure_Start hTable "DATAFLEX"
    // do the table creation/modification
Structure_End hTable

The above example shows the Structure_Start...Structure_End block you could use to create a new DataFlex database table.

Notes

  • After a restructure, tableNum contains a table handle rather than the table number it was passed before the restructure. Therefore, an open tableNum statement after a restructure will return an error. It is good practice either to create a separate variable to pass to Structure_Start for tableNum or to perform restructures in procedures that use a local variable for the parameter.

  • When creating a new table, DF_FILE_PHYSICAL_NAME can be used to specify the physical table name. If not set, DFDFLT will be used as the physical table name. The Execute Structure_Start topic has more information about table creation default values.

Handle hTable
Move 0 to hTable
Structure_Start hTable "DATAFLEX"
Set_Attribute DF_FILE_PHYSICAL_NAME of hTable to "Customer"
// set other attributes, etc.
Structure_End hTable

  • When restructuring an embedded database table, in order to perform any type of restructuring operation, the header file (.HDR) must be located in the same folder as the .DAT file.

  • When restructuring an embedded database table, after restructuring, the table's DF_FILE_REVISION attribute will be that of the revision of DataFlex used when the table was restructured.

  • This command is only for attributes that actually change the structure of the table, such as creating or deleting a column or index. If you are setting an attribute that does not modify the table structure, you should do it outside any Structure_Start/Structure_End block.

For example, setting DF_FILE_DISPLAY_NAME does not change the structure of the table; it only modifies filelist.cfg. The following sequence will cause an error (Bad table number):

Handle hTable
Open Test1
Move Test1.File_Number to hTable
Structure_Start hTable
Set_Attribute DF_FILE_DISPLAY_NAME of hTable to "Employee Data"
Structure_End hTable DF_STRUCTEND_OPT_NONE

This code would work as intended without the Structure_Start and Structure_End commands:

Handle hTable
Open Test1
Move Test1.File_Number to hTable
Set_Attribute DF_FILE_DISPLAY_NAME of hTable to "Employee Data"