DbiAddAlias

C syntax

DBIResult DbiAddAlias( [hCfg], pszAliasName, pszDriverType, pszParams, bPersistent );

Delphi syntax

function DbiAddAlias (hCfg: hDBICfg; pszAliasName: PChar; pszDriverType: PChar; pszParams: PChar; bPersist: Bool): DBIResult stdcall;

Description

Adds an alias to the configuration file specified by the parameter hCfg.

Parameters

hCfg Type: hDBICfg (Input)
Specifies the configuration file to be used. This parameter is required to be NULL, indicating that the new alias is added to the configuration file for the current session.

pszAliasName Type: pCHAR (Input)
Pointer to the alias name. This is the name of the new alias that is to be added.

pszDriverType Type: pCHAR (Input)
Pointer to the driver type. This is the driver type for the new alias that is to be added. If this parameter is NULL, the alias will be for the STANDARD database. If szPARADOX, szDBASE, or szASCII are passed, this will add an entry in the STANDARD database alias generated to indicate that this will be the preferred driver type. If a driver name is an ODBC driver not previously added to the configuration file being modified, the BDE adds it automatically.

pszParams Type: pCHAR (Input)
Pointer to a list of optional parameters. This is a list defined as follows:

"AliasOption: Option Data[;AliasOption: Option Data][;...]"

AliasOption must correspond to a value retrieved by DbiOpenCfgInfoList. For a STANDARD database alias, the only valid parameter is PATH, all others will be ignored (no errors). If the parameter setting contains a semicolon (;) , enclose the entire setting in quotes ("Option Data";).

bPersistent Type: BOOL (Input)
This determines the scope of the new alias:
TRUE Stored in the configuration file for future sessions.
FALSE For use only in this session.

Examples

To set the path for a STANDARD database use:

"PATH:c:\mydata"

To set the server name and user name for a SQL driver use:

"SERVER NAME: server:/path/database;USER NAME: myname"

Usage

The alias added by this function will have whatever default values are associated with the driver specified unless they are specifically mentioned in the pszParams parameter. For a standard database alias, all entries in pszParams except PATH will be ignored. You can use DbiOpenCfgInfoList to modify the default values after DbiAddAlias has been called.

ODBC: DbiAddAlias automatically adds ODBC drivers and data sources as BDE aliases to the active session when they aren't currently stored in the configuration file. The BDE also supports ODBC 3 drivers.

Note:

All changes you make to the current session are also applied to any sessions with sesCFGUPDATE set to ON.

Prerequisites

DbiInit must be called prior to calling DbiAddAlias.

DbiResult	Meaning
DBIERR_INVALIDPARAM	Null or invalid alias name. Invalid characters include a colon (":") and backslash ("\"). szASCII, szDBASE, and szPARADOX are entered as a STANDARD alias with the respective default driver.
DBIERR_NONE	The alias was added successfully.
DBIERR_NAMENOTUNIQUE	Another alias with the same name already exists (applicable only when bPersistent is TRUE).
DBIERR_OBJNOTFOUND	One (or more) of the optional parameters passed in through pszParams was not found as a valid type in the driver section of the configuration file.
DBIERR_UNKNOWNDRIVER	No driver name found in configuration file matching pszDriverType.