Add Method

Add Method (McDBDatabases)

Description

Adds a new database definition (i.e. mapping) to this McDBDatabases collection and returns its corresponding McDBDatabase instance.

Return Type

A McDBDatabase object.

Syntax

object.Add (Logical, [PhysicalName], [Server])

The Add Method syntax has these parts:

Part	Description
object	An expression evaluating to an object of type McDBDatabases.
Logical	Required. A String value. The logical name for the database mapping. This value must be unique within this collection, and will be used to uniquely identify a database mapping. That is, it is NOT possible to have two databases (i.e. two different physical paths) with the same logical name. This value is case-sensitive. That is Database and DataBASE are different, discrete Logical Names.
PhysicalName	Optional. A String value. A fully qualified path to the database. For LOCAL databases, this path should specify a directory which contains the actual database files. If this parameter is omitted or empty, the local configuration file is searched for a mapping with the specified Logical Name. If Server is not LOCAL, this value is the Logical Name of the database in the configuration file on the database server.
Server	Optional. A String value. The DNS name or IP Address of the machine serving the database (to specify a remote database served by an IQbase database server). If this parameter is not passed in, its value will be retrieved from the local configuration file, if present. If no suitable mapping can be found, a LOCAL server is assumed.

Remarks

The McDBDatabase.Open method of the returned McDBDatabase will only succeed if the database specified already exists. That is, no testing for the existence of database files matching the specification passed is done. This method is not capable of creating database files, but is capable of creating configuration entries corresponding to a database that was copied or moved manually to a new location.

Exceptions

Error Value Description

E_INVALIDARG &H80070057 One of the arguments is invalid. Either no PhysicalName was passed in for a database, and no mapping for the Logical name is present in the local configuration file, or the Logical or Server name passed contains an illegal character (e.g. a colon “:”)

E_UNEXPECTED &H8001FFFF A framework error occurred modifying the local configuration file (McDBLib.Cfg).

E_FAIL &H80004005 The Logical name is not unique within this collection.

Notes

Any mapping created by this call will overwrite an existing mapping for the same Logical database name in the local configuration file.