Advantage Client Engine
Finds the first table matching the file mask on the given connection. If called on a dictionary-bound connection, this API will also return the names of tables in linked dictionaries.
UNSIGNED32 ENTRYPOINT AdsFindFirstTable62( ADSHANDLE hConnect,
UNSIGNED8 *pucFileMask,
UNSIGNED8 *pucFirstDD,
UNSIGNED16 *pusDDLen,
UNSIGNED8 *pucFirstFile,
UNSIGNED16 *pusFileLen,
SIGNED32 *plHandle );
hConnect (I) |
Handle of connection. |
pucFileMask (I) |
File mask to use when searching for tables. |
pucFirstDD (O) |
If the table found is in a linked dictionary, the name of the link is returned in this buffer. |
pusDDLen (I/O) |
Length of pucFirstDD on input, length of returned data on output. |
pucFirstFile (O) |
First matching tablename is returned in this buffer. |
pusFileLen (I/O) |
Length of pucFirstFile on input, length of returned data on output. |
plHandle (O) |
Handle to use in subsequent calls to AdsFindNextTable. |
AE_NO_FILE_FOUND |
No tables were found. |
Use AdsFindFirstTable62, in conjunction with AdsFindNextTable62 and AdsFindClose, to search for either physical file names matching a given file mask (such as "*.adt"), or to find "logical" table names in an Advantage Data Dictionary, where a "logical" table name is the name given to a table or a view in the data dictionary.
This API works in the same fashion as AdsFindFirstTable, but AdsFindFirstTable62 is also capable of finding tables in linked dictionaries. See Using Tables from Multiple Data Dictionaries for more information on linked dictionaries.
To find logical table names in an Advantage Data Dictionary, the hConnect parameter must be a database connection, and the pucFileMask parameter must be either NULL or an empty string. If you are not using a database connection or the pucFileMask is neither NULL nor an empty string, the API will try to find physical files matching the given file mask.
How the existence check for a file is done by Advantage can depend on many factors, including whether using a database connection or free connection and the Advantage server type to which you are connected. Those variations are discussed below:
If a logical table exists in the data dictionary (when using a database connection), this function will return AE_SUCCESS (0). Otherwise, it is assumed no files exist, and AE_NO_FILE_FOUND is returned.
If a logical table exists in the data dictionary (when using a database connection), this function will return AE_SUCCESS (0). Otherwise, a non-Advantage, low-level file access function is called from the client to check for existence of a file matching the pucFileMask. If attempting to find a file on a server, this function cannot override normal access rights imposed by that server. If the client has access rights to a file matching the pucFileMask, and it exists, AE_SUCCESS (0) will be returned. If no file matching the pucFileMask exists, or if the client does not have access rights to an existing file matching the pucFileMask, this function will return AE_NO_FILE_FOUND.
If the function returns AE_SUCCESS, the first file name will be returned in pucFirstFile, and pusFileLen will contain the length of that file name. If a table is found in a linked dictionary, the link name is returned in pucFirstDD, and pusDDLen will contain the length of that link name. AdsFindNextTable62 can be used to retrieve the next file name. Call AdsFindClose when your work with the find handle (plHandle) is complete.
usLen = ADS_MAX_TABLE_NAME;
usAliasLen = ADS_MAX_OBJECT_NAME;
ulRetVal = AdsFindFirstTable62( hConn, aucTableMask,
aucDictionaryAlias, &usAliasLen,
aucTable, &usLen, &hFindHandle );
if ( (ulRetVal != AE_NO_FILE_FOUND) && (ulRetVal != AE_SUCCESS) )
return ulRetVal;
while ( ulRetVal != AE_NO_FILE_FOUND )
{
// Do your work with aucDictionaryAlias and aucTable here...
// now get the next table
usLen = ADS_MAX_TABLE_NAME;
usAliasLen = ADS_MAX_OBJECT_NAME;
ulRetVal = AdsFindNextTable62( hConn, hFindHandle,
aucDictionaryAlias, &usAliasLen, aucTable, &usLen );
if ( (ulRetVal != AE_NO_FILE_FOUND) && (ulRetVal != AE_SUCCESS) )
return ulRetVal;
}
AdsFindClose( hConn, hFindHandle );