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

Requirements

Provider ODP.NET, Unmanaged Driver
Assembly Oracle.DataAccess.dll
Namespace Oracle.DataAccess.Client
.NET Framework 3.5, 4.0, 4.5

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();
      }
    }
  }
}

OracleDatabase Members

OracleDatabase members are listed in the following tables.

OracleDatabase Constructors

The OracleDatabase constructor is listed in Table 6-48.

Table 6-48 OracleDatabase Constructors

Constructor Description

OracleDatabase Constructor

Instantiates a new instance of OracleDatabase class using the supplied connection string


OracleDatabase Properties

The OracleDatabase properties are listed in Table 6-49.

Table 6-49 OracleDatabase Properties

Property Description

ServerVersion

Specifies the database version number of the Oracle Database instance to which the connection is made


OracleDatabase Public Methods

The OracleDatabase public methods are listed in Table 6-50.

Table 6-50 OracleDatabase Public Methods

Public Method Description

Dispose

Releases any resources or memory allocated by the object.

ExecuteNonQuery

Executes the supplied non-SELECT statement against the database

Shutdown

Shuts down the database (Overloaded)

Startup

Starts up the database (Overloaded)


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 6-51.

Table 6-51 OracleDatabase Properties

Property Description

ServerVersion

Specifies the database version number of the Oracle Database instance to which the connection is made


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 6-52.

Table 6-52 OracleDatabase Public Methods

Public Method Description

Dispose

Releases any resources or memory allocated by the object.

ExecuteNonQuery

Executes the supplied non-SELECT statement against the database

Shutdown

Shuts down the database (Overloaded)

Startup

Starts up the database (Overloaded)


Dispose

This method releases any resources or memory allocated by the object.

Declaration

// C#
public void Dispose();

Implements

IDisposable

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.

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.

Note:

As the shutdown is effected using the OracleDBShutdownMode.Default mode, the shutdown request may remain pending if there are open connections other than the connection created by the OracleDatabase object.

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);

Note:

  • The OracleDBShutdownMode.Final enumeration value should not be used as the shutdownMode for the initial method invocation. The OracleDBShutdownMode.Final mode should be used only if the database is already closed and dismounted. Otherwise, the method might wait indefinitely.

  • If the specified shutdownMode is OracleDBShutdownMode.Final, then the value of the bCloseDismountAndFinalize input parameter is ignored, as the database should have been closed and dismounted already.

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 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");