AdsCreateTable71

Advantage Client Engine

Creates a new table

Syntax

UNSIGNED32

AdsCreateTable71 (ADSHANDLE hConnect,

UNSIGNED8 *pucName,

UNSIGNED8 *pucDBObjName,

UNSIGNED16 usTableType,

UNSIGNED16 usCharType,

UNSIGNED16 usLockType,

UNSIGNED16 usCheckRights,

UNSIGNED16 usMemoSize,

UNSIGNED8 *pucFields,

UNSIGNED32 ulOptions,

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.

pucDBObjName (I)

The object name to store in the data dictionary if the table is to be added to a data dictionary. This parameter may be NULL. When this parameter is NULL or an empty string, the base name of the table will be stored in the data dictionary. When a table is part of a data dictionary, the object name of the table is used to reference the table. This parameter is useful in the rare case where a table must be created using the same physical table name as an existing table in the data dictionary. See the ulOptions parameter for additional information.

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"

ulOptions (I)

A bit field for defining the options for the created table. The options that do not conflict with each other can be OR’ed together. Allowed values are:

ADS_DEFAULT: No options bit is set. When this value is used as the option and the connection is a database connection, the newly created table may be either a database table or a free table depending on the capability of the connected user. If the connected user is ADSSYS, the newly create table is a database table. If the connected user is not the ADSSYS user, the newly created table is a free table.

ADS_DICTIONARY_BOUND_TABLE: The newly created table should be part of the data dictionary. The connection handle must be a database connection and the user must have been granted the CREATE TABLE permission in the database. An AE_PERMISSION_DENIED error will be returned if the user does not have the permission to create a table in the database. This bit cannot be OR'ed with the ADS_FREE_TABLE or the ADS_TEMP_TABLE bits.

ADS_FREE_TABLE: The newly created table should not be part of the data dictionary. This bit cannot be OR'ed with the ADS_DICTIONARY_BOUND_TABLE bit. This option is required for an ADSSYS user to create a free table.

ADS_TEMP_TABLE: The newly created table is a temporary table that is only available on the current connection. This bit cannot be OR'ed with the ADS_DICTIONARY_BOUND_TABLE bit. See Temporary Tables for more information. When this option is used, the pucName will be the name of the temporary table and it will have no relation to the names of the physical files created by Advantage. Advantage will choose the appropriate location to store the physical files and will delete the files when the connection is closed.

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.

AE_PERMISSION_DENIED

The connected user does not have the permission to create a table in the database. See ADS_DICTIONARY_BOUND_TABLE in the ulOptions parameter above.

Remarks

AdsCreateTable71 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.

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.

See Also

AdsCreateTable

AdsOpenTable

AdsConnect

AdsCloseTable

AdsGetTableHandle