AdsRestructureTable

Advantage Client Engine

Adds, removes, or changes field definitions for a table

Syntax

UNSIGNED32

AdsRestructureTable( ADSHANDLE hConnect,

UNSIGNED8 *pucName,

UNSIGNED8 *pucPassword,

UNSIGNED16 usTableType,

UNSIGNED16 usCharType,

UNSIGNED16 usLockType,

UNSIGNED16 usCheckRights,

UNSIGNED8 *pucAddFields,

UNSIGNED8 *pucDeleteFields,

UNSIGNED8 *pucChangeFields );

Parameters

hConnect (I)

An optional connection handle used to open the table. If this is 0, then any available connection of the appropriate type will be used, or a new connection will be created if one is not available. To restructure a free table, this parameter must be a free connection handle or 0. To restructure a database table, this parameter must be a database connection handle to the Advantage Data Dictionary the table is bound to. For a data dictionary-bound table, the connected user must have the ALTER permission to restructure the table.

pucName (I)

Name of table to open. To open a database table, this parameter must specify the name of the table in the data dictionary. The Advantage Database Server will use the information from the data dictionary to resolve the file path of database table. To open a free table, this parameter may specify the file path of the table. If this parameter does not specify a path, then the default path (see AdsSetDefault ) or the search path (see AdsSetSearchPath ) will be used. If no path is given and there is no default or search path, then the current working directory of the application will be used. The Advantage Client Engine resolves all table path names to UNC (Universal Naming Convention). Therefore, it is slightly faster to pass UNC names (e.g., \\server\volume\data\file.dbf) to the Advantage Client Engine rather than relative paths or paths with drive letters.

pucPassword (I)

Encryption password if the table to be restructured is encrypted. If the table is an encrypted free table and the encryption password for the table is not supplied, the function will fail with error 5096 (AE_ENCRYPTION_NOT_ENABLED). This parameter is ignored when restructuring a database table. This parameter is also ignored when restructuring a free table that is not encrypted.

usTableType (I)

Type of table. Options are ADS_DEFAULT, ADS_ADT, ADS_VFP, ADS_NTX and ADS_CDX. If the specified table type is ADS_DEFAULT, the function will attempt to open a database table. In such case, the hConnect parameter must be a database connection handle and the Advantage Server will use the information stored in the data dictionary to resolve the table type. If the specified table type is ADS_ADT, ADS_VFP, ADS_NTX, or ADS_CDX, the function will attempt to open a free table.

usCharType (I)

Type of character data in the table. Options are ADS_ANSI and ADS_OEM. This indicates the type of character data to be stored in the table. For compatibility with DOS-based CA-Clipper applications, ADS_OEM should be specified. When usTableType is ADS_ADT, this parameter is ignored and ANSI is always used. When opening a database table, (i.e., the usTableType is ADS_DEFAULT), this parameter is ignored. The Advantage server will use the information stored in the data dictionary to resolve the character data type.

usLockType (I)

Type of locking to use. Options are ADS_PROPRIETARY_LOCKING and ADS_COMPATIBLE_LOCKING. When opening a database table, (i.e., the usTableType is ADS_DEFAULT) this parameter is ignored and ADS_PROPRIETARY_LOCKING is the default. If the application is to be used with non-Advantage applications, then ADS_COMPATIBLE_LOCKING should be used. If the table will be used only by Advantage applications, then ADS_PROPRIETARY_LOCKING should be used. See your Advantage server guide for more information about locking methods. When ADS_COMPATIBLE_LOCKING is chosen, Advantage uses the appropriate style based on the table type. When usTableType is ADS_ADT, this parameter is ignored and ADS_PROPRIETARY_LOCKING is always used.

usCheckRights (I)

Indicates if the server is to use rights checking for the file open. Options are ADS_CHECKRIGHTS and ADS_IGNORERIGHTS. When opening a database table, (i.e., the usTableType is ADS_DEFAULT) this parameter is ignored. The user access right defined in the database is used (see AdsDDSetDatabaseProperty for more information).

If ADS_CHECKRIGHTS is given, then the Advantage Database Server will use the rights of the connected user when creating the file, and if the user does not have rights to the directory or server, then the creation will fail. If ADS_IGNORERIGHTS is used, then the Advantage Database Server will ignore the connected user's rights and create the table regardless. This way an application developer can allow only Advantage-based applications to access specific data. See Check Rights for more information.

pucAddFields (I)

Field descriptions of the form: "fieldname,type,length,decimals,(order);…". For example: "EMPID,Numeric,5,0;DEPT,Char,20,(3)" 

pucDeleteFields (I)

Field descriptions of the form: "fieldname;…". For example: "EMPID,LASTNAME"

pucChangeFields (I)

Field descriptions of the form: "oldfieldname,newfieldname,type,length,decimals,;…". For example: "EMPID,Employee ID,Numeric,5,0;DEPT,Char,20"

Special Return Codes

AE_RESTRUCTURE_FAILED

The table restructure failed. Call AdsGetLastError for details.

Remarks

CAUTION AdsRestructureTable significantly modifies existing tables and may result in data loss. Prior to using this function, the table to be modified should be backed up. If the table is part of a data dictionary, then the entire database should be backed up. The original table file, memo file, and index files will be renamed by the Advantage Client Engine and left in the same directory. Multiple calls to this function will cause the previously renamed files to be overwritten.

AdsRestructureTable provides the capability to add, delete, or change field definitions within a table. The table may be a free table or a database table. If the table is associated with a database, then the current user must have ALTER permissions for the specified table.

This function will open the table exclusively, so the table may not be opened elsewhere. If the table is part of a database, then all tables interlinked with referential integrity rules will also be opened exclusively. AdsRestructureTable will fail if:

If any of these limitations exist, you may delete the offending indexes or constraint and try again.

The parameters named pucAddFields, pucDeleteFields, and pucChangeFields are comprised of semicolon delimited lists of fields to be manipulated. The pucAddFields is identical to the field definitions passed into AdsCreateTable with one optional, additional parameter. If desired, the field definition can be appended with a comma followed with an integer within parentheses (ex ,(3)). That integer will indicate the position of the field within the table. For example, "lastname, char, 20, (2); employee id, autoinc, (3)" will add two fields into the second and third positions within sequence of fields in the table. The pucDeleteFields parameter is simply a list of existing fields to be deleted. An example to delete two fields is "customer;date". The last parameter, pucChangeFields, is the same as a field definition that is passed to AdsCreateTable except that it is preceded with the original field name. The second field name is the renamed field name. Regardless of what is being changed in the field (the name, size, or type). All values are required. An example that changes the field name "lastname" to the new name "last name" is: "lastname, last name, char, 20". If desired, the field definition can be appended with a comma followed with an integer within parentheses (ex ,(3)). That integer will indicate the position of the field within the table. For example, "Lastname, Lastname, char, 20, (5)" will move the field "Lastname" to the fifth position in the field list.

Note This function is illegal in a transaction.

For information on data types supported, see the following:

ADT Field Types and Specifications

DBF Field Types and Specifications

Note When restructuring a table and changing an integer field to an auto increment (autoinc) field type, Advantage does not verify the uniqueness of the existing integer values. It preserves the existing values and sets the next auto increment value (for the next appended record) to be the maximum existing integer value plus one. You can test the uniqueness of integer field values prior to changing the structure of the table by building a unique index on the field.

Example

ulRetCode = AdsRestructureTable( hDD, "demotable", NULL,

ADS_DEFAULT, ADS_ANSI, ADS_PROPRIETARY_LOCKING,

ADS_IGNORERIGHTS,

"NewCharField,ch,30,(3);NewIntField,integer,(4);",

"Date; Time",

"doublefield,NewNameForDouble,double,10,2; Tax,Tax,double,10,2,(20) " );