<< Click to Display Table of Contents >> Navigation:  »No topics above this level« DbiOpenCfgInfoList

C syntax

DBIResult DBIFN DbiOpenCfgInfoList (hCfg, eOpenMode, eConfigMode, pszCfgPath, phCur);

Delphi syntax

function DbiOpenCfgInfoList (hCfg: hDBICfg; eOpenMode: DBIOpenMode; eConfigMode: CFGMode; pszCfgPath: PChar; var hCur: hDBICur): DBIResult stdcall;

Description

DbiOpenCfgInfoList returns a handle to a list of all the nodes in the BDE configuration file accessible by the specified path.

Parameters

hCfg                Type: hDBICfg                (Input)
Specifies the configuration file handle; must be NULL.

eOpenMode                Type: DBIOpenMode                (Input)
Specifies the open mode; choose dbiREADWRITE or dbiREADONLY.

eConfigMode                Type: CFGMode                (Input)
Specifies the configuration mode; only cfgPersistent is supported.

pszCfgPath                Type: pCHAR                (Input)
Pointer to the configuration file path name used to locate a piece of information within the configuration file. The path name starts at the root, denoted by a backslash (\). As many levels as necessary to locate the target piece of information may be specified. Each node specified in the path name must have at least one subnode or an error results. The path name must be NULL-terminated. See the Usage section for an example. If the path is a valid ODBC driver name and data source not stored in the configuration file, the default parameter settings for that driver and data source are returned.

phCur                Type: phDBICur                (Output)
Pointer to a cursor handle.

Usage

This function can be used to retrieve information from the configuration file about BDE drivers, internal buffers, and aliases by supplying a known path in pszConfigPath.

DbiOpenCfgInfoList accesses the same configuration file that was used when BDE was initialized. If no configuration file was used during DbiInit, an empty table is returned.

The full path name is supplied by pszConfigPath, starting at the root, and then subsequently specifying the name of a node, a backslash (\), one of the node's subnodes, and so on until the desired level is reached. For example, to retrieve the values used to initialize BDE, the pszConfigPath passed in would be:

phCur then receives the handle to a table containing a list of records, each representing a node accessible by the specified path name. The cursor is used by subsequent record manipulation calls such as DbiGetNextRecord and DbiGetPriorRecord. DbiGetCursorProps can be used to allocate the proper record size or the client application can allocate the size of the CFGDesc structure. After the record is retrieved it can be cast with the CFGDesc type definition and used as if it is a CFGDesc C language structure.

DbiModifyRecord can also be used with the cursor with the following restrictions:

This function can also be used to build a path name to a target piece of information within the configuration file, when the path name is not known. In that case, the first call to DbiOpenCfgInfoList is passed with pszConfigPath set to backslash (\). The table returned lists all the nodes accessible to the root. If these nodes do not contain the target information (in szText[MAXSCFLDLEN]), subsequent calls to DbiOpenCfgInfoList can be made, each one extending the path name to access one level deeper in the configuration file.

You can use the read-only property sesCFGNAME to retrieve the name of the configuration file used by the active session.

Prerequisites

The database engine must be initialized with a configuration file.

See also

DbiInit, DbiOpenDatabaseList, DbiOpenDriverList