Database connection functions

Database connection functions let you make and manage any connection, including the Dreamweaver-provided ADO, ColdFusion, and JDBC connections. These functions interface with the Connection Manager only; they do not access a database. For functions that access a database, see "Database access functions" on page 590.

MMDB.deleteConnection()

Availability

Dreamweaver MX.

Description

This function deletes the named database connection.

Arguments

 connName 

• The connName argument is the name of the database connection as it is specified in the Connection Manager. This argument identifies, by name, the database connection to delete.

Returns

Nothing.

Example

The following example deletes a database connection:

 function clickedDelete() {   var selectedObj = dw.serverComponents.getSelectedNode();   if (selectedObj && selectedObj.objectType=="Connection")   {     var connRec = MMDB.getConnection(selectedObj.name);     if (connRec)     {       MMDB.deleteConnection(selectedObj.name);       dw.serverComponents.refresh();     }   } } 

MMDB.getColdFusionDsnList()

Availability

Dreamweaver UltraDev 4.

Description

This function gets the ColdFusion data source names (DSNs) from the site server, using the geTRDSUserName() and getrDSPassword() functions.

Arguments

None.

Returns

An array that contains the ColdFusion DSNs that are defined on the server for the current site.

MMDB.getConnection()

Availability

Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.

Description

This function gets a named connection object.

Arguments

 name 

• The name argument is a string variable that specifies the name of the connection that you want to reference.

Returns

A reference to a named connection object. Connection objects contain the following properties:

Property	Description
name	Connection name
type	Indicates, if useHTTP is a value of false, which DLL to use for connecting to a database at runtime
string	Runtime ADO connection string or JDBC URL
dsn	ColdFusion DSN
driver	Runtime JDBC driver
username	Runtime user name
password	Runtime password
useHTTP	String that contains either a TRue or false value, specifying whether to use a remote driver (HTTP connection) at design time; otherwise, use a local driver (DLL)
includePattern	Regular expression used to find the file include statement on the page during Live Data and Preview In Browser
variables	Array of page variable names and their corresponding values used during Live Data and Preview In Browser
catalog	Used to restrict the metadata that appears (for more information, see "MMDB.getProcedures()" on page 594)
schema	Used to restrict the metadata that appears (for more information, see "MMDB.getProcedures()" on page 594)
filename	Filename of dialog box that was used to create the connection

NOTE

These properties are the standard ones that Dreamweaver implements. Developers can define their connection types and add new properties to this standard set or provide a different set of properties.

MMDB.getConnectionList()

Availability

Dreamweaver UltraDev 1.

Description

This function gets a list of all the connection strings that are defined in the Connection Manager.

Arguments

None.

Returns

An array of strings where each string is the name of a connection as it appears in the Connection Manager.

Example

A call to MMDB.getConnectionList() can return the strings ["EmpDB", "Test", TestEmp"].

MMDB.getConnectionName()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the connection name that corresponds to the specified connection string. This function is useful when you need to reselect a connection name in the user interface (UI) from data on the page.

If you have a connection string that references two drivers, you can specify the connection string and the driver that corresponds to the connection name that you want to return. For example, you can have two connections.

• Connection 1 has the following properties:

   ConnectionString="jdbc:inetdae:velcro-qa-5:1433?database=pubs" DriverName="com.inet.tds.TdsDriver" 

  
  

• Connection 2 has the following properties:

 ConnectionString="jdbc:inetdae:velcro-qa-5:1433?database=pubs" DriverName="com.inet.tds.TdsDriver2" 

The connection strings for Connection 1 and Connection 2 are the same. Connection 2 connects to a more recent version of the tdsDriver driver. You should pass the driver name to this function to fully qualify the connection name you want to return.

Arguments

 connString, {driverName} 

• The connString argument is the connection string that gets the connection name.

• The driverName argument, which is optional, further qualifies the connString argument.

Returns

A connection name string that corresponds to the connection string.

Example

The following code returns the string "EmpDB":

 var connectionName = MMDB.getConnectionName ("dsn=EmpDB;uid=;pwd="); 

MMDB.getConnectionString()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the connection string that is associated with the named connection.

Arguments

 connName 

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A connection string that corresponds to the named connection.

Example

The code var connectionString = MMDB.getConnectionString ("EmpDB") returns different strings for an ADO or JDBC connection.

• For an ADO connection, the following string can return:

   "dsn=EmpDB;uid=;pwd="; 

  
  

• For a JDBC connection, the following string can return:

   "jdbc:inetdae:192.168.64.49:1433?database=pubs&user=JoeUser& password=joesSecret" 

  
  

MMDB.getDriverName()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the driver name that is associated with the specified connection. Only a JDBC connection has a driver name.

Arguments

 connName 

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A string that contains the driver name.

Example

The statement MMDB.getDriverName ("EmpDB"); might return the following string:

 "jdbc/oracle/driver/JdbcOracle" 

MMDB.getDriverUrlTemplateList() (deprecated)

Availability

Dreamweaver UltraDev 4, deprecated in Dreamweaver MX.

NOTE

For Dreamweaver UltraDev 4, the list of JDBC drivers are stored in the connections.xml file, which is located in the Configuration/Connections folder. Each driver has an associated URL template. This function returns the list of JDBC drivers.

For Dreamweaver MX (or later), these drivers and URL templates are hard-coded in the JDBC dialog boxes. In addition, this function is an empty function definition to eliminate undefined-function errors. The following example shows how a JDBC driver and URL template are hard-coded:

 var DEFAULT_DRIVER = "COM.ibm.db2.jdbc.app.DB2Driver"; var DEFAULT_TEMPLATE = "jdbc:db2:[database name]"; 

Dreamweaver has a dialog box for each driver/URL template pair.

In summary, Dreamweaver UltraDev 4 developers need to add a new entry to the XML, and Dreamweaver MX (or later), developers need to implement a new dialog box.

Description

This function gets JDBC Drivers and respective URL templates.

Arguments

None.

Returns

An array that contains JDBC drivers that have been detected on the user's system and their respective URL templates, if they are specified. The array has an even number of elements that contain: Driver1, UrlTemplate1, Driver2, UrlTemplate2, and so on.

MMDB.getLocalDsnList()

Availability

Dreamweaver UltraDev 4.

Description

This function gets ODBC DSNs that are defined on the user's system.

Arguments

None.

Returns

An array that contains the ODBC DSNs that are defined on the user's system.

MMDB.getPassword()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the password that is used for the specified connection.

Arguments

 connName 

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A password string that is associated with the connection name.

Example

The statement MMDB.getPassword ("EmpDB"); might return "joessecret".

MMDB.getRDSPassword()

Availability

Dreamweaver UltraDev 4.

Description

This function gets the Remote Development Services (RDS) password (for use with ColdFusion connections).

Arguments

None.

Returns

A string that contains the RDS password.

MMDB.getRDSUserName()

Availability

Dreamweaver UltraDev 4.

Description

This function gets the RDS user name (for use with ColdFusion connections).

Arguments

None.

Returns

A string that contains the RDS user name.

MMDB.getRemoteDsnList()

Availability

Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.

Description

This function gets the ODBC DSNs from the site server. The geTRDSUserName() and getrDSPassword() functions are used when the server model of the current site is ColdFusion. This function provides an option for a developer to specify a URL parameter string to be appended to the Remote Connectivity URL that MMDB.getRemoteDsnList() generates. If the developer provides a parameter string, this function passes it to the HTTP connectivity scripts.

Arguments

 {urlParams} 

• The urlParams argument, which is optional, is a string that contains a list of name=value expressions, which are separated by ampersand (&) characters. You must not enclose values with quotes. Some characters, such as the space in the value Hello World, need to be encoded. The following example shows a valid sample argument that you can pass to MMDB.getRemoteDsnList():

   a=1&b=Hello%20World 

  
  

Returns

Returns an array that contains the ODBC DSNs that are defined on the server for the current site.

MMDB.getRuntimeConnectionType()

Availability

Dreamweaver UltraDev 1.

Description

This function returns the runtime connection type of the specified connection name.

Arguments

 connName 

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A string that corresponds to the connection type. This function can return one of the following values: "ADO", "ADODSN", "JDBC", or "CFDSN".

Example

The following code returns the string "ADO" for an ADO connection:

 var connectionType = MMDB.getRuntimeConnectionType ("EmpDB") 

MMDB.getUserName()

Availability

Dreamweaver UltraDev 1.

Description

This function returns a user name for the specified connection.

Arguments

 connName 

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A user name string that is associated with the connection name.

Example

The statement MMDB.getUserName ("EmpDB"); might return "amit".

MMDB.hasConnectionWithName()

Availability

Dreamweaver UltraDev 4.

Description

This function determines whether a connection of a given name exists.

Arguments

 name 

• The name argument is the connection name.

Returns

Returns a Boolean value: true indicates that a connection with the specified name exists; false otherwise.

MMDB.needToPromptForRdsInfo()

Availability

Dreamweaver MX.

Description

This function determines whether Dreamweaver should open the RDS Login Information dialog box.

Arguments

 bForce 

• The bForce argument is a Boolean value; true indicates that the user who has previously cancelled out of the RDS login dialog box still needs to be prompted for RDS login information.

Returns

A Boolean value: TRue indicates that the user needs to be prompted for RDS login information; false otherwise.

MMDB.needToRefreshColdFusionDsnList()

Availability

Dreamweaver MX.

Description

This function tells the Connection Manager to empty the cache and get the ColdFusion data source list from the application server the next time a user requests the list.

Arguments

None.

Returns

Nothing.

MMDB.popupConnection()

Availability

Dreamweaver MX.

Description

This function invokes a connection dialog box. This function has the following three signatures:

• If the argument list consists only of dialogFileName (a string), the popupConnection() function makes Dreamweaver open the Connection dialog box so you can define a new connection.

• If the argument list consists only of connRec (a connection reference), the popupConnection() function makes Dreamweaver launch the Connection dialog box in edit mode for editing the named connection. In this mode, the name text field is dimmed.

• If the argument list consists of connRec and the Boolean value bDuplicate, the popupConnection() function makes Dreamweaver open the Connection dialog box in duplicate mode. In this mode, the name text field is blanked out, and the remaining properties are copied to define a duplicate connection.

Arguments

 dialogFileName 

or

 connRec 

or

 connrec, bDuplicate 

• The dialogFileName argument is a string that contains the name of an HTML file that resides in the Configuration/Connections/server-model folder. This HTML file defines the dialog box that creates a connection. This file must implement three JavaScript API functions: findConnection(), inspectConnection(), and applyConnection(). Typically, you create a JavaScript file that implements these functions and then include that file in the HTML file. (For more information on creating a connection, see "The Database Connectivity API" on page 605.)

• The connRec argument is a reference to an existing Connection object.

• The bDuplicate argument is a Boolean value.

Returns

Nothing. The defined connection dialog box appears.

MMDB.setRDSPassword()

Availability

Dreamweaver UltraDev 4.

Description

This function sets the RDS password.

Arguments

 password 

• The password argument is a string that contains the RDS password.

Returns

Nothing.

MMDB.setRDSUserName()

Availability

Dreamweaver UltraDev 4.

Description

This function sets the RDS user name.

Arguments

 username 

• The username argument is a valid RDS user name.

Returns

Nothing.

MMDB.showColdFusionAdmin()

Availability

Dreamweaver MX.

Description

This function displays the ColdFusion Administrator dialog box.

Arguments

None.

Returns

Nothing. The ColdFusion Administrator dialog box appears.

MMDB.showConnectionMgrDialog()

Availability

Dreamweaver UltraDev 1.

Description

This function displays the Connection Manager dialog box.

Arguments

None.

Returns

Nothing. The Connection Manager dialog box appears.

MMDB.showOdbcDialog()

Availability

Dreamweaver UltraDev 4 (Windows only).

Description

This function displays the System ODBC Administration dialog box or the ODBC Data Source Administrator dialog box.

Arguments

None.

Returns

Nothing. The System ODBC Administration dialog box or the ODBC Data Source Administrator dialog box appears.

MMDB.showRdsUserDialog()

Availability

Dreamweaver UltraDev 4.

Description

This function displays the RDS user name and password dialog box.

Arguments

 username, password 

• The username argument is the initial user name.

• The password argument is the initial password.

Returns

An object that contains the new values in the username and password properties. If either property is not defined, it indicates that the user cancelled the dialog box.

MMDB.showRestrictDialog()

Availability

Dreamweaver UltraDev 4.

Description

This function displays the Restrict dialog box.

Arguments

 catalog, schema 

• The catalog argument is the initial catalog value.

• The schema argument is the initial schema value.

Returns

An object that contains the new values in the catalog and schema properties. If either property is not defined, it indicates that the user cancelled the dialog box.

MMDB.testConnection()

Availability

Dreamweaver UltraDev 4.

Description

This function tests connection settings. It displays a modal dialog box that describes the results.

Arguments

 serverPropertiesArray 

This function expects a single argument, an array object that contains values from the following list, which are appropriate for the current server model. For properties that do not apply to the connection being tested, set them to empty ("").

• The type argument indicates, when useHTTP is a false value, which DLL to use for connecting to a database at design time to test connection settings.

• The string argument is the ADO connection string or JDBC URL.

• The dsn argument is the data source name.

• The driver argument is the JDBC driver.

• The username argument is the user name.

• The password argument is the password.

• The useHTTP argument is a Boolean value. A value of true specifies that Dreamweaver should use an HTTP connection at design time; otherwise, Dreamweaver uses a DLL.

Returns

A Boolean value: true if the connection test is successful; false otherwise.