Advantage Client Engine

Opens an existing table.



AdsOpenTable (ADSHANDLE hConnect,

UNSIGNED8 *pucName,

UNSIGNED8 *pucAlias,

UNSIGNED16 usTableType,

UNSIGNED16 usCharType,

UNSIGNED16 usLockType,

UNSIGNED16 usCheckRights,

UNSIGNED32 ulOptions,

ADSHANDLE *phTable);


hConnect (I)

Optional connection handle used to open the table. If this is 0, then an appropriate available connection will be used, or a new connection will be opened if one is not available. To open a database table, this parameter must be a database connection handle to the appropriated Advantage Data Dictionary file.

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.

pucAlias (I)

Alias to associate with the table. If NULL, the alias will be the base filename. The alias is limited to 10 characters.

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. Valid values include ADS_ANSI, ADS_OEM, or one of the dynamic collations such as GENERAL_VFP_CI_AS_1252. This indicates the type of character data to be stored in the table and the collation to use when sorting the data. For compatibility with DOS-based CA-Clipper applications, ADS_OEM should be specified when opening DBF tables. 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. 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. 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. See Advantage Locking Modes for more information.

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 your Advantage server guide for more information on Rights Checking.

ulOptions (I)

This is a bit field for defining the options for opening the table. The options can be ORíed together. For example, ADS_EXCLUSIVE | ADS_READONLY. The options are:

ADS_DEFAULT: If no options are needed, this value (0) can be used.

ADS_EXCLUSIVE: Open table for exclusive (non-shared) use. This option is mutually exclusive with the ADS_SHARED option.

ADS_SHARED: Open table for shared use. This option is mutually exclusive with the ADS_EXCLUSIVE option.

ADS_READONLY: Open table for read-only use. If this option is not set, and the table cannot be opened for read/write access due to an OS file access restriction such as CD-ROM drive or the data dictionary user access restriction, the table will be opened with read-only access when such access is allowed by OS or the data dictionary.

ADS_CLIPPER_MEMOS: Strip CA-Clipper style carriage return linefeed character pairs (0x8D 0x0A) from memos. If a memo field contains these characters, they will not be displayable in a Windows application. This option will force the Advantage Client Engine to remove the characters from the memo text.

ADS_REINDEX_ON_COLLATION_MISMATCH: Automatically rebuild indexes when a collation mismatch is detected when opening indexes for this table. Beginning with version 6.2, Advantage stores a collation sequence identifier in the header of Advantage proprietary index (.ADI) files when it creates a new index file. When opening the index again, it can use that identifier to determine if the current collation sequence matches the one used to create the index. If the ADS_REINDEX_ON_COLLATION_MISMATCH option is provided, Advantage will attempt to automatically rebuild the index when it detects that the index was originally built with a different collation sequence. Advantage will be unable to rebuild the index if it has any index orders created with the ADS_CUSTOM option (see AdsCreateIndex, AdsCreateIndex61). It is also not possible to rebuild the index if another user currently has the index open; this can happen when different clients use Advantage Local Server and each client has a different collation sequence. If Advantage is unable to rebuild the index, it will return error code 5175. It is important to note that if the use of this option does trigger an index rebuild, it can slow down the open of the index or table (when using auto-open indexes). For example, if an application is using Advantage Local Server with large tables across a network, an index rebuild may take a considerable amount of time. If any record locks are held by the application on the table that owns this index when this option triggers a reindex, Advantage will release those locks.

ADS_IGNORE_COLLATION_MISMATCH: Ignore collation mismatches when opening index files. A mismatch between the collation sequence used to build an index and the current collation sequence effectively causes the index file to be corrupt. For example, Advantage may not be able to find some keys because they may be sorted differently than they would be according to the current collation sequence. Therefore, an application should only use this option if it plans to immediately rebuild the index file (see AdsReindex, AdsReindex61). If neither this option nor ADS_REINDEX_ON_COLLATION_MISMATCH are specified, then Advantage will return a 5175 error when it detects a collation mismatch and will not open the index file.

ADS_TEMP_TABLE: The table to be opened is a temporary table. When this option is specified, the pucName specifies the name of the tables instead of the physical file name. As an alternative, prefix the table name with a # character (e.g., using #Temp1 as the pucName parameter). This is equivalent to specifying the ADS_TEMP_TABLE option.

phTable (O)

The handle to the table is returned if the table is opened successfully.

Special Return Codes

7079, 7080

The user does not have the proper rights to open the database table.


When opening a free table, if any path information including relative paths such as "..\file.dbf" is included, then the name will be used as given. If no path information is given with pucName, then the following rules are used to find and open the file.

  1. If a default path exists (AdsSetDefault), attempt to open the file in the specified default path.

  2. If a search path exists (AdsSetSearchPath), try each path in the search path.

  3. Try to open the file in the current directory that is controlled via the userís application.

AdsOpenTable is used to open an existing table. 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 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.

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). If ADS_OEM is specified for the usCharType when using ADT tables, it will be changed to ADS_ANSI. ADT tables do not support OEM character sets.

If the table to be opened is a database table, (i.e., usTableType parameter is ADS_DEFAULT) there may be additional features and limitations on the use of the returned table handle. Properties defined for the table in the data dictionary are automatically available for the database table. See AdsDDSetTableProperty and AdsDDSetFieldProperty for more information. Adding or removing an index with the table will modify the definitions stored in the database.


Click Here

See Also