Struct mimir::Connection

pub struct Connection { /* fields omitted */ }

Connection handles are used to represent connections to the database.

Methods

impl Connection

fn add_ref(&self) -> Result<()>

Adds a reference to the connection. This is intended for situations where a reference to the connection needs to be maintained independently of the reference returned when the connection was created.

fn begin_distrib_trans(
    &self,
    format_id: i64,
    txn_id: &str,
    branch_id: &str
) -> Result<()>

Begins a distributed transaction using the specified transaction id (XID) made up of the formatId, transactionId and branchId.

• format_id - the identifier of the format of the XID. A value of -1 indicates that the entire XID is null.
• txn_id - the global transaction id of the XID as a byte string. The maximum length permitted is 64 bytes.
• branch_id - the branch id of the XID as a byte string. The maximum length permitted is 64 bytes.

fn break_execution(&self) -> Result<()>

Performs an immediate (asynchronous) termination of any currently executing function on the server associated with the connection.

fn change_password(
    &self,
    username: &str,
    old_password: &str,
    new_password: &str
) -> Result<()>

Changes the password of the specified user.

• username - the name of the user whose password is to be changed, as a byte string in the encoding used for CHAR data.
• old_password - the old password of the user whose password is to be changed, as a byte string in the encoding used for CHAR data.
• new_password - the new password of the user whose password is to be changed, as a byte string in the encoding used for CHAR data.

fn close(&self, mode: ODPIConnCloseMode, tag: Option<&str>) -> Result<()>

Closes the connection and makes it unusable for further activity.

• mode - one or more of the values from the enumeration ODPIConnCloseMode, OR'ed together.
• tag - a byte string in the encoding used for CHAR data, indicating what tag should be set on the connection when it is released back to the pool. None is also acceptable when indicating that the tag should be cleared. This value is ignored unless the close mode includes the value DPI_MODE_CONN_CLOSE_RETAG.

fn commit(&self) -> Result<()>

Commits the current active transaction.

fn create(
    context: &Context,
    username: Option<&str>,
    password: Option<&str>,
    connect_string: Option<&str>,
    common_create_params: Option<CommonCreate>,
    conn_create_params: Option<ConnCreate>
) -> Result<Connection>

Creates a standalone connection to a database or acquires a connection from a session pool and returns a reference to the connection.

• context - the context handle created earlier using the function Context::create(). If the handle is NULL or invalid an error is returned.
• username - the name of the user used for authenticating the user, as a byte string in the encoding used for CHAR data. None is also acceptable if external authentication is being requested or if credentials were specified when the pool was created.
• password - the password to use for authenticating the user, as a byte string in the encoding used for CHAR data. None is also acceptable if external authentication is being requested or if credentials were specified when the pool was created.
• connect_string - the connect string identifying the database to which a connection is to be established, as a byte string in the encoding used for CHAR data. None is also acceptable for local connections (identified by the environment variable $ORACLE_SID) or when a connection is being acquired from a session pool. This value is ignored when a connection is being acquired from a session pool.
• common_create_params - An optional CommonCreate structure which is used to specify context parameters for connection creation. None is also acceptable in which case all default parameters will be used when creating the connection. This value is ignored when a cquiring a connection from a session pool.
• conn_create_params - An optional ConnCreate structure which is used to specify parameters for connection creation. None is also acceptable in which case all default parameters will be used when creating the connection.

fn deque_object(
    &self,
    queue_name: &str,
    options: &Options,
    props: &Properties
) -> Result<(String, Object)>

Dequeues a message from a queue.

• queue_name - the name of the queue from which the message is to be dequeued, as a byte string in the encoding used for CHAR data.
• options - a reference to the dequeue options that should be used when dequeuing the message from the queue.
• props -- a reference to the message properties that will be populated with information from the message that is dequeued.

fn enqueue_object(
    &self,
    queue_name: &str,
    options: &Options,
    props: &Properties
) -> Result<(String, Object)>

Enqueues a message to a queue.

• queue_name - the name of the queue to which the message is to be enqueued, as a byte string in the encoding used for CHAR data.
• options - a reference to the enqueue options that should be used when enqueuing the message to the queue.
• props - a reference to the message properties that will affect the message that is enqueued.

fn get_current_schema(&self) -> Result<String>

Get the current schema.

fn get_edition(&self) -> Result<String>

Returns the edition that is being used by the connection.

fn get_encoding_info(&self) -> Result<Info>

Returns the encoding information used by the connection. This will be equivalent to the values passed when the standalone connection or session pool was created, or the values retrieved from the environment variables NLS_LANG and NLS_NCHAR.

fn get_external_name(&self) -> Result<String>

Returns the external name that is being used by the connection. This value is used when logging distributed transactions.

fn get_internal_name(&self) -> Result<String>

Returns the internal name that is being used by the connection. This value is used when logging distributed transactions.

fn get_ltxid(&self) -> Result<String>

Returns the logical transaction id for the connection. This value is used in Transaction Guard to determine if the last failed call was completed and if the transaction was committed using the procedure call dbms_app_cont.get_ltxid_outcome().

fn get_object_type(&self, name: &str) -> Result<ObjectType>

Looks up an object type by name in the database and returns a reference to it. The reference should be released as soon as it is no longer needed.

• name - the name of the object type to lookup, as a string in the encoding used for CHAR data.

fn get_server_version(&self) -> Result<Info>

Returns the version information of the Oracle Database to which the connection has been made.

fn get_statement_cache_size(&self) -> Result<u32>

Returns the size of the statement cache, in number of statements.

fn new_deq_options(&self) -> Result<Options>

Returns a reference to a new set of dequeue options, used in dequeuing objects from a queue. The reference should be released as soon as it is no longer needed.

fn new_enq_options(&self) -> Result<Options>

Returns a reference to a new set of enqueue options, used in enqueuing objects into a queue. The reference should be released as soon as it is no longer needed.

fn new_msg_props(&self) -> Result<Properties>

Returns a reference to a new set of message properties, used in enqueuing and dequeuing objects in a queue. The reference should be released as soon as it is no longer needed.

fn new_subscription(
    &self,
    subscr_create_params: SubscrCreate
) -> Result<(u32, Subscription)>

Returns a reference to a subscription which is used for requesting notifications of changes on tables or queries that are made in the database. The reference should be released as soon as it is no longer needed.

fn new_temp_lob(&self, lob_type: ODPIOracleTypeNum) -> Result<Lob>

Returns a reference to a new temporary LOB which may subsequently be written and bound to a statement. The reference should be released as soon as it is no longer needed.

• lob_type - the type of LOB which should be created. It should be one of these values from the enumeration ODPIOracleTypeNum: Clob, NClob or Blob.

fn new_var(
    &self,
    oracle_type_num: ODPIOracleTypeNum,
    native_type_num: ODPINativeTypeNum,
    max_array_size: u32,
    size: u32,
    size_is_bytes: bool,
    is_array: bool
) -> Result<Var>

Returns a reference to a new variable which can be used for binding data to a statement or providing a buffer for querying data from the database. The reference should be released as soon as it is no longer needed.

• oracle_type_num - the type of Oracle data that is to be used. It should be one of the values from the enumeration ODPIOracleTypeNum
• native_type_num - the type of native C data that is to be used. It should be one of the values from the enumeration ODPINativeTypeNum
• max_array_size - the maximum number of rows that can be fetched or bound at one time from the database, or the maximum number of elements that can be stored in a PL/SQL array.
• size - the maximum size of the buffer used for transferring data to/from Oracle. This value is only used for variables transferred as byte strings. Size is either in characters or bytes depending on the value of the size_is_bytes parameter. If the value is in characters, internally the value will be multipled by the maximum number of bytes for each character and that value used instead when determining the necessary buffer size.
• size_is_bytes - boolean value indicating if the size parameter refers to characters or bytes. This flag is only used if the variable refers to character data.
• is_array - boolean value indicating if the variable refers to a PL/SQL array or simply to buffers used for binding or fetching data.

fn ping(&self) -> Result<()>

Pings the database to verify that the connection is still alive.

fn prepare_distrib_trans(&self) -> Result<bool>

Prepares a distributed transaction for commit. This function should only be called after dpiConn_beginDistribTrans() is called and before dpiConn_commit() is called.

fn prepare_stmt(
    &self,
    sql: Option<&str>,
    tag: Option<&str>,
    scrollable: bool
) -> Result<Statement>

Returns a reference to a statement prepared for execution. The reference should be released as soon as it is no longer needed.

• sql - the SQL that is to be prepared for execution, as a string in the encoding used for CHAR data. The value can also be None if the tag parameter is specified.
• tag - the key to be used for searching for the statement in the statement cache, as a string in the encoding used for CHAR data. The value can also be None if the sql parameter is specified.
• scrollable - a boolean indicating if the statement is scrollable or not. If it is scrollable, Statement::scroll() can be used to reposition the cursor; otherwise, rows are retrieved in order from the statement until the rows are exhausted. This value is ignored for statements that do not refer to a query.

fn release(&self) -> Result<()>

Releases a reference to the connection. A count of the references to the connection is maintained and when this count reaches zero, the memory associated with the connection is freed and the connection is closed or released back to the session pool if that has not already taken place using the function close().

fn rollback(&self) -> Result<()>

Rolls back the current active transaction.

fn set_action(&self, action: &str) -> Result<()>

Sets the action attribute on the connection. This is one of the end-to-end tracing attributes that can be tracked in database views, shown in audit trails and seen in tools such as Enterprise Manager.

• action - a string in the encoding used for CHAR data which will be used to set the action attribute.

fn set_client_identifier(&self, id: &str) -> Result<()>

Sets the client identifier attribute on the connection. This is one of the end-to-end tracing attributes that can be tracked in database views, shown in audit trails and seen in tools such as Enterprise Manager.

• id - a string in the encoding used for CHAR data which will be used to set the client identifier attribute.

fn set_client_info(&self, info: &str) -> Result<()>

Sets the client info attribute on the connection. This is one of the end-to-end tracing attributes that can be tracked in database views, shown in audit trails and seen in tools such as Enterprise Manager.

• info - a string in the encoding used for CHAR data which will be used to set the client info attribute.

fn set_current_schema(&self, schema: &str) -> Result<()>

Sets the current schema to be used on the connection. This has the same effect as the SQL statement ALTER SESSION SET CURRENT_SCHEMA. The value be changed when the next call requiring a round trip to the server is performed. If the new schema name does not exist, the same error is returned as when the alter session statement is executed. The new schema name is placed before database objects in statement that you execute that do not already have a schema.

• schema - A string in the encoding used for CHAR data which will be used to set the current schema.

fn set_db_op(&self, op: &str) -> Result<()>

Sets the database operation attribute on the connection. This is one of the end-to-end tracing attributes that can be tracked in database views, shown in audit trails and seen in tools such as Enterprise Manager.

• op - a string in the encoding used for CHAR data which will be used to set the database operation attribute.

fn set_external_name(&self, external_name: &str) -> Result<()>

Sets the external name that is being used by the connection. This value is used when logging distributed transactions.

• external_name - a string in the encoding used for CHAR data which will be used to set the external name.

fn set_internal_name(&self, internal_name: &str) -> Result<()>

Sets the internal name that is being used by the connection. This value is used when logging distributed transactions.

• internal_name - a string in the encoding used for CHAR data which will be used to set the internal name.

fn set_module(&self, module: &str) -> Result<()>

Sets the module attribute on the connection. This is one of the end-to-end tracing attributes that can be tracked in database views, shown in audit trails and seen in tools such as Enterprise Manager.

• module - a string in the encoding used for CHAR data which will be used to set the module attribute.

fn set_statement_cache_size(&self, size: u32) -> Result<()>

Sets the size of the statement cache.

• size - the new size of the statement cache, in number of statements.

fn shutdown_database(self, mode: ODPIShutdownMode) -> Result<()>

Shuts down the database. This function must be called twice for the database to be shut down successfully. After calling this function the first time, the SQL statements "alter database close normal" and "alter database dismount" must be executed. Once that is complete this function should be called again with the mode DPI_MODE_SHUTDOWN_FINAL in order to complete the orderly shutdown of the database.

• mode - one of the values from the enumeration ODPIShutdownMode.

fn start_database(self, mode: ODPIStartupMode) -> Result<()>

Starts up a database

• mode - one of the values from the enumeration ODPIStartupMode.

Trait Implementations

impl From<*mut ODPIConn> for Connection

fn from(inner: *mut ODPIConn) -> Connection

Performs the conversion.