OracleDatabase Class

An OracleDatabase object represents an Oracle Database instance.

Class Inheritance

System.Object

  Oracle.DataAccess.Client.OracleDatabase

Declaration

// C#
public sealed class OracleDatabase : IDisposable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Example

// C#

using System;
using Oracle.DataAccess.Client;
 
namespace Startup
{
  class Test
  {
    static void Main()
    {
      OracleConnection con = null;
      OracleDatabase db = null;
      string constring = "dba privilege=sysdba;user id=scott;password=tiger;data source=oracle";
 
      try
      {
        // Open a connection to see if the DB is up
        con = new OracleConnection(constring);
        con.Open();
 
        Console.WriteLine("The Oracle database is already up.");
      }
      catch (OracleException ex)
      {
        // If the database is down, start up the DB
        if (ex.Number == 1034)
        {
          Console.WriteLine("The Oracle database is down.");
 
          // Create an instance of an OracleDatbase object
          db = new OracleDatabase(constring);
 
          // Start up the database
          db.Startup();
 
          Console.WriteLine("The Oracle database is now up.");
 
          // Executing Startup() is the same as the following:
          // db.Startup(OracleDBStartupMode.NoRestriction, null, true);
          // which is also the same as:
          // db.Startup(OracleDBStartupMode.NoRestriction, null, false);
          // db.ExecuteNonQuery("ALTER DATABASE MOUNT");
          // db.ExecuteNonQuery("ALTER DATABASE OPEN");
 
          // Dispose the OracleDatabase object
          db.Dispose();
        }
        else
        {
          Console.WriteLine("Error: " + ex.Message);
        }
      }
      finally
      {
        // Dispose the OracleConnetion object
        con.Dispose();
      }
    }
  }
}

Requirements

Namespace: Oracle.DataAccess.Client

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4

OracleDatabase Members

OracleDatabase members are listed in the following tables.

OracleDatabase Constructors

The OracleDatabase constructor is listed in Table 5-38.

OracleDatabase Properties

The OracleDatabase properties are listed in Table 5-39.

OracleDatabase Public Methods

The OracleDatabase public methods are listed in Table 5-40.

OracleDatabase Constructor

The OracleDatabase constructor instantiates a new instance of the OracleDatabase class using the supplied connection string.

Declaration

// C#
public OracleDatabase(String connetionString);

Parameters

• connectionString

  The connection information used to connect to the Oracle Database instance.

Remarks

The connectionString follows the same format used by the OracleConnection object. However, the OracleDatabase constructor accepts only the user id, password, data source, and dba privilege connection string attributes. All other attribute values are ignored. The supplied connectionString must contain the dba privilege connection string attribute that is set to either SYSDBA or SYSOPER.

The OracleDatabase object creates a connection upon construction and remains connected throughout its lifetime. The connection is destroyed when the OracleDatabase object is disposed. This connection is not pooled to be used by another OracleDatabase object.

OracleDatabase Properties

The OracleDatabase properties are listed in Table 5-41.

ServerVersion

This property returns the database version number of the Oracle Database instance to which the connection is made.

Declaration

Public string ServerVersion {get;}

Property value

Returns the database version of the Oracle Database instance.

OracleDatabase Public Methods

The OracleDatabase public methods are listed in Table 5-42.

ExecuteNonQuery

This method executes the supplied non-SELECT statement against the database.

Declaration

// C#
public void ExecuteNonQuery(string sql);

Exceptions

OracleException - The command execution has failed.

Remarks

This method is meant for execution of DDL statements such as ALTER DATABASE statements to OPEN and MOUNT the database, for example. This method should not be used to execute SQL SELECT statements. This method does not support any parameter binding.

Shutdown

Shutdown methods shut down a database instance.

Overload List

• Shutdown()

  This method shuts down the database.

• Shutdown(OracleDBShutdownMode, bool)

  This method shuts down the database using the specified mode.

Shutdown()

This method shuts down the database.

Declaration

// C#
public void Shutdown();

Exceptions

OracleException - The database shutdown request has failed.

Remarks

This method shuts down a database instance in the OracleDBShutdownMode.Default mode. New connections are refused, and the method waits for the existing connections to end.

After the connections have closed, the method closes the database, dismounts the database, and shuts down the instance using the OracleDBShutdownMode.Final mode.

This method does not throw exceptions for cases where the database has been already closed, dismounted, or shutdown appropriately. If other errors are encountered, then an exception is thrown.

Invoking this method against an Oracle Real Application Clusters (Oracle RAC) database shuts down only that database instance to which the OracleDatabase object is connected.

Shutdown(OracleDBShutdownMode, bool)

This method shuts down the database instance using the specified mode.

Declaration

//C#
public void Shutdown(OracleDBShutdownMode shutdownMode, bool bCloseDismountAndFinalize);

Parameters

• shutdownMode

  A OracleDBShutdownMode enumeration value.

• bCloseDismountAndFinalize

  A boolean signifying whether the database is to be closed, dismounted, and finalized.

Exceptions

OracleException - The database shutdown request has failed.

Remarks

This method shuts down a database instance in the specified mode. If the bCloseDismountAndFinalize parameter is true, then the method also closes the database, dismounts the database, and shuts down the instance using the OracleDBShutdownMode.Final mode.

If the bCloseDismountAndFinalize parameter is true, then this method does not throw exceptions for cases where the database has been already closed, dismounted, or shutdown appropriately. If other errors are encountered, then an exception is thrown.

If the bCloseDismountAndFinalize parameter is false, then the application needs to explicitly close and dismount the database. The application can then reinvoke the method using the OracleDBShutdownMode.Final mode to properly shut down the database. For example, if db is an instance of the OracleDatabase class, then the application invokes the following:

1. db.Shutdown(OracleDBShutdownMode.Default, false);

2. db.ExecuteNonQuery("ALTER DATABASE CLOSE NORMAL");

3. db.ExecuteNonQuery("ALTER DATABASE DISMOUNT");

4. db.Shutdown(OracleDBShutdownMode.Final);

If the specified shutdownMode is OracleDBShutdownMode.Abort, then the value of the bCloseDismountAndFinalize input parameter is ignored, as the Abort mode requires the database to be closed, dismounted, and finalized.

Invoking this method against an Oracle Real Application Clusters (Oracle RAC) database shuts down only that database instance to which the OracleDatabase object is connected.

Example

using System;
using Oracle.DataAccess.Client;
 
namespace Shutdown
{
  class Test
  {
    static void Main()
    {
      OracleConnection con = null;
      OracleDatabase db = null;
      string constring = "user id=scott;password=tiger;data source=oracle;" +
        "pooling=false;dba privilege=sysdba";
 
      try
      {
        // Open a connection to see if the DB is up;
        con = new OracleConnection(constring);
        con.Open();
 
        Console.WriteLine("The Oracle database is currently up.");
 
        // If open succeeds, we know that the database is up.
        // We have to dispose the connection so that we can
        //   shutdown the database.
        con.Dispose();
 
        // Shutdown the database
        db = new OracleDatabase(constring);
        db.Shutdown();
 
        Console.WriteLine("The Oracle database is shut down.");
 
        // Executing Shutdown() above is the same as the following:
        // db.Shutdown(OracleDBShutdownMode.Default, false);
        // db.ExecuteNonQuery("ALTER DATABASE CLOSE NORMAL");
        // db.ExecuteNonQuery("ALTER DATABASE DISMOUNT");
        // db.Shutdown(OracleDBShutdownMode.Final);
 
        // Dispose the OracleDatabase object
        db.Dispose();
      }
      catch (OracleException ex)
      {
        Console.WriteLine("An error has occurred: {0}", ex.Message);
      }
    }
  }
}

Startup

Startup methods enable a user with database administrator privileges to start a database instance.

Overload List

• Startup()

  This method starts a database instance using the server-side parameter file.

• Startup(OracleDBStartupMode, string, bool)

  This method starts a database instance using the client-side parameter file.

Startup()

This method starts up the database.

Declaration

// C#
public void Startup();

Exceptions

OracleException - The database startup request has failed.

Remarks

This method starts a database instance in the OracleDbStartupMode.Normal mode using the server-side parameter file (spfile). After the database is successfully started, this method also executes the ALTER DATABASE MOUNT and ALTER DATABASE OPEN statements.

This method does not throw exceptions for cases where the database is already mounted, opened, or started appropriately. If other errors are encountered, then an exception is thrown.

Startup(OracleDBStartupMode, string, bool)

This method starts up the database using the specified startup mode.

Declaration

// C#
public void Startup(OracleDbStartupMode startupMode, string pfile, bool bMountAndOpen);

Parameters

• startupMode

  An OracleDBStartupMode enumeration value.

• pfile

  The location and name of the client-side parameter file. For example, "c:\\admin\\init.ora".

  The name of the parameter file varies depending on the operating system. For example, it can be in mixed case or lowercase, or it can have a logical name or a variation of the name init.ora. The default location is usually ORACLE_HOME/dbs or ORACLE_HOME\database.

• bMountAndOpen

  A true/false value signifying whether the database is to be mounted and opened.

Exceptions

OracleException - The database startup request has failed.

Remarks

This method starts a database instance in the specified mode using the specified client-side parameter file. After the database is successfully started, and if bMountAndOpen input parameter is true, this method also executes the ALTER DATABASE MOUNT and ALTER DATABASE OPEN statements.

If bMountAndOpen is true, then this method does not throw an exception for cases where the database is already mounted, opened, or started appropriately. If other errors are encountered, then an exception is thrown.

If bMountAndOpen is false, then the database must be mounted and opened explicitly by the application. For example, if db is an instance of the OracleDatabase class, then the application invokes the following:

1. db.Startup(OracleDBStartupMode.NoRestriction, null, false);

2. db.ExecuteNonQuery("ALTER DATABASE MOUNT");

3. db.ExecuteNonQuery("ALTER DATABASE OPEN");