AdsCreateTable

Advantage Client Engine

Creates a new table

Syntax

UNSIGNED32

AdsCreateTable (ADSHANDLE hConnect,

UNSIGNED8 *pucName,

UNSIGNED8 *pucAlias,

UNSIGNED16 usTableType,

UNSIGNED16 usCharType,

UNSIGNED16 usLockType,

UNSIGNED16 usCheckRights,

UNSIGNED16 usMemoSize,

UNSIGNED8 *pucFields,

ADSHANDLE *phTable);

Parameters

hConnect (I)

Optional connection handle used to open the table. If this is 0, then an appropriate connection will be chosen if available, otherwise a new connection will be opened.

pucName (I)

Name of the table to create. If this does not contain a path then the default path, (AdsSetDefault ) or the first search path (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.

pucAlias (I)

Alias of the table. If NULL, the alias will be the base name of the table. The Alias is limited to 10 bytes.

usTableType (I)

Type of table. Options are ADS_ADT, ADS_VFP, ADS_NTX, and ADS_CDX.

usCharType (I)

Type of character data in the table. Options are ADS_ANSI, 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.

usLockType (I)

Type of locking to use. Options are ADS_PROPRIETARY_LOCKING, ADS_COMPATIBLE_LOCKING. 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 usTableType is ADS_ADT, this parameter is ignored.

usCheckRights (I)

Indicates if the server is to use rights checking for the file creation. Options are ADS_CHECKRIGHTS, ADS_IGNORERIGHTS. If ADS_CHECKRIGHTS is given, then Advantage Database Server will use the rights of the connected user when creating the file. 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 allows an application developer to allow only Advantage-based applications to access specific data. See your Advantage server guide for more information regarding rights checking.

usMemoSize (I)

Size of memo blocks in memo file if memo fields are used. The value of ADS_DEFAULT (or zero) indicates the default value should be used, which is 8 if usTableType is ADS_ADT, and 64 if usTableType is ADS_CDX or ADS_VFP. This parameter has no effect when using ADS_NTX, which always uses 512. For ADS_ADT, valid values are in the range 8-1024. For ADS_CDX ands ADS_VFP, values are in the range 1-1024. If the value is in the range 1-32, then that value is multiplied by 512 to get the actual block size.

 

pucFields (I)

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

phTable (O)

Returns the handle of the new table if the create is successful.

Special Return Codes

AE_INVALID_FIELDDEF

One of the field definitions for the table is invalid.

Remarks

AdsCreateTable provides the capability to create new tables in the database. The table is left open for usage after it has been created.

The connection handle is used to specify a connection, if necessary. This allows flexibility during transactions because transactions are per connection. Using a separate connection will allow a table to remain outside of a transaction if another connection to the same server is in a transaction. See Transaction Processing for more information.

An alias is used as an alternate method of referring to a table in other commands. It can also be used with expressions.

If the table type is ADS_ADT, then the associated index type is the ADI format, and memos are the ADM format. If the table type is ADS_NTX, then the associated index type is the NTX format, and memos are the DBT format. If the table type is ADS_CDX or ADS_VFP, then IDX and CDX index types are used, and memos are the FPT format.

The pucFields parameter defines the structure of the table. The supported types are shown in the field type specifications linked below. The pucFields definition need only contain as much of the type name as is needed for uniqueness. For example, "name, ch, 25" is a valid definition for a character field.

The total record length must be no greater than 65535. Each record in a DBF table uses one byte for the deleted record indicator, so the longest any field can be is 65534. Each record in an ADT table has an additional 5 bytes, so the longest any field can be in an ADT is 65530. Also note that the record buffer is dynamically allocated when a table is opened or created.

For ADT tables, valid field names are 128 characters or less and can contain any character value except 0 (NULL), ";" (a semi-colon), or "," (a comma). For DBF tables, valid field names are 10 characters or less. Valid characters for field names are the letters a-z and A-Z, digits 0-9, and the underscore "_" character.

For information on the data types supported, see the following:

DBF Field Types and Specifications

ADT Field Types and Specifications

Note When creating an auto-increment field, the initial value can be optionally specified in the third parameter of the creation syntax. For example, "field name, AutoIncrement, 67" will cause the first record in the newly created table to have the value 67 in the auto-increment field.

 

Note usLockType is always set to compatible locking (ADS_COMPATIBLE_LOCKING) when used with Advantage Local Server (ADS_LOCAL_SERVER) with ADT and DBF tables. usLockType is always set to proprietary locking (ADS_PROPRIETARY_LOCKING) when used with the Advantage Database Server (ADS_REMOTE_SERVER) with ADT tables. usCheckRights is ignored when used with Advantage Local Server (ADS_LOCAL_SERVER) with ADT and DBF tables. It is effectively treated as rights checking on (ADS_CHECKRIGHTS). usCharType is always set to ANSI (ADS_ANSI) when used with ADT tables. ADT tables do not support OEM character sets.

Example

Click Here

See Also

AdsOpenTable

AdsConnect

AdsCloseTable

AdsGetTableHandle