- name: dpiAuthMode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the mode to use when authorizing connections to the
database.
members:
- name: DPI_MODE_AUTH_DEFAULT
desc: |
Default value used when creating connections.
- name: DPI_MODE_AUTH_PRELIM
desc: |
Used together with DPI_MODE_AUTH_SYSDBA or DPI_MODE_AUTH_SYSOPER to
authenticate for certain administrative tasks (such as starting up or
shutting down the database).
- name: DPI_MODE_AUTH_SYSASM
desc: |
Authenticates with SYSASM access. The use of this value requires Oracle
Client 12.1 or higher.
- name: DPI_MODE_AUTH_SYSBKP
desc: |
Authenticates with SYSBACKUP access. The use of this value requires
Oracle Client 12.1 or higher.
- name: DPI_MODE_AUTH_SYSDBA
desc: |
Authenticates with SYSDBA access.
- name: DPI_MODE_AUTH_SYSDGD
desc: |
Authenticates with SYSDG access. The use of this value requires Oracle
Client 12.1 or higher.
- name: DPI_MODE_AUTH_SYSKMT
desc: |
Authenticates with SYSKM access. The use of this value requires Oracle
Client 12.1 or higher.
- name: DPI_MODE_AUTH_SYSOPER
desc: |
Authenticates with SYSOPER access.
- name: DPI_MODE_AUTH_SYSRAC
desc: |
Authenticates with SYSRAC access. The use of this value requires Oracle
Client 12.2 or higher.
- name: dpiConnCloseMode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the mode to use when closing connections to the
database.
members:
- name: DPI_MODE_CONN_CLOSE_DEFAULT
desc: |
Default value used when closing connections.
- name: DPI_MODE_CONN_CLOSE_DROP
desc: |
Causes the session to be dropped from the session pool instead of
simply returned to the pool for future use.
- name: DPI_MODE_CONN_CLOSE_RETAG
desc: |
Causes the session to be tagged with the tag information given when the
connection is closed. A value of NULL for the tag will cause the tag to
be cleared.
- name: dpiCreateMode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the mode to use when creating connections to the
database. Note that the OCI objects mode is always enabled.
members:
- name: DPI_MODE_CREATE_DEFAULT
desc: |
Default value used when creating connections.
- name: DPI_MODE_CREATE_EVENTS
desc: |
Enables events mode which is required for the use of advanced queuing
(AQ) and continuous query notification (CQN).
- name: DPI_MODE_CREATE_THREADED
desc: |
Enables threaded mode. Internal OCI structures not exposed to the user
are protected from concurrent access by multiple threads. Error
information is also managed in thread local storage.
- name: dpiDeqMode
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the modes that are possible when dequeuing messages
from a queue.
members:
- name: DPI_MODE_DEQ_BROWSE
desc: |
Read the message without acquiring a lock on the message (equivalent
to a SELECT statement).
- name: DPI_MODE_DEQ_LOCKED
desc: |
Read the message and obtain a write lock on the message (equivalent
to a SELECT FOR UPDATE statement).
- name: DPI_MODE_DEQ_REMOVE
desc: |
Read the message and update or delete it. This is the default mode.
Note that the message may be retained in the queue table based on
retention properties.
- name: DPI_MODE_DEQ_REMOVE_NO_DATA
desc: |
Confirms receipt of the message but does not deliver the actual message
content.
- name: dpiDeqNavigation
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the method used for determining which message is to
be dequeued from a queue.
members:
- name: DPI_DEQ_NAV_FIRST_MSG
desc: |
Retrieves the first available message that matches the search criteria.
This resets the position to the beginning of the queue.
- name: DPI_DEQ_NAV_NEXT_MSG
desc: |
Retrieves the next available message that matches the search criteria.
This is the default method.
- name: DPI_DEQ_NAV_NEXT_TRANSACTION
desc: |
Skips the remainder of the current transaction group (if any) and
retrieves the first message of the next transaction group. This option
can only be used if message grouping is enabled for the queue.
- name: dpiEventType
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the types of events that can take place. The event
type is part of the messages that are sent to subscriptions.
members:
- name: DPI_EVENT_AQ
desc: |
Indicates that a queue has messages available to dequeue.
- name: DPI_EVENT_DEREG
desc: |
Indicates that a subscription is no longer registered with the database
and will no longer generate events.
- name: DPI_EVENT_NONE
desc: |
Indicates that no event has taken place.
- name: DPI_EVENT_OBJCHANGE
desc: |
Indicates that an object change has taken place.
- name: DPI_EVENT_QUERYCHANGE
desc: |
Indicates that a query change has taken place.
- name: DPI_EVENT_SHUTDOWN
desc: |
Indicates that a database is being shut down.
- name: DPI_EVENT_SHUTDOWN_ANY
desc: |
Indicates that an instance of Oracle Real Application Clusters (RAC) is
being shut down.
- name: DPI_EVENT_STARTUP
desc: |
Indicates that a database is being started up.
- name: dpiExecMode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the available modes for executing statements
using [`dpiStmt_execute()`] and [`dpiStmt_executeMany()`].
members:
- name: DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS
desc: |
Enable getting row counts for each DML operation when performing an
array DML execution. The actual row counts can be retrieved using the
function [`dpiStmt_getRowCounts()`].
- name: DPI_MODE_EXEC_BATCH_ERRORS
desc: |
Enable batch error mode. This permits an an array DML operation to
succeed even if some of the individual operations fail. The errors can
be retrieved using the function [`dpiStmt_getBatchErrors()`].
- name: DPI_MODE_EXEC_COMMIT_ON_SUCCESS
desc: |
If execution completes successfully, the current active transaction is
committed.
- name: DPI_MODE_EXEC_DEFAULT
desc: |
Default mode for execution. Metadata is made available after queries
are executed.
- name: DPI_MODE_EXEC_DESCRIBE_ONLY
desc: |
Do not execute the statement but simply acquire the metadata for the
query.
- name: DPI_MODE_EXEC_PARSE_ONLY
desc: |
Do not execute the statement but only parse it and return any parse
errors. Note that using this mode with a DDL statement will result in
the statement being executed.
- name: dpiFetchMode
kind: enum
underlying_type: uint16_t
desc: |
This enumeration identifies the mode to use when scrolling the cursor to a new
location using the function [`dpiStmt_scroll()`].
members:
- name: DPI_MODE_FETCH_ABSOLUTE
desc: |
Scroll the cursor to the row identified by the offset parameter using
absolute positioning.
- name: DPI_MODE_FETCH_FIRST
desc: |
Scroll the cursor to the first row in the result set. The offset is
ignored when using this mode.
- name: DPI_MODE_FETCH_LAST
desc: |
Scroll the cursor to the last row in the result set. The offset is
ignored when using this mode.
- name: DPI_MODE_FETCH_NEXT
desc: |
Scroll the cursor to the next row in the result set. The offset is
ignored when using this mode.
- name: DPI_MODE_FETCH_PRIOR
desc: |
Scroll the cursor to the previous row in the result set. The offset is
ignored when using this mode.
- name: DPI_MODE_FETCH_RELATIVE
desc: |
Scroll the cursor to the row identified by the offset parameter using
relative positioning. A positive number will move forward in the result
set while a negative number will move backwards in the result set.
- name: dpiJsonOptions
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the options that can be used when calling
[`dpiJson_getValue()`].
members:
- name: DPI_JSON_OPT_DATE_AS_DOUBLE
desc: |
Convert values that are stored as Oracle dates and timestamps in the
JSON value into double values (number of milliseconds since
January 1, 1970).
- name: DPI_JSON_OPT_DEFAULT
desc: |
Default value.
- name: DPI_JSON_OPT_NUMBER_AS_STRING
desc: |
Convert values that are stored as Oracle numbers in the JSON value into
strings in order to retain precision.
- name: dpiMessageDeliveryMode
kind: enum
underlying_type: uint16_t
desc: |
This enumeration identifies the delivery mode used for filtering messages
when dequeuing messages from a queue.
members:
- name: DPI_MODE_MSG_BUFFERED
desc: |
Dequeue only buffered messages from the queue.
- name: DPI_MODE_MSG_PERSISTENT
desc: |
Dequeue only persistent messages from the queue. This is the default
mode.
- name: DPI_MODE_MSG_PERSISTENT_OR_BUFFERED
desc: |
Dequeue both persistent and buffered messages from the queue.
- name: dpiMessageState
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the possible states for messages in a queue.
members:
- name: DPI_MSG_STATE_EXPIRED
desc: |
The message has been moved to the exception queue.
- name: DPI_MSG_STATE_PROCESSED
desc: |
The message has already been processed and is retained.
- name: DPI_MSG_STATE_READY
desc: |
The message is ready to be processed.
- name: DPI_MSG_STATE_WAITING
desc: |
The message is waiting for the delay time to expire.
- name: dpiNativeTypeNum
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the type of data that is being transferred to and
from the database. It is used in the structures
[`dpiDataTypeInfo`],
[`dpiShardingKeyColumn`] and
[`dpiJsonNode`].
members:
- name: DPI_NATIVE_TYPE_BOOLEAN
desc: |
Data is passed as a boolean value in [`dpiDataBuffer.asBoolean`].
- name: DPI_NATIVE_TYPE_BYTES
desc: |
Data is passed as a byte string in [`dpiDataBuffer.asBytes`].
- name: DPI_NATIVE_TYPE_DOUBLE
desc: |
Data is passed as a double precision floating point number in
[`dpiDataBuffer.asDouble`].
- name: DPI_NATIVE_TYPE_FLOAT
desc: |
Data is passed as a single precision floating point number in
[`dpiDataBuffer.asFloat`].
- name: DPI_NATIVE_TYPE_INT64
desc: |
Data is passed as a 64-bit integer in [`dpiDataBuffer.asInt64`].
- name: DPI_NATIVE_TYPE_INTERVAL_DS
desc: |
Data is passed as an interval (days to seconds) in
[`dpiDataBuffer.asIntervalDS`].
- name: DPI_NATIVE_TYPE_INTERVAL_YM
desc: |
Data is passed as an interval (years to months) in
[`dpiDataBuffer.asIntervalYM`].
- name: DPI_NATIVE_TYPE_JSON
desc: |
Data is passed as a JSON node in `dpiDataBuffer.asJsonNode`.
- name: DPI_NATIVE_TYPE_JSON_ARRAY
desc: |
Data is passed as a JSON array in [`dpiDataBuffer.asJsonArray`].
- name: DPI_NATIVE_TYPE_JSON_OBJECT
desc: |
Data is passed as a JSON object in
[`dpiDataBuffer.asJsonObject`].
- name: DPI_NATIVE_TYPE_LOB
desc: |
Data is passed as a reference to a LOB in
[`dpiDataBuffer.asLOB`].
- name: DPI_NATIVE_TYPE_NULL
desc: |
No data is being passed. This is used to identify the JSON singleton
null value.
- name: DPI_NATIVE_TYPE_OBJECT
desc: |
Data is passed as a reference to an object in
[`dpiDataBuffer.asObject`].
- name: DPI_NATIVE_TYPE_ROWID
desc: |
Data is passed as a reference to a rowid in
[`dpiDataBuffer.asRowid`].
- name: DPI_NATIVE_TYPE_STMT
desc: |
Data is passed as a reference to a statement in
[`dpiDataBuffer.asStmt`].
- name: DPI_NATIVE_TYPE_TIMESTAMP
desc: |
Data is passed as a timestamp in [`dpiDataBuffer.asTimestamp`].
- name: DPI_NATIVE_TYPE_UINT64
desc: |
Data is passed as an unsigned 64-bit integer in
[`dpiDataBuffer.asUint64`].
- name: DPI_NATIVE_TYPE_VECTOR
desc: |
Data is passed as a reference to a vector in
[`dpiDataBuffer.asVector`].
- name: dpiOpCode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the types of operations that can take place during
object change and query change notification. It is used both as a filter when
determining which operations to consider when sending notifications as well as
identifying the operation that took place on a particular table or row when a
notification is sent. Multiple values can be OR’ed together to specify multiple
types of operations at the same time.
members:
- name: DPI_OPCODE_ALL_OPS
desc: |
Indicates that notifications should be sent for all operations on the
table or query.
- name: DPI_OPCODE_ALL_ROWS
desc: |
Indicates that all rows have been changed in the table or query (or
too many rows were changed or row information was not requested).
- name: DPI_OPCODE_ALTER
desc: |
Indicates that the registered table or query has been altered.
- name: DPI_OPCODE_DELETE
desc: |
Indicates that a delete operation has taken place in the table or
query.
- name: DPI_OPCODE_DROP
desc: |
Indicates that the registered table or query has been dropped.
- name: DPI_OPCODE_INSERT
desc: |
Indicates that an insert operation has taken place in the table or
query.
- name: DPI_OPCODE_UPDATE
desc: |
Indicates that an update operation has taken place in the table or
query.
- name: DPI_OPCODE_UNKNOWN
desc: |
An unknown operation has taken place.
- name: dpiOracleTypeNum
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the types of Oracle data that can be used for
binding data as arguments to a statement, fetching data from the database, or
getting and setting object attributes and element values.
members:
- name: DPI_ORACLE_TYPE_BFILE
desc: |
Default type used for BFILE columns in the database. Only a locator is
transferred to/from Oracle, which can subsequently be used via dpiLob
references to read/write from that locator.
- name: DPI_ORACLE_TYPE_BLOB
desc: |
Default type used for BLOB columns in the database. Only a locator is
transferred to/from Oracle, which can subsequently be used via dpiLob
references to read/write from that locator.
- name: DPI_ORACLE_TYPE_BOOLEAN
desc: |
Used within PL/SQL for boolean values. This is only available in 12.1.
Earlier releases simply use the integer values 0 and 1 to represent a
boolean value. Data is transferred to/from Oracle as an integer.
- name: DPI_ORACLE_TYPE_CHAR
desc: |
Default type used for CHAR columns in the database. Data is transferred
to/from Oracle as byte strings in the encoding used for CHAR data.
- name: DPI_ORACLE_TYPE_CLOB
desc: |
Default type used for CLOB columns in the database. Only a locator is
transferred to/from Oracle, which can subsequently be used via dpiLob
references to read/write from that locator.
- name: DPI_ORACLE_TYPE_DATE
desc: |
Default type used for DATE columns in the database. Data is transferred
to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_INTERVAL_DS
desc: |
Default type used for INTERVAL DAY TO SECOND columns in the database.
Data is transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_INTERVAL_YM
desc: |
Default type used for INTERVAL YEAR TO MONTH columns in the database.
Data is transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_JSON
desc: |
Default type used for JSON columns in the database (available in Oracle
Database 20 and higher). Data is transferred to/from Oracle using the
structure [`dpiJsonNode`].
- name: DPI_ORACLE_TYPE_JSON_ARRAY
desc: |
Type used for identifying nodes that are JSON arrays. Data is
transferred to/from Oracle using the structure
[`dpiJsonArray`].
- name: DPI_ORACLE_TYPE_JSON_ID
desc: |
Type used for identifying nodes that are JSON IDs. Data is transferred
to/from Oracle as raw byte strings.
- name: DPI_ORACLE_TYPE_JSON_OBJECT
desc: |
Type used for identifying nodes that are JSON objects. Data is
transferred to/from Oracle using the structure [`dpiJsonObject`].
- name: DPI_ORACLE_TYPE_LONG_NVARCHAR
desc: |
This value cannot be represented in an Oracle database but is used when
fetching NCLOB data as a string. Data is transferred to/from Oracle as
byte strings in the encoding used for NCHAR data.
- name: DPI_ORACLE_TYPE_LONG_RAW
desc: |
Default type used for LONG RAW columns in the database. Data is
transferred to/from Oracle as raw byte strings.
- name: DPI_ORACLE_TYPE_LONG_VARCHAR
desc: |
Default type used for LONG columns in the database. Data is transferred
to/from Oracle as byte strings in the encoding used for CHAR data.
- name: DPI_ORACLE_TYPE_NATIVE_DOUBLE
desc: |
Default type used for BINARY_DOUBLE columns in the database. Data is
transferred to/from Oracle as the C double type.
- name: DPI_ORACLE_TYPE_NATIVE_FLOAT
desc: |
Default type used for BINARY_FLOAT columns in the database. Data is
transferred to/from Oracle as the C float type.
- name: DPI_ORACLE_TYPE_NATIVE_INT
desc: |
Type available for binding native integers directly in PL/SQL
(such as PLS_INTEGER). Data is transferred to/from Oracle as 64-bit
integers.
- name: DPI_ORACLE_TYPE_NATIVE_UINT
desc: |
Type available for binding native integers directly in PL/SQL
(such as PLS_INTEGER). Data is transferred to/from Oracle as 64-bit
unsigned integers.
- name: DPI_ORACLE_TYPE_NCHAR
desc: |
Default type used for NCHAR columns in the database. Data is
transferred to/from Oracle as byte strings in the encoding used for
NCHAR data.
- name: DPI_ORACLE_TYPE_NCLOB
desc: |
Default type used for NCLOB columns in the database. Only a locator is
transferred to/from Oracle, which can subsequently be used via dpiLob
references to read/write from that locator.
- name: DPI_ORACLE_TYPE_NUMBER
desc: |
Default type used for NUMBER columns in the database. Data is
transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_NVARCHAR
desc: |
Default type used for NVARCHAR2 columns in the database. Data is
transferred to/from Oracle as byte strings in the encoding used for
NCHAR data.
- name: DPI_ORACLE_TYPE_OBJECT
desc: |
Default type used for named type columns in the database. Data is
transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_RAW
desc: |
Default type used for RAW columns in the database. Data is transferred
to/from Oracle as raw byte strings.
- name: DPI_ORACLE_TYPE_ROWID
desc: |
Default type used for the pseudocolumn “ROWID”. Data is transferred
to/from Oracle as byte strings, in the encoding used for CHAR data.
- name: DPI_ORACLE_TYPE_STMT
desc: |
Used within PL/SQL for REF CURSOR or within SQL for querying a CURSOR.
Only a handle is transferred to/from Oracle, which can subsequently be
used via dpiStmt for querying.
- name: DPI_ORACLE_TYPE_TIMESTAMP
desc: |
Default type used for TIMESTAMP columns in the database. Data is
transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_TIMESTAMP_LTZ
desc: |
Default type used for TIMESTAMP WITH LOCAL TIME ZONE columns in the
database. Data is transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_TIMESTAMP_TZ
desc: |
Default type used for TIMESTAMP WITH TIME ZONE columns in the database.
Data is transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_UROWID
desc: |
This value is currently a synonym for DPI_ORACLE_TYPE_ROWID. It is
intended to be the default type for UROWID columns in the database when
it is possible to distinguish betweeen ROWID and UROWID. Data is
transferred to/from Oracle as byte strings, in the encoding used for
CHAR data.
- name: DPI_ORACLE_TYPE_VARCHAR
desc: |
Default type used for VARCHAR2 columns in the database. Data is
transferred to/from Oracle as byte strings in the encoding used for
CHAR data.
- name: DPI_ORACLE_TYPE_VECTOR
desc: |
Default type used for VECTOR columns in the database. Data is
transferred to/from Oracle in Oracle’s internal format.
- name: DPI_ORACLE_TYPE_XMLTYPE
desc: |
Default type used for SYS.XMLTYPE columns in the database. Data is
transferred to/from Oracle as byte strings in the encoding used for
CHAR data.
- name: dpiPoolCloseMode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the mode to use when closing pools.
members:
- name: DPI_MODE_POOL_CLOSE_DEFAULT
desc: |
Default value used when closing pools. If there are any active sessions
in the pool an error will be raised.
- name: DPI_MODE_POOL_CLOSE_FORCE
desc: |
Causes all of the active connections in the pool to be closed before
closing the pool itself.
- name: dpiPoolGetMode
kind: enum
underlying_type: uint8_t
desc: |
This enumeration identifies the mode to use when getting sessions from a
session pool.
members:
- name: DPI_MODE_POOL_GET_FORCEGET
desc: |
Specifies that a new session should be created if all of the sessions
in the pool are busy, even if this exceeds the maximum sessions
allowable for the session pool (see
[`dpiPoolCreateParams.maxSessions`]).
- name: DPI_MODE_POOL_GET_NOWAIT
desc: |
Specifies that the caller should return immediately, regardless of
whether a session is available in the pool. If a session is not
available an error is returned.
- name: DPI_MODE_POOL_GET_TIMEDWAIT
desc: |
Specifies that the caller should block until a session is available
from the pool, but only for the specified length of time defined in
[`dpiPoolCreateParams.waitTimeout`]. If a session is not
available within the specified period of time an error is returned.
- name: DPI_MODE_POOL_GET_WAIT
desc: |
Specifies that the caller should block until a session is available
from the pool.
- name: dpiPurity
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the purity of the sessions that are acquired when
using connection classes during connection creation.
members:
- name: DPI_PURITY_DEFAULT
desc: |
Default value used when creating connections.
- name: DPI_PURITY_NEW
desc: |
A connection is required that has not been tainted with any prior
session state.
- name: DPI_PURITY_SELF
desc: |
A connection is permitted to have prior session state.
- name: dpiServerType
kind: enum
underlying_type: uint8_t
desc: |
This enumeration identifies the type of server process associated with a
connection. It is only available with Oracle Client libraries 23.4 or higher.
members:
- name: DPI_SERVER_TYPE_DEDICATED
desc: |
A dedicated server process is being used with the connection.
- name: DPI_SERVER_TYPE_POOLED
desc: |
A pooled server process (DRCP) is being used with the connection.
- name: DPI_SERVER_TYPE_SHARED
desc: |
A shared server process is being used with the connection.
- name: DPI_SERVER_TYPE_UNKNOWN
desc: |
The type of server process is unknown.
- name: dpiShutdownMode
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the mode to use when shutting down a database
using [`dpiConn_shutdownDatabase()`].
members:
- name: DPI_MODE_SHUTDOWN_ABORT
desc: |
All uncommitted transactions are terminated and are not rolled back.
This is the fastest way to shut down the database but the next database
startup may require instance recovery.
- name: DPI_MODE_SHUTDOWN_DEFAULT
desc: |
Further connections to the database are prohibited. Wait for users to
disconnect from the database.
- name: DPI_MODE_SHUTDOWN_FINAL
desc: |
Shuts down the database. This mode should only be used in the second
call to [`dpiConn_shutdownDatabase()`].
- name: DPI_MODE_SHUTDOWN_IMMEDIATE
desc: |
All uncommitted transactions are terminated and rolled back and all
connections to the database are closed immediately.
- name: DPI_MODE_SHUTDOWN_TRANSACTIONAL
desc: |
Further connections to the database are prohibited and no new
transactions are allowed to be started. Wait for active transactions
to complete.
- name: DPI_MODE_SHUTDOWN_TRANSACTIONAL_LOCAL
desc: |
Behaves the same way as DPI_MODE_SHUTDOWN_TRANSACTIONAL but only waits
for local transactions to complete.
- name: dpiSodaFlags
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the flags that can be used with SODA functions.
members:
- name: DPI_SODA_FLAGS_ATOMIC_COMMIT
desc: |
If the function completes successfully the current transaction is
committed. If it does not complete successfully, no changes to the
database are made and the existing transaction is left untouched.
- name: DPI_SODA_FLAGS_CREATE_COLL_MAP
desc: |
Create collection in MAP mode. This mode is only supported in
[`dpiSodaDb_createCollection()`].
- name: DPI_SODA_FLAGS_DEFAULT
desc: |
Default value.
- name: DPI_SODA_FLAGS_INDEX_DROP_FORCE
desc: |
Forcibly drop the index. This mode is only supported in
[`dpiSodaColl_dropIndex()`].
- name: dpiStartupMode
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the mode to use when starting up a database using
[`dpiConn_startupDatabase()`].
members:
- name: DPI_MODE_STARTUP_DEFAULT
desc: |
Default mode for startup which permits database access to all users.
- name: DPI_MODE_STARTUP_FORCE
desc: |
Shuts down a running instance (using ABORT) before starting a new one.
This mode should only be used in unusual circumstances.
- name: DPI_MODE_STARTUP_RESTRICT
desc: |
Only allows database access to users with both the CREATE SESSION and
RESTRICTED SESSION privileges (normally the DBA).
- name: dpiStatementType
kind: enum
underlying_type: uint16_t
desc: |
This enumeration identifies the type of statement that has been prepared. It is
available as part of the structure [`dpiStmtInfo`].
members:
- name: DPI_STMT_TYPE_ALTER
desc: |
Identifies an alter statement. The member [`dpiStmtInfo.isDDL`]
will be set to 1.
- name: DPI_STMT_TYPE_BEGIN
desc: |
Identifies an anonymous PL/SQL block starting with the keyword begin.
The member [`dpiStmtInfo.isPLSQL`] will be set to 1.
- name: DPI_STMT_TYPE_CALL
desc: |
Identifies a CALL statement used for calling stored procedures and
functions. The member [`dpiStmtInfo.isPLSQL`] will be set to 1.
- name: DPI_STMT_TYPE_COMMIT
desc: |
Identifies a commit statement.
- name: DPI_STMT_TYPE_CREATE
desc: |
Identifies a create statement. The member [`dpiStmtInfo.isDDL`]
will be set to 1.
- name: DPI_STMT_TYPE_DECLARE
desc: |
Identifies an anonymous PL/SQL block starting with the keyword
declare. The member [`dpiStmtInfo.isPLSQL`] will be set to 1.
- name: DPI_STMT_TYPE_DELETE
desc: |
Identifies a delete statement. The member [`dpiStmtInfo.isDML`]
will be set to 1.
- name: DPI_STMT_TYPE_DROP
desc: |
Identifies a drop statement. The member [`dpiStmtInfo.isDDL`]
will be set to 1.
- name: DPI_STMT_TYPE_EXPLAIN_PLAN
desc: |
Identifies an explain plan statement. The member
[`dpiStmtInfo.isDML`] will be set to 1.
- name: DPI_STMT_TYPE_INSERT
desc: |
Identifies an insert statement. The member [`dpiStmtInfo.isDML`]
will be set to 1.
- name: DPI_STMT_TYPE_MERGE
desc: |
Identifies a merge statement. The member [`dpiStmtInfo.isDML`]
will be set to 1.
- name: DPI_STMT_TYPE_ROLLBACK
desc: |
Identifies a rollback statement.
- name: DPI_STMT_TYPE_SELECT
desc: |
Identifies a select statement. The member [`dpiStmtInfo.isQuery`]
will be set to 1.
- name: DPI_STMT_TYPE_UPDATE
desc: |
Identifies an update statement. The member [`dpiStmtInfo.isDML`]
will be set to 1.
- name: DPI_STMT_TYPE_UNKNOWN
desc: |
Indicates that the statement type is unknown.
- name: dpiSubscrGroupingClass
kind: enum
underlying_type: uint8_t
desc: |
This enumeration identifies the grouping class. Instead of individual events
being delivered to the callback, events are grouped before being sent to the
callback. This enumeration is used in the
[`dpiSubscrCreateParams`] structure.
members:
- name: DPI_SUBSCR_GROUPING_CLASS_TIME
desc: |
Events are grouped by the period of time in which they are received.
- name: dpiSubscrGroupingType
kind: enum
underlying_type: uint8_t
desc: |
This enumeration identifies the grouping type. It is used in the
[`dpiSubscrCreateParams`] structure.
members:
- name: DPI_SUBSCR_GROUPING_TYPE_LAST
desc: |
The last event in the group is sent.
- name: DPI_SUBSCR_GROUPING_TYPE_SUMMARY
desc: |
A summary of all events in the group is sent. This is also the default
value.
- name: dpiSubscrNamespace
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the namespaces supported by subscriptions.
members:
- name: DPI_SUBSCR_NAMESPACE_AQ
desc: |
Identifies the namespace used for receiving notifications when messages
are available to be dequeued in advanced queueing (AQ).
- name: DPI_SUBSCR_NAMESPACE_DBCHANGE
desc: |
Identifies the namespace used for receiving notifications for database
object changes and query changes (CQN).
- name: dpiSubscrProtocol
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the protocol used for sending notifications to
subscriptions.
members:
- name: DPI_SUBSCR_PROTO_CALLBACK
desc: |
Notifications are sent by calling the callback specified when the
subscription was registered.
- name: DPI_SUBSCR_PROTO_HTTP
desc: |
Notifications are sent to the URL specified when the subscription
was registered.
- name: DPI_SUBSCR_PROTO_MAIL
desc: |
Notifications are sent by sending an e-mail to the e-mail address
specified when the subscription was registered.
- name: DPI_SUBSCR_PROTO_PLSQL
desc: |
Notifications are sent by calling the PL/SQL procedure specified when
the subscription was registered.
- name: dpiSubscrQOS
kind: enum
underlying_type: uint32_t
hints:
type: bitflags
desc: |
This enumeration identifies the quality of service flags for sending
notifications to subscriptions.
members:
- name: DPI_SUBSCR_QOS_BEST_EFFORT
desc: |
Perform query notification in best effort mode which may result in
notifications being sent when the query has not in fact changed. This
is needed for complex queries that cannot be registered in guaranteed
mode.
- name: DPI_SUBSCR_QOS_DEREG_NFY
desc: |
When the notification has been received, the subscription is removed.
- name: DPI_SUBSCR_QOS_QUERY
desc: |
Perform query notification instead of database change notification.
Notification is done in guaranteed mode which guarantees that the query
has in fact changed.
- name: DPI_SUBSCR_QOS_RELIABLE
desc: |
Notifications are sent reliably. If the database fails, the notifications
are not lost. This is not supported for nonpersistent queues or buffered
messaging.
- name: DPI_SUBSCR_QOS_ROWIDS
desc: |
Information on the rows affected by the database or query change is
sent along with the notification.
- name: dpiTpcBeginFlags
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the flags that can be used when calling
[`dpiConn_tpcBegin()`].
members:
- name: DPI_TPC_BEGIN_JOIN
desc: |
Joins an existing global transaction.
- name: DPI_TPC_BEGIN_NEW
desc: |
Creates a new global transaction.
- name: DPI_TPC_BEGIN_PROMOTE
desc: |
Promotes a local transaction to a global transaction.
- name: DPI_TPC_BEGIN_RESUME
desc: |
Resumes an existing global transaction.
- name: dpiTpcEndFlags
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the flags that can be used when calling
[`dpiConn_tpcEnd()`].
members:
- name: DPI_TPC_END_NORMAL
desc: |
Normal ending of the transaction.
- name: DPI_TPC_END_SUSPEND
desc: |
Transaction is suspended and may be resumed at some later point.
- name: dpiVectorFlags
kind: enum
underlying_type: uint8_t
hints:
type: bitflags
desc: |
This enumeration identifies the possible values for
[`dpiDataTypeInfo.vectorFlags`].
members:
- name: DPI_VECTOR_FLAGS_FLEXIBLE_DIM
desc: |
The vector column uses a flexible number of dimensions.
- name: DPI_VECTOR_FLAGS_SPARSE
desc: |
The vector column contains sparse vectors
- name: dpiVectorFormat
kind: enum
underlying_type: uint8_t
desc: |
This enumeration identifies the storage format for a vector’s dimensions.
members:
- name: DPI_VECTOR_FORMAT_BINARY
desc: |
The vector dimension storage format is single bits, represented in
groups of 8 as single byte unsigned integers.
- name: DPI_VECTOR_FORMAT_FLOAT32
desc: |
The vector dimension storage format is single-precision floating point
numbers.
- name: DPI_VECTOR_FORMAT_FLOAT64
desc: |
The vector dimension storage format is double-precision floating point
numbers.
- name: DPI_VECTOR_FORMAT_INT8
desc: |
The vector dimension storage format is single byte signed integers.
- name: dpiVisibility
kind: enum
underlying_type: uint32_t
desc: |
This enumeration identifies the visibility of messages in advanced queuing.
members:
- name: DPI_VISIBILITY_IMMEDIATE
desc: |
The message is not part of the current transaction but constitutes
a transaction of its own.
- name: DPI_VISIBILITY_ON_COMMIT
desc: |
The message is part of the current transaction. This is the default
value.
- name: dpiConn
kind: opaque struct
desc: |
Connection handles are used to represent connections to the database. These can
be standalone connections created by calling the function
[`dpiConn_create()`] or acquired from a session pool by calling the
function [`dpiPool_acquireConnection()`]. They can be closed by calling the
function [`dpiConn_close()`] or releasing the last reference to the
connection by calling the function [`dpiConn_release()`]. Connection
handles are used to create all handles other than session pools and context
handles.
functions:
- name: dpiConn_addRef
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
The connection to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiConn_breakExecution
desc: |
Performs an immediate (asynchronous) termination of any currently executing
function on the server associated with the connection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection on which the break is to take place.
If the reference is NULL or invalid, an error is returned.
- name: dpiConn_changePassword
desc: |
Changes the password of the specified user.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection on which the password is to be
changed. If the reference is NULL or invalid, an error is
returned.
- name: userName
type: const char *
mode: IN
desc: |
The name of the user whose password is to be changed, as a byte
string in the encoding used for CHAR data.
- name: userNameLength
type: uint32_t
mode: IN
desc: |
The length of the user name parameter, in bytes.
- name: oldPassword
type: const char *
mode: IN
desc: |
The old password of the user whose password is to be changed,
as a byte string in the encoding used for CHAR data.
- name: oldPasswordLength
type: uint32_t
mode: IN
desc: |
The length of the old password parameter, in bytes.
- name: newPassword
type: const char *
mode: IN
desc: |
The new password of the user whose password is to be changed,
as a byte string in the encoding used for CHAR data.
- name: newPasswordLength
type: uint32_t
mode: IN
desc: |
The length of the new password parameter, in bytes.
- name: dpiConn_close
desc: |
Closes the connection and makes it unusable for further activity. Any open
statements and LOBs associated with the connection will also be closed and
made unusable for further activity.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection which is to be closed. If the reference
is NULL or invalid, an error is returned.
- name: mode
type: dpiConnCloseMode
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiConnCloseMode`], OR’ed together.
- name: tag
type: const char *
mode: IN
desc: |
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. NULL 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.
- name: tagLength
type: uint32_t
mode: IN
desc: |
The length of the tag parameter, in bytes, or 0 if the tag
parameter is NULL.
- name: dpiConn_commit
desc: |
Commits the current active transaction.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection which holds the transaction which is
to be committed. If the reference is NULL or invalid, an error is
returned.
- name: dpiConn_create
desc: |
Creates a standalone connection to a database or acquires a connection
from a session pool and returns a reference to the connection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
If a failure occurs, the errorInfo structure is filled in with error
information.
round_trips: Maybe
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: userName
type: const char *
mode: IN
desc: |
The name of the user used for authenticating the user, as a byte
string in the encoding used for CHAR data. NULL is also acceptable
if external authentication is being requested or if credentials
were specified when the pool was created.
- name: userNameLength
type: uint32_t
mode: IN
desc: |
The length of the userName parameter, in bytes, or 0 if the
userName parameter is NULL.
- name: password
type: const char *
mode: IN
desc: |
The password to use for authenticating the user, as a byte string
in the encoding used for CHAR data. NULL is also acceptable if
external authentication is being requested or if credentials were
specified when the pool was created.
- name: passwordLength
type: uint32_t
mode: IN
desc: |
The length of the password parameter, in bytes, or 0 if the
password parameter is NULL.
- name: connectString
type: const char *
mode: IN
desc: |
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. NULL 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.
- name: connectStringLength
type: uint32_t
mode: IN
desc: |
The length of the connectString parameter, in bytes, or 0 if the
connectString parameter is NULL.
- name: commonParams
type: dpiCommonCreateParams *
mode: IN
desc: |
A pointer to a [`dpiCommonCreateParams`]
structure which is used to specify context parameters for
connection creation. NULL is also acceptable in which case all
default parameters will be used when creating the connection. This
value is ignored when acquiring a connection from a session pool.
- name: createParams
type: dpiConnCreateParams *
mode: IN
desc: |
A pointer to a [`dpiConnCreateParams`]
structure which is used to specify parameters for connection
creation. NULL is also acceptable in which case all default
parameters will be used when creating the connection. If the
member [`dpiConnCreateParams.pool`] is not NULL, a
connection will be acquired from the pool (as if the function
[`dpiPool_acquireConnection()`] had been called); otherwise, a
standalone connection will be created.
- name: conn
type: dpiConn **
mode: OUT
desc: |
A pointer to a reference to the connection that is created. Call
[`dpiConn_release()`] when the reference is no longer needed.
- name: dpiConn_deqObject
desc: |
Dequeues a message from a queue. This function is deprecated and will be
removed in version 4. One of the functions [`dpiQueue_deqOne()`] or
[`dpiQueue_deqMany()`] should be used instead.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the message is to be
dequeued. If the reference is NULL or invalid, an error is
returned.
- name: queueName
type: const char *
mode: IN
desc: |
The name of the queue from which the message is to be dequeued,
as a byte string in the encoding used for CHAR data.
- name: queueNameLength
type: uint32_t
mode: IN
desc: |
The length of the queueName parameter, in bytes.
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options that should be used when
dequeuing the message from the queue.
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties that will be populated
with information from the message that is dequeued.
- name: payload
type: dpiObject *
mode: IN
desc: |
A reference to the object which will be populated with the
message that is dequeued.
- name: msgId
type: const char **
mode: OUT
desc: |
A pointer to a byte string which will be populated with the id of
the message that is dequeued, or NULL if no message is available.
If there is a message id, the pointer will remain valid until the
next call to [`dpiConn_enqObject()`] or
[`dpiConn_deqObject()`].
- name: msgIdLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the msgId parameter, or 0 if the msgId
parameter is NULL.
- name: dpiConn_enqObject
desc: |
Enqueues a message to a queue. This function is deprecated and will be
removed in version 4. One of the functions [`dpiQueue_enqOne()`] or
[`dpiQueue_enqMany()`] should be used instead.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection to which the message is to be
enqueued. If the reference is NULL or invalid, an error is
returned.
- name: queueName
type: const char *
mode: IN
desc: |
The name of the queue to which the message is to be enqueued,
as a byte string in the encoding used for CHAR data.
- name: queueNameLength
type: uint32_t
mode: IN
desc: |
The length of the queueName parameter, in bytes.
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
A reference to the enqueue options that should be used when
enqueuing the message to the queue.
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties that will affect the message
that is enqueued.
- name: payload
type: dpiObject *
mode: IN
desc: |
a reference to the object which will be enqueued.
- name: msgId
type: const char **
mode: OUT
desc: |
A pointer to a byte string which will be populated with the id of
the message that is enqueued upon successful completion of this
function. The pointer will remain valid until the next call to
[`dpiConn_enqObject()`] or [`dpiConn_deqObject()`].
- name: msgIdLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the msgId parameter which will be
populated upon successful completion of this function.
- name: dpiConn_getCallTimeout
desc: |
Returns the current call timeout (in milliseconds) used for round-trips to
the database made with this connection. A value of 0 means that no timeouts
will take place. This value can be set using the function
[`dpiConn_setCallTimeout()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the current call timeout
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the call timeout value, which will be populated upon
successful completion of this function.
- name: dpiConn_getCurrentSchema
desc: |
Returns the current schema that is being used by the connection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the current schema is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the current schema, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the connection is held and the current
schema is not changed by some means.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the current schema, in bytes, which will
be populated upon successful completion of this function.
- name: dpiConn_getDbDomain
desc: |
Returns the Oracle Database Domain name associated with the connection.
This is the same value returned by the SQL expression
`SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'`.
This function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the database domain name
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the database domain name, as a byte string in the
encoding used for CHAR data, which will be populated upon
successful completion of this function. The string returned will
remain valid as long as a reference to the connection is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the database domain name, in bytes,
which will be populated upon successful completion of this
function.
- name: dpiConn_getDbName
desc: |
Returns the Oracle Database name associated with the connection. This is
the same value returned by the SQL expression
`SELECT NAME FROM V$DATABASE`.
This function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the database name is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the database name, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the connection is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the database name, in bytes, which will
be populated upon successful completion of this function.
- name: dpiConn_getEdition
desc: |
Returns the edition that is being used by the connection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the edition is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the edition, as a byte string in the encoding used
for CHAR data, which will be populated upon successful completion
of this function. The string returned will remain valid as long as
a reference to the connection is held and the edition is not
changed by some means.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the edition, in bytes, which will be
populated upon successful completion of this function.
- name: dpiConn_getEncodingInfo
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection whose encoding information is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiEncodingInfo *
mode: OUT
desc: |
A pointer to a [`dpiEncodingInfo`] structure
which will be populated with the encoding information used by the
connection.
- name: dpiConn_getExternalName
desc: |
Returns the external name that is being used by the connection. This value
is used when logging distributed transactions.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the external name is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the external name, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the connection is held and the external
name is not changed by some means.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the external name, in bytes, which will
be populated upon successful completion of this function.
- name: dpiConn_getHandle
desc: |
Returns the OCI service context handle in use by the connection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection whose service context handle is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: handle
type: void **
mode: OUT
desc: |
A pointer which will be populated with the service context handle
of the connection upon successful completion of the function. This
handle can be used within OCI calls independently of the library,
but care must be taken not to cause problems due to shared use.
- name: dpiConn_getInfo
desc: |
Returns information about the connection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which information is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiConnInfo *
mode: OUT
desc: |
A pointer to a structure of type [`dpiConnInfo`]
which will be filled in with information about the connection upon
successful completion of the function. The pointers in the
structure will remain valid as long as the connection itself is
open. When using a pooled server process, however, the information
in the structure may become stale when a new session is associated
with the connection.
- name: dpiConn_getInstanceName
desc: |
Returns the Oracle Database instance name associated with the connection.
This is the same value returned by the SQL expression
`sys_context('userenv', 'instance_name')`.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the instance name is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the instance name, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the connection is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the instance name, in bytes, which will
be populated upon successful completion of this function.
- name: dpiConn_getInternalName
desc: |
Returns the internal name that is being used by the connection. This value
is used when logging distributed transactions.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the internal name is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the internal name, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the connection is held and the internal
name is not changed by some means.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the internal name, in bytes, which will
be populated upon successful completion of this function.
- name: dpiConn_getIsHealthy
desc: |
Checks if a connection is usable. Connections may become unusable in
several cases, such as if the network socket is broken, if an Oracle error
indicates the connection is unusable or after receiving a planned down
notification from the database.
This function is best used before starting a new database request on an
existing standalone connection. Pooled connections internally perform this
check before returning a connection to the application.
Avoid using this function when database requests are in progress.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
If DPI_FAILURE is returned, the connection should be not be used by the
application and a new connection should be established instead.
This function performs a local check. To fully check a connection’s health,
use [`dpiConn_ping()`].
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection for which the status is to be
checked. If the reference is NULL or invalid, an error is
returned.
- name: isHealthy
type: int *
mode: OUT
desc: |
A pointer to an integer defining whether the connection is
healthy (1) or not (0), which will be populated upon successful
completion of this function.
- name: dpiConn_getLTXID
desc: |
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().
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the logical transaction id
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the logical transaction id, as a byte string, which
will be populated upon successful completion of this function. The
bytes returned will remain valid as long as a reference to the
connection is held and the logical transaction id is not changed
by some means.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the logical transaction id, in bytes,
which will be populated upon successful completion of this
function.
- name: dpiConn_getMaxOpenCursors
desc: |
Returns the maximum number of cursors that can be opened. This is the same
value returned by the SQL expression
`SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'`.
This function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the maximum number of open
cursors is to be retrieved. If the reference is NULL or invalid an
error is returned.
- name: maxOpenCursors
type: uint32_t *
mode: OUT
desc: |
A pointer of type uint32_t, which will be populated upon successful
completion of this function.
- name: dpiConn_getObjectType
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection which contains the object type to
look up. If the reference is NULL or invalid, an error is returned.
- name: name
type: const char *
mode: IN
desc: |
The name of the object type to lookup, as a byte string in the
encoding used for CHAR data.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: objType
type: dpiObjectType **
mode: OUT
desc: |
A pointer to a reference to the object type, which will be
populated upon successfully locating the object type.
- name: dpiConn_getOciAttr
desc: |
Returns the value of an OCI attribute. This is intended solely for testing
attributes that are not otherwise supported by ODPI-C and should not be
used for any other purpose. Use only as directed by Oracle.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the OCI attribute is to be
returned. If the reference is NULL or invalid, an error is
returned.
- name: handleType
type: uint32_t
mode: IN
desc: |
The type of OCI handle that is to be used. This should be one of 3
(service context handle), 8 (server handle) or 9 (session handle).
- name: attribute
type: uint32_t
mode: IN
desc: |
The attribute to acquire.
- name: value
type: dpiDataBuffer *
mode: OUT
desc: |
A data buffer which will be populated with the value of the OCI
attribute upon successfully completing this function.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
The length of the attribute which will be populated upon
succesfully completing this function.
- name: dpiConn_getServerVersion
desc: |
Returns the version information of the Oracle Database to which the
connection has been made.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the server version
information is to be retrieved. If the reference is NULL or
invalid, an error is returned.
- name: releaseString
type: const char **
mode: OUT
desc: |
A pointer to the release string which will be populated when this
function returns successfully. The string remains valid as long as
a reference is held to the connection. This parameter may also be
NULL. In Oracle Client 20.3 and higher, using NULL will eliminate
the need for a round-trip to the server.
- name: releaseStringLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the release string which will be
populated when this function returns successfully. This parameter
may also be NULL.
- name: versionInfo
type: dpiVersionInfo *
mode: OUT
desc: |
A pointer to a [`dpiVersionInfo`] structure
which will be populated with the version information of the Oracle
Database to which the connection has been made.
- name: dpiConn_getServiceName
desc: |
Returns the Oracle Database service name associated with the connection.
This is the same value returned by the SQL expression
`SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL`.
This function returns DPI_SCCUESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the service name is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the service name, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the connection is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the service name, in bytes, which will
be populated upon successful completion of this function.
- name: dpiConn_getSodaDb
desc: |
Return a reference to a SODA database which can be used to create, open
and drop collections. The connection that is passed should remain open
while SODA operations are being performed. If the connection is closed an
error will take place when the next SODA operation is attempted.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection to use for accessing the SODA
database.
- name: db
type: dpiSodaDb **
mode: OUT
desc: |
A pointer to a reference to a newly allocated SODA database if the
function completes successfully. The function
[`dpiSodaDb_release()`] should be used when the database is no
longer required.
- name: dpiConn_getStmtCacheSize
desc: |
Returns the size of the statement cache, in number of statements.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection from which the size of the statement
cache is to be retrieved. If the reference is NULL or invalid, an
error is returned.
- name: cacheSize
type: uint32_t *
mode: OUT
desc: |
A pointer to the size of the statement cache, which will be
populated upon successful completion of this function.
- name: dpiConn_getTransactionInProgress
desc: |
Returns whether a transaction is in progress or not.
This function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the presence of a
transaction should be detected. If the reference is NULL or
invalid, an error is returned.
- name: txnInProgress
type: const int *
mode: OUT
desc: |
A pointer to the transaction in progress, which will be populated
with 0 (no transaction) or 1 (a transaction is in progress) upon
successful completion of this function.
- name: dpiConn_newDeqOptions
desc: |
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. This function is deprecated and will be removed in version
4. The function [`dpiQueue_getDeqOptions()`] should be used instead.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the dequeue is going to take
place. If the reference is NULL or invalid, an error is returned.
- name: options
type: dpiDeqOptions **
mode: OUT
desc: |
A pointer to a reference to the dequeue options that is created by
this function.
- name: dpiConn_newEnqOptions
desc: |
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. This function is deprecated and will be removed in version
4. The function [`dpiQueue_getEnqOptions()`] should be used instead.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the enqueue is going to take
place. If the reference is NULL or invalid, an error is returned.
- name: options
type: dpiEnqOptions **
mode: OUT
desc: |
A pointer to a reference to the enqueue options that is created by
this function.
- name: dpiConn_newJson
desc: |
Returns a reference to a new JSON object. This object can be used as the
payload in a message enqueued in a JSON queue, or as the value for a
variable. The reference should be released by calling
[`dpiJson_release()`] as soon as it is no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the JSON object is going to
be used. If the reference is NULL or invalid, an error is returned.
- name: json
type: dpiJson **
mode: OUT
desc: |
A pointer to a reference to the JSON object that is created by this
function.
- name: dpiConn_newJsonQueue
desc: |
Returns a reference to a new queue which enqueues and dequeues messages
from Advanced Queueing (AQ) with a JSON payload. The reference should be
released by calling [`dpiQueue_release()`] as soon as it is no longer
needed. For queues with RAW or Database Object payloads, use the method
[`dpiConn_newQueue()`] instead.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which messages are to be dequeued
or enqueued. If the reference is NULL or invalid, an error is
returned.
- name: name
type: const char *
mode: IN
desc: |
The name of the queue, as a byte string in the encoding used for
CHAR data. Note that UTF-16 encodings are not currently supported
by AQ.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: queue
type: dpiQueue **
mode: OUT
desc: |
A reference to the newly created queue which will be populated
upon successful completion of this function. The reference should
be released by calling [`dpiQueue_release()`] as soon as it is
no longer needed.
- name: dpiConn_newMsgProps
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the enqueue or dequeue is
going to take place. If the reference is NULL or invalid, an error
is returned.
- name: props
type: dpiMsgProps **
mode: OUT
desc: |
A pointer to a reference to the message properties that is created
by this function.
- name: dpiConn_newQueue
desc: |
Returns a reference to a new queue which may be used to enqueue and dequeue
messages from Advanced Queuing (AQ) queues. The reference should be
released by calling [`dpiQueue_release()`] as soon as it is no longer
needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which messages are to be dequeued
or enqueued. If the reference is NULL or invalid, an error is
returned.
- name: name
type: const char *
mode: IN
desc: |
The name of the queue, as a byte string in the encoding used for
CHAR data. Note that UTF-16 encodings are not currently supported
by AQ.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: payloadType
type: dpiObjectType *
mode: IN
desc: |
A reference to the object type which will be used for the payload
of messages that dequeued and enqueued. This value may also be
NULL in which case a RAW payload is dequeued and enqueued instead.
- name: queue
type: dpiQueue **
mode: OUT
desc: |
A reference to the newly created queue which will be populated
upon successful completion of this function. The reference should
be released by calling [`dpiQueue_release()`] as soon as it is
no longer needed.
- name: dpiConn_newTempLob
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the temporary LOB is to be
created. If the reference is NULL or invalid, an error is returned.
- name: lobType
type: dpiOracleTypeNum
mode: IN
desc: |
The type of LOB which should be created. It should be one of these
values from the enumeration
[`dpiOracleTypeNum`]: DPI_ORACLE_TYPE_CLOB,
DPI_ORACLE_TYPE_NCLOB or DPI_ORACLE_TYPE_BLOB.
- name: lob
type: dpiLob **
mode: OUT
desc: |
A pointer to a reference to the temporary LOB that is created by
this function, which will be populated upon successful completion
of this function.
- name: dpiConn_newVar
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection which this variable will be used for
binding or querying. If the reference is NULL or invalid, an error
is returned.
- name: oracleTypeNum
type: dpiOracleTypeNum
mode: IN
desc: |
The type of Oracle data that is to be used. It should be one of the
values from the enumeration [`dpiOracleTypeNum`].
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The type of native C data that is to be used. It should be one of the
values from the enumeration [`dpiNativeTypeNum`].
- name: maxArraySize
type: uint32_t
mode: IN
desc: |
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.
- name: size
type: uint32_t
mode: IN
desc: |
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 sizeIsBytes 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.
- name: sizeIsBytes
type: int
mode: IN
desc: |
A boolean value indicating if the size parameter refers to
characters or bytes. This flag is only used if the variable
refers to character data.
- name: isArray
type: int
mode: IN
desc: |
A boolean value indicating if the variable refers to a PL/SQL
array or simply to buffers used for binding or fetching data.
- name: objType
type: dpiObjectType *
mode: IN
desc: |
A reference to the object type of the object that is being bound
or fetched. This value is only used if the Oracle type is
DPI_ORACLE_TYPE_OBJECT.
- name: var
type: dpiVar **
mode: OUT
desc: |
A pointer to a reference to the variable that is created by this
function.
- name: data
type: dpiData **
mode: OUT
desc: |
A pointer to an array of [`dpiData`] structures that
are used to transfer data to/from the variable. These are allocated
when the variable is created and the number of structures
corresponds to the maxArraySize.
- name: dpiConn_newVector
desc: |
Returns a reference to a new vector object. This object can be used as the
value for a variable. The reference should be released by calling
[`dpiVector_release()`] as soon as it is no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the vector object is going
to be used. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiVectorInfo *
mode: IN
desc: |
A pointer to a structure of type
[`dpiVectorInfo`] which contains the information
needed to populate the vector. A value of NULL is acceptable in
which the vector will be empty and a call to
[`dpiVector_setValue()`] will be needed bofore it can be used.
- name: vector
type: dpiVector **
mode: OUT
desc: |
A pointer to a reference to the vector object that is created by
this function.
- name: dpiConn_ping
desc: |
Pings the database to determine if a connection is usable.
This function does the local, light-weight checks of
[`dpiConn_getIsHealthy()`] and additionally performs a round-trip to
the database if the local checks are successful.
The session pool internally may perform this check before returning a
connection to the application. This depends on the value of
DPI_DEFAULT_PING_INTERVAL and when the connection was returned to the pool.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
If DPI_FAILURE is returned, the application should close the connection.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection which will be pinged. If the
reference is NULL or invalid, an error is returned.
- name: dpiConn_prepareStmt
desc: |
Returns a reference to a statement prepared for execution. The reference
should be released as soon as it is no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection on which the statement is to be
prepared. If the reference is NULL or invalid, an error is
returned.
- name: scrollable
type: int
mode: IN
desc: |
A boolean indicating if the statement is scrollable or not. If it
is scrollable, [`dpiStmt_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.
- name: sql
type: const char *
mode: IN
desc: |
The SQL that is to be prepared for execution, as a byte string in
the encoding used for CHAR data. The value can also be NULL if the
tag parameter is specified.
- name: sqlLength
type: uint32_t
mode: IN
desc: |
The length of the SQL that is to be prepared for execution, in
bytes, or 0 if the sql parameter is NULL.
- name: tag
type: const char *
mode: IN
desc: |
The key to be used for searching for the statement in the statement
cache, as a byte string in the encoding used for CHAR data. The
value can also be NULL if the sql parameter is specified.
- name: tagLength
type: uint32_t
mode: IN
desc: |
The length of the key to be used for searching for the statement
in the statement cache, in bytes, or 0 if the tag parameter is
NULL.
- name: stmt
type: dpiStmt **
mode: OUT
desc: |
A pointer to a reference to the statement that was just prepared,
which will be populated upon successful completion of the function.
- name: dpiConn_release
desc: |
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 [`dpiConn_close()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
The connection from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiConn_rollback
desc: |
Rolls back the current active transaction.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection which holds the transaction which
is to be rolled back. If the reference is NULL or invalid, an
error is returned.
- name: dpiConn_setAction
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the action attribute is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data which
will be used to set the action attribute.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setCallTimeout
desc: |
Sets the call timeout (in milliseconds) to be used for round-trips to the
database made with this connection. A value of 0 means that no timeouts
will take place. The current value can be acquired using the function
[`dpiConn_getCallTimeout()`].
The call timeout value applies to each database round-trip
individually, not to the sum of all round-trips. Time spent
processing in ODPI-C before or after the completion of each
round-trip is not counted.
After a timeout is triggered, ODPI-C attempts to clean up the
internal connection state. The cleanup is allowed to take another
`value` milliseconds.
If the cleanup was successful, an exception DPI-1067 will be
raised but the application can continue to use the connection.
For small values of call timeout, the connection cleanup may not
complete successfully within the additional call timeout
period. In this case an exception ORA-3114 is raised and the
connection will no longer be usable. It should be closed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection on which the current call timeout is
to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t
mode: IN
desc: |
The value to use (in milliseconds) for round-trips to the database
made with this connection. A value of 0 means that no timeouts will
take place.
- name: dpiConn_setClientIdentifier
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the client identifier
attribute is to be set. If the reference is NULL or invalid, an
error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data
which will be used to set the client identifier attribute.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setClientInfo
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the client info attribute
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data
which will be used to set the client info attribute.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setCurrentSchema
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the current schema is to be
set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data
which will be used to set the current schema.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setDbOp
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the database operation
attribute is to be set. If the reference is NULL or invalid, an
error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data
which will be used to set the database operation attribute.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setEcontextId
desc: |
Sets the execution context id 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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the execution context id
attribute is to be set. If the reference is NULL or invalid, an
error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data
which will be used to set the module attribute.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setExternalName
desc: |
Sets the external name that is being used by the connection. This value is
used when logging distributed transactions.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the external name is to be
set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data which
will be used to set the external name.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setInternalName
desc: |
Sets the internal name that is being used by the connection. This value is
used when logging distributed transactions.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the internal name is to be
set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data which
will be used to set the internal name.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setModule
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the module attribute is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data which
will be used to set the module attribute.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value that is to be set, in bytes.
- name: dpiConn_setOciAttr
desc: |
Sets the value of an OCI attribute. This is intended solely for testing
attributes that are not otherwise supported by ODPI-C and should not be
used for any other purpose. Use only as directed by Oracle.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection on which the OCI attribute is to be
set. If the reference is NULL or invalid, an error is returned.
- name: handleType
type: uint32_t
mode: IN
desc: |
The type of OCI handle that is to be used. This should be one of
3 (service context handle), 8 (server handle) or 9
(session handle).
- name: attribute
type: uint32_t
mode: IN
desc: |
The attribute to set.
- name: value
type: void *
mode: IN
desc: |
A pointer to the data which is to be set.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the data which is to be set.
- name: dpiConn_setStmtCacheSize
desc: |
Sets the size of the statement cache.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the size of the statement
cache is to be set. If the reference is NULL or invalid, an error
is returned.
- name: cacheSize
type: uint32_t
mode: IN
desc: |
The new size of the statement cache, in number of statements.
- name: dpiConn_shutdownDatabase
desc: |
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.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection to the database which is to be shut
down. If the reference is NULL or invalid, an error is returned.
The connection needs to have been established at least with
authorization mode set to DPI_MODE_AUTH_SYSDBA or
DPI_MODE_AUTH_SYSOPER.
- name: mode
type: dpiShutdownMode
mode: IN
desc: |
One of the values from the enumeration
[`dpiShutdownMode`].
- name: dpiConn_startupDatabaseWithPfile
desc: |
Starts up a database with a parameter file (PFILE).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection to the database which is to be
started up. If the reference is NULL or invalid, an error is
returned. The connection must be created with the authorization
mode set to DPI_MODE_AUTH_PRELIM along with one of
DPI_MODE_AUTH_SYSDBA or DPI_MODE_AUTH_SYSOPER.
- name: pfile
type: const char *
mode: IN
desc: |
A pointer to a byte string in the encoding used for CHAR data
which identifies the name of the parameter file (PFILE) that will
be used to startup the database. This value may be NULL if the
pfileLength parameter is zero. In that case this function behaves
identically to the [`dpiConn_startupDatabase()`] function.
- name: pfileLength
type: uint32_t
mode: IN
desc: |
The length of the pfile parameter, in bytes.
- name: mode
type: dpiStartupMode
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiStartupMode`], OR’ed together.
- name: dpiConn_startupDatabase
desc: |
Starts up a database.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection to the database which is to be
started up. If the reference is NULL or invalid, an error is
returned. The connection must be created with the authorization
mode set to DPI_MODE_AUTH_PRELIM along with one of
DPI_MODE_AUTH_SYSDBA or DPI_MODE_AUTH_SYSOPER.
- name: mode
type: dpiStartupMode
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiStartupMode`], OR’ed together.
- name: dpiConn_subscribe
desc: |
Returns a reference to a subscription which is used for requesting
notifications of events that take place in the database. Events that are
supported are changes on tables or queries (continuous query notification)
and the availability of messages to dequeue (advanced queuing). The
reference should be released as soon as it is no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the subscription is to be
created. If the reference is NULL or invalid, an error is returned.
- name: params
type: dpiSubscrCreateParams *
mode: IN
desc: |
A pointer to a [`dpiSubscrCreateParams`]
structure which is used to specify parameters for the subscription.
These parameters determine what events will result in notifications.
- name: subscr
type: dpiSubscr **
mode: OUT
desc: |
A pointer to a reference to the subscription that is created by this
function.
- name: dpiConn_tpcBegin
desc: |
Begins a new TPC (two-phase commit) transaction with the given transaction
id (XID).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the transaction is to begin.
If the reference is NULL or invalid, an error is returned.
- name: xid
type: dpiXid *
mode: IN
desc: |
A pointer to a structure of type [`dpiXid`] which
identifies the TPC transaction which is to begin.
- name: transactionTimeout
type: uint32_t
mode: IN
desc: |
The duration in seconds to wait for a transaction to become
available for resumption when the flags parameter is one of
DPI_TPC_BEGIN_RESUME or DPI_TPC_BEGIN_JOIN. When DPI_TPC_BEGIN_NEW
is specified for the flags parameter, this parameter indicates the
number of seconds the transaction can be inactive before it is
automatically terminated by the system.
- name: flags
type: uint32_t
mode: IN
desc: |
One of the values from the enumeration
[`dpiTpcBeginFlags`].
- name: dpiConn_tpcCommit
desc: |
Commits a TPC (two-phase commit) transaction.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the transaction is to be
committed. If the reference is NULL or invalid, an error is
returned.
- name: xid
type: dpiXid *
mode: IN
desc: |
A pointer to a structure of type [`dpiXid`] which
identifies the TPC transaction which is to be committed. If this
value is NULL, the XID associated with the connection via the
last TPC call is used and this function becomes equivalent to
[`dpiConn_commit()`].
- name: onePhase
type: int
mode: IN
desc: |
Specifies whether to perform a one phase commit (1) or a two-phase
commit (0) if the xid parameter is not NULL. If the xid parameter
is NULL the connection already knows what type of commit is
needed and this parameter is ignored.
- name: dpiConn_tpcEnd
desc: |
Ends a TPC (two-phase commit) transaction with the given transaction
id (XID).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the transaction is to end.
If the reference is NULL or invalid, an error is returned.
- name: xid
type: dpiXid *
mode: IN
desc: |
A pointer to a structure of type [`dpiXid`] which
identifies the TPC transaction which is to end. If this value is
NULL, the XID associated with the connection via the last TPC call
is used.
- name: flags
type: uint32_t
mode: IN
desc: |
One of the values from the enumeration
[`dpiTpcEndFlags`].
- name: dpiConn_tpcForget
desc: |
Forgets a TPC (two-phase commit) transaction.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the transaction is to be
forgotten. If the reference is NULL or invalid, an error is
returned.
- name: xid
type: dpiXid *
mode: IN
desc: |
A pointer to a structure of type [`dpiXid`] which
identifies the TPC transaction which is to be forgotten.
- name: dpiConn_tpcPrepare
desc: |
Prepares a TPC (two-phase commit) transaction for commit. This function
should only be called after [`dpiConn_tpcBegin()`] is called and before
[`dpiConn_tpcCommit()`] or [`dpiConn_commit()`] is called.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the transaction is to be
prepared. If the reference is NULL or invalid, an error is
returned.
- name: xid
type: dpiXid *
mode: IN
desc: |
A pointer to a structure of type [`dpiXid`] which
identifies the TPC transaction which is to be prepared. If this
value is NULL, the XID associated with the connection during the
previous call to [`dpiConn_tpcBegin()`] is used.
- name: commitNeeded
type: int *
mode: OUT
desc: |
A pointer to a boolean value indicating if a commit is needed or
not. If no commit is needed, attempting to commit anyway will
result in an ORA-24756 error (transaction does not exist).
- name: dpiConn_tpcRollback
desc: |
Rolls back a TPC (two-phase commit) transaction.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the transaction is to be
rolled back. If the reference is NULL or invalid, an error is
returned.
- name: xid
type: dpiXid *
mode: IN
desc: |
A pointer to a structure of type [`dpiXid`] which
identifies the TPC transaction which is to be rolled back. If this
value is NULL, the XID associated with the connection via the
last TPC call is used and this function becomes equivalent to
[`dpiConn_rollback()`].
- name: dpiConn_unsubscribe
desc: |
Unsubscribes from the events that were earlier subscribed to via the
function [`dpiConn_subscribe()`]. Once this function completes
successfully no further notifications will be sent for this subscription.
Note that this method does not generate a notification either.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: conn
type: dpiConn *
mode: IN
desc: |
A reference to the connection in which the subscription is to be
destroyed. If the reference is NULL or invalid, an error is
returned. The connection used to unsubscribe should be the same
connection used to subscribe or should access the same database and
be connected as the same user name.
- name: subscr
type: dpiSubscr *
mode: OUT
desc: |
A pointer to a reference to the subscription that is to be
destroyed. A reference will be released and the subscription will
no longer be usable once this function completes successfully.
- name: dpiContext
kind: opaque struct
desc: |
Context handles are the top level handles created by the library and are used
for all error handling as well as creating pools and standalone connections to
the database. The first call to ODPI-C by any application must be
[`dpiContext_createWithParams()`] which will create the context as well as
validate the version used by the application. Context handles are destroyed by
using the function [`dpiContext_destroy()`].
functions:
- name: dpiContext_createWithParams
desc: |
Creates a new context for interaction with the library. This is the first
function that must be called and it must have completed successfully before
any other functions can be called, including in other threads.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
If a failure occurs, the errorInfo structure is filled in with error
information.
round_trips: No
return: int
params:
- name: majorVersion
type: unsigned int
mode: IN
desc: |
The major version of the ODPI-C library that is being used by the
application. This should always be the constant value
DPI_MAJOR_VERSION defined in the dpi.h being used by the
application. It must match the major version of the ODPI-C library
that is being linked to the application.
- name: minorVersion
type: unsigned int
mode: IN
desc: |
The minor version of the ODPI-C library that is being used by the
application. This should always be the constant value
DPI_MINOR_VERSION defined in the dpi.h being used by the
application. It must be less than or equal to the minor version of
the ODPI-C library that is being linked to the application.
- name: params
type: dpiContextCreateParams *
mode: IN
desc: |
A pointer to a
[`dpiContextCreateParams`] structure
containing parameters used to modify how ODPI-C loads the Oracle
Client library. Although it is possible to create multiple
contexts, only the first context created will use these
parameters. This value can also be NULL in which case default
parameters will be used.
- name: context
type: dpiContext **
mode: OUT
desc: |
A pointer to a context handle which will be populated upon
successful completion of this function.
- name: errorInfo
type: dpiErrorInfo *
mode: OUT
desc: |
A pointer to a [`dpiErrorInfo`] structure which
will be populated with error information if an error takes place
during the execution of this function. If no error takes place,
the structure is not modified in any way. Note that the only
members of the structure that should be examined when an error
occurs are message, messageLength, encoding, fnName, and action.
- name: dpiContext_destroy
desc: |
Destroys the context that was earlier created with the function
[`dpiContext_createWithParams()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: dpiContext *
mode: IN
desc: |
The context handle which should be destroyed. If the handle is NULL
or invalid, an error is returned.
- name: dpiContext_freeStringList
desc: |
Frees the memory associated with the string list allocated by a call to
one of the functions [`dpiSodaDb_getCollectionNames()`]
or [`dpiSodaColl_listIndexes()`]. This function should not be
called without first calling one of those functions first.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: dpiContext *
mode: IN
desc: |
A reference to the context in which the string list was allocated.
- name: list
type: dpiStringList *
mode: IN
desc: |
A pointer to a structure of type
[`dpiStringList`] which was previously
used in a call to [`dpiSodaDb_getCollectionNames()`] or
[`dpiSodaColl_listIndexes()`].
- name: dpiContext_getClientVersion
desc: |
Return information about the version of the Oracle Client that is being
used.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: versionInfo
type: dpiVersionInfo *
mode: OUT
desc: |
A pointer to a [`dpiVersionInfo`] structure
which will be populated with the version information of the Oracle
Client being used.
- name: dpiContext_getError
desc: |
Returns information for the last error or warning that was raised by the
library. This function must be called with the same thread that generated
the error or warning. It must also be called before any other ODPI-C
library calls are made on the calling thread since the error/warning
information specific to that thread is cleared at the start of every ODPI-C
function call.
round_trips: No
return: void
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, the error information is populated with an invalid context
handle error instead.
- name: errorInfo
type: dpiErrorInfo *
mode: OUT
desc: |
A pointer to a [`dpiErrorInfo`] structure which
will be populated with information about the last error or warning
that was raised. If a warning was raised, the
[`dpiErrorInfo.isWarning`] flag will be set to the value 1.
- name: dpiContext_initCommonCreateParams
desc: |
Initializes the [`dpiCommonCreateParams`]
structure to default values.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: params
type: dpiContextParams *
mode: OUT
desc: |
A pointer to a [`dpiCommonCreateParams`]
structure which will be populated with default values upon
completion of this function.
- name: dpiContext_initConnCreateParams
desc: |
Initializes the [`dpiConnCreateParams`] structure
to default values.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: params
type: dpiConnCreateParams *
mode: OUT
desc: |
A pointer to a [`dpiConnCreateParams`]
structure which will be populated with default values upon
completion of this function.
- name: dpiContext_initPoolCreateParams
desc: |
Initializes the [`dpiPoolCreateParams`] structure
to default values.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: params
type: dpiPoolCreateParams *
mode: OUT
desc: |
A pointer to a [`dpiPoolCreateParams`]
structure which will be populated with default values upon
completion of this function.
- name: dpiContext_initSodaOperOptions
desc: |
Initializes the [`dpiSodaOperOptions`]
structure to default values.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: options
type: dpiSodaOperOptions *
mode: OUT
desc: |
A pointer to a [`dpiSodaOperOptions`]
structure which will be populated with default values upon
completion of this function.
- name: dpiContext_initSubscrCreateParams
desc: |
Initializes the [`dpiSubscrCreateParams`]
structure to default values.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: params
type: dpiSubscrCreateParams *
mode: OUT
desc: |
A pointer to a [`dpiSubscrCreateParams`]
structure which will be populated with default values upon completion
of this function.
- name: dpiDeqOptions
kind: opaque struct
desc: |
Dequeue option handles are used to represent the options specified when
dequeuing messages using advanced queueing. They are created by calling the
function [`dpiConn_newDeqOptions()`] and are destroyed by releasing the
last reference by calling the function [`dpiDeqOptions_release()`].
functions:
- name: dpiDeqOptions_addRef
desc: |
Adds a reference to the dequeue options. This is intended for situations
where a reference to the dequeue options needs to be maintained
independently of the reference returned when the handle was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
The dequeue options to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiDeqOptions_getCondition
desc: |
Returns the condition that must be satisfied in order for a message to be
dequeued. See function [`dpiDeqOptions_setCondition()`] for more
information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the condition is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no condition, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there
is no condition, the pointer will be populated with the value 0.
- name: dpiDeqOptions_getConsumerName
desc: |
Returns the name of the consumer that is dequeuing messages. See function
[`dpiDeqOptions_setConsumerName()`] for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the consumer name
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no consumer name, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there
is no consumer name, the pointer will be populated with the value
0.
- name: dpiDeqOptions_getCorrelation
desc: |
Returns the correlation of the message to be dequeued. See function
[`dpiDeqOptions_setCorrelation()`] for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the correlation
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no correlation, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there
is no correlation, the pointer will be populated with the value
0.
- name: dpiDeqOptions_getMode
desc: |
Returns the mode that is to be used when dequeuing messages.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the mode is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: dpiDeqMode *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. It will be one of the values from
the enumeration [`dpiDeqMode`].
- name: dpiDeqOptions_getMsgId
desc: |
Returns the identifier of the specific message that is to be dequeued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the message
identifier is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. If there is no message identifier, the
pointer will be populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there
is no message identifier, the pointer will be populated with the
value 0.
- name: dpiDeqOptions_getNavigation
desc: |
Returns the position of the message that is to be dequeued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the navigation
option is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: value
type: dpiDeqNavigation *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. It will be one of the values from
the enumeration [`dpiDeqNavigation`].
- name: dpiDeqOptions_getTransformation
desc: |
Returns the transformation of the message to be dequeued. See function
[`dpiDeqOptions_setTransformation()`] for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the transformation
is to be retrieved. If the reference is NULL or invalid, an
error is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no transformation, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there is
no transformation, the pointer will be populated with the value 0.
- name: dpiDeqOptions_getVisibility
desc: |
Returns whether the message being dequeued is part of the current
transaction or constitutes a transaction on its own.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the visibility
is to be retrieved. If the reference is NULL or invalid, an
error is returned.
- name: value
type: dpiVisibility *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. It will be one of the values from
the enumeration [`dpiVisibility`].
- name: dpiDeqOptions_getWait
desc: |
Returns the time to wait, in seconds, for a message matching the search
criteria. See function [`dpiDeqOptions_setWait()`] for more
information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options from which the wait time
is to be retrieved. If the reference is NULL or invalid, an
error is returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function.
- name: dpiDeqOptions_release
desc: |
Releases a reference to the dequeue options. A count of the references to
the dequeue options is maintained and when this count reaches zero, the
memory associated with the options is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
The dequeue options from which a reference is to be released. If
the reference is NULL or invalid, an error is returned.
- name: dpiDeqOptions_setCondition
desc: |
Sets the condition which must be true for messages to be dequeued. The
condition must be a valid boolean expression similar to the where clause
of a SQL query. The expression can include conditions on message
properties, user data properties and PL/SQL or SQL functions. User data
properties must be prefixed with tab.user_data as a qualifier to indicate
the specific column of the queue table that stores the message payload.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the condition is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
condition is to be cleared.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiDeqOptions_setConsumerName
desc: |
Sets the name of the consumer which will be dequeuing messages. This value
should only be set if the queue is set up for multiple consumers.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the consumer name is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
consumer name is to be cleared.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiDeqOptions_setCorrelation
desc: |
Sets the correlation of the message to be dequeued. Special pattern
matching characters such as the percent sign (%) and the underscore (_)
can be used. If multiple messages satisfy the pattern, the order of
dequeuing is undetermined.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the correlation is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
correlation is to be cleared.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiDeqOptions_setDeliveryMode
desc: |
Sets the message delivery mode that is to be used when dequeuing messages.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the message delivery
mode is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: dpiMessageDeliveryMode
mode: IN
desc: |
The mode that should be used. It should be one of the values from
the enumeration [`dpiMessageDeliveryMode`].
- name: dpiDeqOptions_setMode
desc: |
Sets the mode that is to be used when dequeuing messages.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the mode is to be set.
If the reference is NULL or invalid, an error is returned.
- name: value
type: dpiDeqMode
mode: IN
desc: |
The mode that should be used. It should be one of the values from
the enumeration [`dpiDeqMode`].
- name: dpiDeqOptions_setMsgId
desc: |
Sets the identifier of the specific message to be dequeued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the message identifier
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to the bytes making up the message identifier, or NULL
if no specific message is to be dequeued.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiDeqOptions_setNavigation
desc: |
Sets the position in the queue of the message that is to be dequeued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the navigation option
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: dpiDeqNavigation
mode: IN
desc: |
The value that should be used. It should be one of the values
from the enumeration [`dpiDeqNavigation`].
- name: dpiDeqOptions_setTransformation
desc: |
Sets the transformation of the message to be dequeued. The transformation
is applied after the message is dequeued but before it is returned to the
application. It must be created using DBMS_TRANSFORM.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the transformation
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
transformation is to be cleared.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiDeqOptions_setVisibility
desc: |
Sets whether the message being dequeued is part of the current transaction
or constitutes a transaction on its own.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the visibility
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: dpiVisibility
mode: IN
desc: |
The value that should be used. It should be one of the values
from the enumeration [`dpiVisibility`].
- name: dpiDeqOptions_setWait
desc: |
Set the time to wait, in seconds, for a message matching the search
criteria.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiDeqOptions *
mode: IN
desc: |
A reference to the dequeue options on which the wait time is to
be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t
mode: IN
desc: |
The number of seconds to wait for a message matching the search
criteria. Any integer is valid but the predefined constants
DPI_DEQ_WAIT_NO_WAIT and DPI_DEQ_WAIT_FOREVER are provided as a
convenience.
- name: dpiEnqOptions
kind: opaque struct
desc: |
Enqueue option handles are used to represent the options specified when
enqueuing messages using advanced queueing. They are created by calling the
function [`dpiConn_newEnqOptions()`] and are destroyed by releasing the
last reference by calling the function [`dpiEnqOptions_release()`].
functions:
- name: dpiEnqOptions_addRef
desc: |
Adds a reference to the enqueue options. This is intended for situations
where a reference to the enqueue options needs to be maintained
independently of the reference returned when the handle was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
The enqueue options to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiEnqOptions_getTransformation
desc: |
Returns the transformation of the message to be enqueued. See function
[`dpiEnqOptions_setTransformation()`] for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
A reference to the enqueue options from which the transformation is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no transformation, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there is
no transformation, the pointer will be populated with the value 0.
- name: dpiEnqOptions_getVisibility
desc: |
Returns whether the message being enqueued is part of the current
transaction or constitutes a transaction on its own.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
A reference to the enqueue options from which the visibility is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: dpiVisibility *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. It will be one of the values from
the enumeration [`dpiVisibility`].
- name: dpiEnqOptions_release
desc: |
Releases a reference to the enqueue options. A count of the references to
the enqueue options is maintained and when this count reaches zero, the
memory associated with the options is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
The enqueue options from which a reference is to be released. If
the reference is NULL or invalid, an error is returned.
- name: dpiEnqOptions_setDeliveryMode
desc: |
Sets the message delivery mode that is to be used when enqueuing messages.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
A reference to the enqueue options on which the message delivery
mode is to be set. If the reference is NULL or invalid, an error
is returned.
- name: value
type: dpiMessageDeliveryMode
mode: IN
desc: |
The mode that should be used. It should be one of the values from
the enumeration
[`dpiMessageDeliveryMode`].
- name: dpiEnqOptions_setTransformation
desc: |
Sets the transformation of the message to be enqueued. The transformation
is applied after the message is enqueued but before it is returned to the
application. It must be created using DBMS_TRANSFORM.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
A reference to the enqueue options on which the transformation is
to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
transformation is to be cleared.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiEnqOptions_setVisibility
desc: |
Sets whether the message being enqueued is part of the current transaction
or constitutes a transaction on its own.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: options
type: dpiEnqOptions *
mode: IN
desc: |
A reference to the enqueue options on which the visibility is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: dpiVisibility
mode: IN
desc: |
The value that should be used. It should be one of the values from
the enumeration [`dpiVisibility`].
- name: dpiJson
kind: opaque struct
desc: |
JSON handles are used to represent JSON values stored in the database. They are
only available from Oracle Client and Database 20 and higher. They cannot be
created directly but are created implicitly when a variable of type
DPI_ORACLE_TYPE_JSON is created. They are destroyed when the last reference is
released by a call to the function [`dpiJson_release()`].
functions:
- name: dpiJson_addRef
desc: |
Adds a reference to the JSON value. This is intended for situations where a
reference to the JSON value needs to be maintained independently of the
reference returned when the JSON value was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: json
type: dpiJson *
mode: IN
desc: |
The JSON value to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiJson_getValue
desc: |
Returns the top node of a hierarchy of nodes containing the data stored in
the JSON value.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: json
type: dpiJson *
mode: IN
desc: |
The JSON value from which the top node is to be returned. If the
reference is NULL or invalid, an error is returned.
- name: options
type: uint32_t
mode: IN
desc: |
One or more of the values from the
[`dpiJsonOptions`] enumerations, OR’ed together.
- name: topNode
type: dpiJsonNode **
mode: OUT
desc: |
A pointer to the top node of the JSON value, which will be
populated upon successful completion of this function. It is a
structure of type [`dpiJsonNode`] and will remain
valid as long as a reference is held to the JSON value and as long
as the JSON value is not modified by call to
[`dpiJson_setValue()`].
- name: dpiJson_release
desc: |
Releases a reference to the JSON value. A count of the references to the
JSON value is maintained and when this count reaches zero, the memory
associated with the JSON value is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: json
type: dpiJson *
mode: IN
desc: |
The JSON value from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiJson_setFromText
desc: |
Sets the JSON value from the JSON string passed as a byte string.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: json
type: dpiJson *
mode: IN
desc: |
The JSON value which is to be modified to contain the data from
input JSON string. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to the JSON string which contains the data to be set.
This value can be NULL if the valueLength parameter is 0.
- name: valueLength
type: uint64_t
mode: IN
desc: |
The length of the data to be set, in bytes.
- name: flags
type: uint32_t
mode: IN
desc: |
Flags which can be used in the future to adjust how text is
converted to JSON. Pass 0 for now.
- name: dpiJson_setValue
desc: |
Sets the JSON value to the data found in the hierarchy of nodes pointed to
by the top level node.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: json
type: dpiJson *
mode: IN
desc: |
The JSON value which is to be modified to contain the data found
in the hierarchy of nodes pointed to by the top node. If the
reference is NULL or invalid, an error is returned.
- name: topNode
type: dpiJsonNode *
mode: IN
desc: |
A pointer to the top node of the data which will replace the data
in the JSON value. It is a structure of type
[`dpiJsonNode`].
- name: dpiLob
kind: opaque struct
desc: |
LOB handles are used to represent large objects (CLOB, BLOB, NCLOB, BFILE).
Both persistent and temporary large objects can be represented. LOB handles can
be created by calling the function [`dpiConn_newTempLob()`] or are created
implicitly when a variable of type DPI_ORACLE_TYPE_CLOB, DPI_ORACLE_TYPE_NCLOB,
DPI_ORACLE_TYPE_BLOB or DPI_ORACLE_TYPE_BFILE is created and are destroyed when
the last reference is released by calling the function
[`dpiLob_release()`]. They are used for reading and writing data to the
database in smaller pieces than is contained in the large object.
functions:
- name: dpiLob_addRef
desc: |
Adds a reference to the LOB. This is intended for situations where a
reference to the LOB needs to be maintained independently of the reference
returned when the LOB was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB to which a reference is to be added. If the reference is
NULL or invalid, an error is returned.
- name: dpiLob_close
desc: |
Closes the LOB and makes it unusable for further operations immediately,
rather than when the reference count reaches zero.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB which is to be closed. If the reference
is NULL or invalid, an error is returned.
- name: dpiLob_closeResource
desc: |
Closes the LOB resource. This should be done when a batch of writes has
been completed so that the indexes associated with the LOB can be updated.
It should only be performed if a call to function
[`dpiLob_openResource()`] has been performed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB which will be closed. If the reference is
NULL or invalid, an error is returned.
- name: dpiLob_copy
desc: |
Creates an independent copy of a LOB and returns a reference to the newly
created LOB. This reference should be released as soon as it is no longer
needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB which is to be copied. If the reference is NULL or invalid
an error is returned.
- name: copiedLob
type: dpiLob **
mode: OUT
desc: |
A pointer to a reference to the LOB which is created as a copy of
the first LOB, which is populated upon successful completion of
this function.
- name: dpiLob_getBufferSize
desc: |
Returns the size of the buffer needed to hold the number of characters
specified for a buffer of the type associated with the LOB. If the LOB does
not refer to a character LOB the value is returned unchanged.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB in which the buffer is going to be used for
transferring data to and from Oracle. If the reference is NULL or
invalid an error is returned.
- name: sizeInChars
type: uint64_t
mode: IN
desc: |
The number of characters for which a buffer size needs to be
determined.
- name: sizeInBytes
type: uint64_t *
mode: OUT
desc: |
A pointer to the size in bytes which will be populated when the
function has completed successfully.
- name: dpiLob_getChunkSize
desc: |
Returns the chunk size, in bytes, of the internal LOB. Reading and writing
to the LOB in multiples of this size will improve performance.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB from which the chunk size is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: size
type: uint32_t *
mode: OUT
desc: |
A pointer to the chunk size, in bytes, which will be populated
when this function completes successfully.
- name: dpiLob_getDirectoryAndFileName
desc: |
Returns the directory alias name and file name for a BFILE type LOB.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB from which the directory alias name and
file name are to be retrieved. If the reference is NULL or
invalid, an error is returned.
- name: directoryAlias
type: const char **
mode: OUT
desc: |
A pointer to the name of the directory alias, as a byte string in
the encoding used for CHAR data, which will be populated upon
successful completion of this function. The string returned will
remain valid as long as a reference to the LOB is held.
- name: directoryAliasLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the name of the directory alias, in
bytes, which will be populated upon successful completion of this
function.
- name: fileName
type: const char **
mode: OUT
desc: |
A pointer to the name of the file, as a byte string in the
encoding used for CHAR data, which will be populated upon
successful completion of this function. The string returned will
remain valid as long as a reference to the LOB is held.
- name: fileNameLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the name of the file, in bytes, which
will be populated upon successful completion of this function.
- name: dpiLob_getFileExists
desc: |
Returns a boolean value indicating if the file referenced by the BFILE type
LOB exists (1) or not (0).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB which will be checked to see if the
associated file exists. If the reference is NULL or invalid, an
error is returned.
- name: exists
type: int *
mode: OUT
desc: |
A pointer to the boolean value which will be populated when this
function completes successfully.
- name: dpiLob_getIsResourceOpen
desc: |
Returns a boolean value indicating if the LOB resource has been opened by
making a call to the function [`dpiLob_openResource()`] (1) or not (0).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB which will be checked to see if it is open.
If the reference is NULL or invalid, an error is returned.
- name: isOpen
type: int *
mode: OUT
desc: |
A pointer to the boolean value which will be populated when this
function completes successfully.
- name: dpiLob_getSize
desc: |
Returns the size of the data stored in the LOB. For character LOBs the size
is in characters; for binary LOBs the size is in bytes.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
**WARNING**: for historical reasons, Oracle stores CLOBs and NCLOBs using
the UTF-16 encoding, regardless of what encoding is otherwise in use by the
database. The number of characters, however, is defined by the number of
UCS-2 codepoints. For this reason, if a character requires more than one
UCS-2 codepoint, the size returned will be inaccurate and care must be
taken to account for the difference.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB from which the size will be retrieved. If
the reference is NULL or invalid, an error is returned.
- name: size
type: uint64_t *
mode: OUT
desc: |
A pointer to the value which will be populated when this function
completes successfully.
- name: dpiLob_getType
desc: |
Returns the type of the LOB.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB from which the type will be retrieved. If
the reference is NULL or invalid, an error is returned.
- name: type
type: dpiOracleTypeNum *
mode: OUT
desc: |
A pointer to the value which will be populated when this function
completes successfully. It will one of the values from the
enumeration [`dpiOracleTypeNum`] -
*DPI_ORACLE_TYPE_CLOB*, *DPI_ORACLE_TYPE_NCLOB*,
*DPI_ORACLE_TYPE_BLOB* or *DPI_ORACLE_TYPE_BFILE*.
- name: dpiLob_openResource
desc: |
Opens the LOB resource for writing. This will improve performance when
writing to the LOB in chunks and there are functional or extensible indexes
associated with the LOB. If this function is not called, the LOB resource
will be opened and closed for each write that is performed. A call to the
function [`dpiLob_closeResource()`] should be done before performing a
call to the function [`dpiConn_commit()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB which will be opened. If the reference
is NULL or invalid, an error is returned.
- name: dpiLob_readBytes
desc: |
Reads data from the LOB at the specified offset into the provided buffer.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
**WARNING**: for historical reasons, Oracle stores CLOBs and NCLOBs using
the UTF-16 encoding, regardless of what encoding is otherwise in use by the
database. The number of characters, however, is defined by the number of
UCS-2 codepoints. For this reason, if a character requires more than one
UCS-2 codepoint, care must be taken to account for them in both the offset
and amount parameters.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB from which data is to be read. If the reference is NULL
or invalid, an error is returned.
- name: offset
type: uint64_t
mode: IN
desc: |
The offset into the LOB data from which to start reading. The
first position is 1. For character LOBs this represents the number
of characters from the beginning of the LOB; for binary LOBS, this
represents the number of bytes from the beginning of the LOB.
- name: amount
type: uint64_t
mode: IN
desc: |
The maximum number of characters (for character LOBs) or the
maximum number of bytes (for binary LOBs) that will be read from
the LOB. If reading from a character LOB, the buffer size required
can be calculated by taking the number of characters and
multiplying by the maximum number of bytes per character. This
will be [`dpiEncodingInfo.maxBytesPerCharacter`] for CLOBs
and [`dpiEncodingInfo.nmaxBytesPerCharacter`] for NCLOBs.
- name: value
type: char *
mode: OUT
desc: |
The buffer into which the data is read. It is assumed to contain
the number of bytes specified in the valueLength parameter.
- name: valueLength
type: uint64_t *
mode: IN/OUT
desc: |
A pointer to the size of the value. When this function is called
it must contain the maximum number of bytes in the buffer
specified by the value parameter. After the function is completed
successfully it will contain the actual number of bytes read into
the buffer.
- name: dpiLob_release
desc: |
Releases a reference to the LOB. A count of the references to the LOB is
maintained and when this count reaches zero, the memory associated with the
LOB is freed. The LOB is also closed unless that has already taken place
using the function [`dpiLob_close()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB from which a reference is to be released. If the reference
is NULL or invalid, an error is returned.
- name: dpiLob_setDirectoryAndFileName
desc: |
Sets the directory alias name and file name for a BFILE type LOB.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB on which the directory alias name and file
name are to be set. If the reference is NULL or invalid, an error
is returned.
- name: directoryAlias
type: const char *
mode: IN
desc: |
The name of the directory alias, as a byte string in the encoding
used for CHAR data.
- name: directoryAliasLength
type: uint32_t
mode: IN
desc: |
The length of the directoryAlias parameter, in bytes.
- name: fileName
type: const char *
mode: IN
desc: |
The name of the file, as a byte string in the encoding used for
CHAR data.
- name: fileNameLength
type: uint32_t
mode: IN
desc: |
The length of the fileName parameter, in bytes.
- name: dpiLob_setFromBytes
desc: |
Replaces all of the data in the LOB with the contents of the provided
buffer. The LOB will first be cleared and then the provided data will be
written.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB to which data is to be written. If the reference is NULL
or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
The buffer from which the data is written. This value can be NULL
if the valueLength parameter is 0.
- name: valueLength
type: uint64_t
mode: IN
desc: |
The number of bytes which will be read from the buffer and written
to the LOB.
- name: dpiLob_trim
desc: |
Trims the data in the LOB so that it only contains the specified amount of
data.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB which will be trimmed. If the reference is NULL or invalid
an error is returned.
- name: newSize
type: uint64_t
mode: IN
desc: |
The new size of the data in the LOB. For character LOBs, this
value is in characters; for binary LOBs this value is in bytes.
- name: dpiLob_writeBytes
desc: |
Write data to the LOB at the specified offset using the provided buffer as
the source. If multiple calls to this function are planned, the LOB should
first be opened using the function [`dpiLob_openResource()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
**WARNING**: for historical reasons, Oracle stores CLOBs and NCLOBs using
the UTF-16 encoding, regardless of what encoding is otherwise in use by the
database. The number of characters, however, is defined by the number of
UCS-2 codepoints. For this reason, if a character requires more than one
UCS-2 codepoint, care must be taken to account for them in the offset
parameter.
round_trips: Yes
return: int
params:
- name: lob
type: dpiLob *
mode: IN
desc: |
The LOB to which data is to be written. If the reference is NULL
or invalid, an error is returned.
- name: offset
type: uint64_t
mode: IN
desc: |
The offset into the LOB data from which to start writing. The
first position is 1. For character LOBs this represents the number
of characters from the beginning of the LOB; for binary LOBS, this
represents the number of bytes from the beginning of the LOB.
- name: value
type: const char *
mode: IN
desc: |
The buffer from which the data is written.
- name: valueLength
type: uint64_t
mode: IN
desc: |
The number of bytes which will be read from the buffer and written
to the LOB.
- name: dpiMsgProps
kind: opaque struct
desc: |
Message properties handles are used to represent the properties of messages
that are enqueued and dequeued using advanced queuing. They are created by
calling the function [`dpiConn_newMsgProps()`] and are destroyed by
releasing the last reference by calling the function
[`dpiMsgProps_release()`].
functions:
- name: dpiMsgProps_addRef
desc: |
Adds a reference to the message properties. This is intended for situations
where a reference to the message properties needs to be maintained
independently of the reference returned when the handle was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
The message properties to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiMsgProps_getNumAttempts
desc: |
Returns the number of attempts that have been made to dequeue a message.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the number of
attempts is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: value
type: int32_t *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function.
- name: dpiMsgProps_getCorrelation
desc: |
Returns the correlation supplied by the producer when the message was
enqueued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the correlation
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no correlation, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there is
no correlation, the pointer will be populated with the value 0.
- name: dpiMsgProps_getDelay
desc: |
Returns the number of seconds the enqueued message will be delayed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the delay is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: int32_t *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function.
- name: dpiMsgProps_getDeliveryMode
desc: |
Returns the mode that was used to deliver the message.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the message
delivery mode is to be retrieved. If the reference is NULL or
invalid an error is returned.
- name: value
type: dpiMessageDeliveryMode *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. It will be one of the values from the
enumeration [`dpiMessageDeliveryMode`].
- name: dpiMsgProps_getEnqTime
desc: |
Returns the time that the message was enqueued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the enqueue time
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: dpiTimestamp *
mode: OUT
desc: |
A pointer to a [`dpiTimestamp`] structure, which
will be populated upon successful completion of this function.
- name: dpiMsgProps_getExceptionQ
desc: |
Returns the name of the queue to which the message is moved if it cannot be
processed successfully. See function [`dpiMsgProps_setExceptionQ()`]
for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the name of the
exception queue is to be retrieved. If the reference is NULL or
invalid an error is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no exception queue name, the pointer
will be populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there is
no exception queue name, the pointer will be populated with the
value 0.
- name: dpiMsgProps_getExpiration
desc: |
Returns the number of seconds the message is available to be dequeued.
See function [`dpiMsgProps_setExpiration()`] for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the expiration is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: int32_t *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function.
- name: dpiMsgProps_getMsgId
desc: |
Returns the id of the message in the queue that generated this message. No
value is available until the message has been enqueued or dequeued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the message id
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no message id, the pointer will be
populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there
is no message id, the pointer will be populated with the value 0.
- name: dpiMsgProps_getOriginalMsgId
desc: |
Returns the id of the message in the last queue that generated this
message. See function [`dpiMsgProps_setOriginalMsgId()`] for more
information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the original
message id is to be retrieved. If the reference is NULL or
invalid, an error is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. If there is no original message id, the pointer
will be populated with the value NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If there
is no original message id, the pointer will be populated with the
value 0.
- name: dpiMsgProps_getPayload
desc: |
Returns the payload associated with the message properties. The payload can
either be an object or an arbitrary series of bytes and is available after
a call to [`dpiQueue_deqOne()`] or [`dpiQueue_deqMany()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the payload is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: obj
type: dpiObject **
mode: OUT
desc: |
A reference to an object which will be populated upon successful
completion of this function. If the payload is not an object, this
value will be NULL. This parameter can also be NULL.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value, as a byte string, which will be populated
upon successful completion of this function. If the payload is not
a series of bytes, this value will be NULL. This parameter can
also be NULL.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value, in bytes, which will be
populated upon successful completion of this function. If the
payload is not a series of bytes, this value will be 0. This
parameter can also be NULL.
- name: dpiMsgProps_getPayloadJson
desc: |
Returns the payload associated with the message properties, The payload
must be a JSON object and is available after the call to
[`dpiQueue_deqOne()`] or [`dpiQueue_deqMany()`]; otherwise, the
value NULL will be returned.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the payload is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: json
type: dpiJson **
mode: OUT
desc: |
A reference to a JSON object which will be populated upon
successful completion of this function. If the payload is not a
JSON object, this value will be NULL.
- name: dpiMsgProps_getPriority
desc: |
Returns the priority assigned to the message. See function
[`dpiMsgProps_setPriority()`] for more information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the priority is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: int32_t *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function.
- name: dpiMsgProps_getState
desc: |
Returns the state of the message at the time of dequeue.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties from which the message state
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: dpiMessageState *
mode: OUT
desc: |
A pointer to the value, which will be populated upon successful
completion of this function. It will be one of the values from the
enumeration [`dpiMessageState`].
- name: dpiMsgProps_release
desc: |
Releases a reference to the message properties. A count of the references
to the message properties is maintained and when this count reaches zero,
the memory associated with the properties is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
The message properties from which a reference is to be released.
If the reference is NULL or invalid, an error is returned.
- name: dpiMsgProps_setCorrelation
desc: |
Sets the correlation of the message to be dequeued. Special pattern
matching characters such as the percent sign (%) and the underscore (_)
can be used. If multiple messages satisfy the pattern, the order of
dequeuing is undetermined.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the correlation is
to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
correlation is to be cleared.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiMsgProps_setDelay
desc: |
Sets the number of seconds to delay the message before it can be dequeued.
Messages enqueued with a delay are put into the DPI_MSG_STATE_WAITING
state. When the delay expires the message is put into the
DPI_MSG_STATE_READY state. Dequeuing directly by message id overrides this
delay specification. Note that delay processing requires the queue monitor
to be started.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the delay is to be
set. If the reference is NULL or invalid, an error is returned.
- name: value
type: int32_t
mode: IN
desc: |
The value to set.
- name: dpiMsgProps_setExceptionQ
desc: |
Sets the name of the queue to which the message is moved if it cannot be
processed successfully. Messages are moved if the number of unsuccessful
dequeue attempts has reached the maximum allowed number or if the message
has expired. All messages in the exception queue are in the
DPI_MSG_STATE_EXPIRED state.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the name of the
exception queue is to be set. If the reference is NULL or invalid,
an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data, or NULL if the
exception queue name is to be cleared. If not NULL, the value must
refer to a valid queue name.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiMsgProps_setExpiration
desc: |
Sets the number of seconds the message is available to be dequeued. This
value is an offset from the delay. Expiration processing requires the queue
monitor to be running. Until this time elapses, the messages are in the
queue in the state DPI_MSG_STATE_READY. After this time elapses messages
are moved to the exception queue in the DPI_MSG_STATE_EXPIRED state.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the expiration is
to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: int32_t
mode: IN
desc: |
The value to set.
- name: dpiMsgProps_setOriginalMsgId
desc: |
Sets the id of the message in the last queue that generated this
message.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the original
message identifier is to be set. If the reference is NULL or
invalid an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to the bytes making up the message identifier, or NULL
if no identifier is to be specified.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes, or 0 if the value
parameter is NULL.
- name: dpiMsgProps_setPayloadBytes
desc: |
Sets the payload for the message as a series of bytes. This value will be
used when the message is enqueued using [`dpiQueue_enqOne()`] or
[`dpiQueue_enqMany()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the payload is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to the bytes making up the payload.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the value parameter in bytes.
- name: dpiMsgProps_setPayloadJson
desc: |
Sets the payload for the message as a JSON object. This value will be used
when the message is enqueued using [`dpiQueue_enqOne()`] or
[`dpiQueue_enqMany()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the payload is to
be set. If the reference is NULL or invalid, an error is returned.
- name: json
type: dpiJson *
mode: IN
desc: |
A reference to the JSON object that will be used as the message
payload. If the reference is NULL or invalid, an error is returned.
- name: dpiMsgProps_setPayloadObject
desc: |
Sets the payload for the message as an object. This value will be used when
the message is enqueued using [`dpiQueue_enqOne()`] or
[`dpiQueue_enqMany()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the payload is to
be set. If the reference is NULL or invalid, an error is returned.
- name: obj
type: dpiObject *
mode: IN
desc: |
A reference to the object that will be used as the message
payload. If the reference is NULL or invalid, an error is
returned.
- name: dpiMsgProps_setPriority
desc: |
Sets the priority assigned to the message. A smaller number indicates a
higher priority. The priority can be any number, including negative
numbers.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the priority is to
be set. If the reference is NULL or invalid, an error is returned.
- name: value
type: int32_t
mode: IN
desc: |
The value to set.
- name: dpiMsgProps_setRecipients
desc: |
Sets recipients list for the message to be enqueued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message properties on which the recipients list
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: recipients
type: dpiMsgRecipient *
mode: IN
desc: |
A pointer to an array of [`dpiMsgRecipient`]
structures which indicate to which recipients the message should
be sent.
- name: numRecipients
type: uint32_t
mode: IN
desc: |
The number of recipients in the recipients list.
- name: dpiObject
kind: opaque struct
desc: |
Object handles are used to represent instances of the types created by the SQL
command CREATE OR REPLACE TYPE. They are created by calling the function
[`dpiObjectType_createObject()`] or calling the function
[`dpiObject_copy()`] or implicitly by creating a variable of the type
DPI_ORACLE_TYPE_OBJECT. The are destroyed when the last reference is released
by calling the function [`dpiObject_release()`].
functions:
- name: dpiObject_addRef
desc: |
Adds a reference to the object. This is intended for situations where a
reference to the object needs to be maintained independently of the
reference returned when the object was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiObject_appendElement
desc: |
Appends an element with the specified value to the collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object to which the value is to be appended. If the reference
is NULL or invalid, an error is returned. Likewise, if the object
does not refer to a collection an error is returned.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The native type of the data that is to be appended. It should be
one of the values from the enumeration
[`dpiNativeTypeNum`].
- name: value
type: dpiData *
mode: IN
desc: |
A pointer to a [`dpiData`] structure which contains
the value of the element to append to the collection.
- name: dpiObject_copy
desc: |
Creates an independent copy of an object and returns a reference to the
newly created object. This reference should be released as soon as it is
no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object which is to be copied. If the reference is NULL or
invalid an error is returned.
- name: copiedObj
type: dpiObject **
mode: OUT
desc: |
A pointer to a reference to the object which is created as a copy
of the first object, which is populated upon successful completion
of this function.
- name: dpiObject_deleteElementByIndex
desc: |
Deletes an element from the collection. Note that the position ordinals of
the remaining elements are not changed. The delete operation creates
*holes* in the collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the element is to be deleted. If the
reference is NULL or invalid, an error is returned. Likewise,
if the object does not refer to a collection, an error is
returned.
- name: index
type: int32_t
mode: IN
desc: |
The index of the element that is to be deleted. If no element
exists at that index an error is returned.
- name: dpiObject_getAttributeValue
desc: |
Returns the value of one of the object’s attributes.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the the attribute is to be retrieved. If the
reference is NULL or invalid, an error is returned.
- name: attr
type: dpiObjectAttr *
mode: IN
desc: |
The attribute which is to be retrieved. The attribute must belong
to the same type as the object; otherwise, an error is returned.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The native type of the data that is to be retrieved. It should be
one of the values from the enumeration
[`dpiNativeTypeNum`].
- name: value
type: dpiData *
mode: IN/OUT
desc: |
A pointer to a [`dpiData`] structure which will
be populated with the value of the element when this function
completes successfully. If the native type is
`DPI_NATIVE_TYPE_BYTES` and the Oracle type of the attribute is
`DPI_ORACLE_TYPE_NUMBER`, a buffer must be supplied in the
value.asBytes.ptr attribute and the maximum length of that buffer
must be supplied in the value.asBytes.length attribute before
calling this function. For all other conversions, the buffer is
supplied by the library and remains valid as long as a reference
to the object is held. Note that if the native type is
`DPI_NATIVE_TYPE_OBJECT` the reference that is returned must be
released by a call to [`dpiObject_release()`].
- name: dpiObject_getElementExistsByIndex
desc: |
Returns whether an element exists at the specified index.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object for which an element’s existence is to be tested. If
the reference is NULL or invalid, an error is returned. Likewise,
if the object does not refer to a collection, an error is
returned.
- name: index
type: int32_t
mode: IN
desc: |
The index into the collection that is to be checked.
- name: exists
type: int *
mode: OUT
desc: |
A pointer to a boolean value indicating if an element exists at
the specified index (1) or not (0), which will be populated when
this function completes successfully.
- name: dpiObject_getElementValueByIndex
desc: |
Returns the value of the element found at the specified index.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the element is to be retrieved. If the
reference is NULL or invalid, an error is returned. Likewise, if
the object does not refer to a collection, an error is returned.
- name: index
type: int32_t
mode: IN
desc: |
The index into the collection from which the element is to be
retrieved. If no element exists at that index, an error is
returned.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The native type of the data that is to be retrieved. It should be
one of the values from the enumeration
[`dpiNativeTypeNum`].
- name: value
type: dpiData *
mode: IN/OUT
desc: |
A pointer to a [`dpiData`] structure which will be
populated with the value of the element when this function
completes successfully. If the native type is
`DPI_NATIVE_TYPE_BYTES` and the Oracle type of the attribute is
`DPI_ORACLE_TYPE_NUMBER`, a buffer must be supplied in the
value.asBytes.ptr attribute and the maximum length of that buffer
must be supplied in the value.asBytes.length attribute before
calling this function. For all other conversions, the buffer is
supplied by the library and remains valid as long as a reference
to the object is held. Note that if the native type is
`DPI_NATIVE_TYPE_OBJECT` the reference that is returned must be
released by a call to [`dpiObject_release()`].
- name: dpiObject_getFirstIndex
desc: |
Returns the first index used in a collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the first index is to be retrieved. If the
reference is NULL or invalid, an error is returned. Likewise, if
the object does not refer to a collection, an error is returned.
- name: index
type: int32_t *
mode: OUT
desc: |
A pointer to the first index used in the collection, which will be
populated when the function completes successfully.
- name: exists
type: int *
mode: OUT
desc: |
A pointer to a boolean value specifying whether a first index
exists (1) or not (0), which will be populated when the function
completes successfully.
- name: dpiObject_getLastIndex
desc: |
Returns the last index used in a collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the last index is to be retrieved. If the
reference is NULL or invalid, an error is returned. Likewise, if
the object does not refer to a collection, an error is returned.
- name: index
type: int32_t *
mode: OUT
desc: |
A pointer to the last index used in the collection, which will be
populated when the function completes successfully.
- name: exists
type: int *
mode: OUT
desc: |
A pointer to a boolean value specifying whether a last index
exists (1) or not (0), which will be populated when the function
completes successfully.
- name: dpiObject_getNextIndex
desc: |
Returns the next index used in a collection following the specified index.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the next index is to be retrieved. If the
reference is NULL or invalid, an error is returned. Likewise, if
the object does not refer to a collection, an error is returned.
- name: index
type: int32_t
mode: IN
desc: |
The index after which the next index is to be determined. This
does not have to be an actual index in the collection.
- name: nextIndex
type: int32_t *
mode: OUT
desc: |
A pointer to the next index used in the collection, which will be
populated when the function completes successfully and the value
of the exists parameter is 1.
- name: exists
type: int *
mode: OUT
desc: |
A pointer to a boolean value specifying whether a next index
exists following the specified index (1) or not (0), which will be
populated when the function completes successfully.
- name: dpiObject_getPrevIndex
desc: |
Returns the previous index used in a collection preceding the specified
index.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the previous index is to be retrieved. If the
reference is NULL or invalid, an error is returned. Likewise, if
the object does not refer to a collection, an error is returned.
- name: index
type: int32_t
mode: IN
desc: |
The index before which the previous index is to be determined.
This does not have to be an actual index in the collection.
- name: prevIndex
type: int32_t *
mode: OUT
desc: |
A pointer to the previous index used in the collection, which will
be populated when the function completes successfully and the value
of the exists parameter is 1.
- name: exists
type: int *
mode: OUT
desc: |
A pointer to a boolean value specifying whether a previous index
exists preceding the specified index (1) or not (0), which will be
populated when the function completes successfully.
- name: dpiObject_getSize
desc: |
Returns the number of elements in a collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which the number of elements is to be retrieved.
If the reference is NULL or invalid, an error is returned.
Likewise, if the object does not refer to a collection, an error
is returned.
- name: size
type: int32_t *
mode: OUT
desc: |
A pointer to the number of elements in the collection, which will
be populated when the function completes successfully.
- name: dpiObject_release
desc: |
Releases a reference to the object. A count of the references to the object
is maintained and when this count reaches zero, the memory associated with
the object is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiObject_setAttributeValue
desc: |
Sets the value of one of the object’s attributes.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object on which the attribute is to be set. If the reference
is NULL or invalid, an error is returned.
- name: attr
type: dpiObjectAttr *
mode: IN
desc: |
The attribute which is to be set. The attribute must belong to the
same type as the object; otherwise, an error is returned.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The native type of the data that is to be set. It should be one of
the values from the enumeration
[`dpiNativeTypeNum`].
- name: value
type: dpiData *
mode: IN
desc: |
A pointer to a [`dpiData`] structure which contains
the value to which the attribute is to be set.
- name: dpiObject_setElementValueByIndex
desc: |
Sets the value of the element found at the specified index.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object in which the element is to be set. If the reference is
NULL or invalid, an error is returned. Likewise, if the object
does not refer to a collection, an error is returned.
- name: index
type: int32_t
mode: IN
desc: |
The index into the collection at which the element is to be set.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The native type of the data that is to be set. It should be one of
the values from the enumeration
[`dpiNativeTypeNum`].
- name: value
type: dpiData *
mode: IN
desc: |
A pointer to a [`dpiData`] structure which contains the
value of the element to place at the specified index.
- name: dpiObject_trim
desc: |
Trims a number of elements from the end of a collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: obj
type: dpiObject *
mode: IN
desc: |
The object from which a number of elements are to be trimmed. If
the reference is NULL or invalid, an error is returned. Likewise,
if the object does not refer to a collection, an error is
returned.
- name: numToTrim
type: uint32_t
mode: IN
desc: |
The number of elements to trim from the end of the collection. If
the number of of elements to trim exceeds the current size of the
collection an error is returned.
- name: dpiObjectAttr
kind: opaque struct
desc: |
Object attribute handles are used to represent the attributes of types such as
those created by the SQL command CREATE OR REPLACE TYPE. They are created by
calling the function [`dpiObjectType_getAttributes()`] and are destroyed
when the last reference is released by calling the function
[`dpiObjectAttr_release()`].
functions:
- name: dpiObjectAttr_addRef
desc: |
Adds a reference to the attribute. This is intended for situations where a
reference to the attribute needs to be maintained independently of the
reference returned when the attribute was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: attr
type: dpiObjectAttr *
mode: IN
desc: |
The attribute to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiObjectAttr_getInfo
desc: |
Returns information about the attribute.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: attr
type: dpiObjectAttr *
mode: IN
desc: |
A reference to the attribute whose information is to be retrieved.
If the reference is NULL or invalid, an error is returned.
- name: info
type: dpiObjectAttrInfo *
mode: OUT
desc: |
A pointer to a [`dpiObjectAttrInfo`]
structure which will be populated with information about the
attribute.
- name: dpiObjectAttr_release
desc: |
Releases a reference to the attribute. A count of the references to the
attribute is maintained and when this count reaches zero, the memory
associated with the attribute is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: attr
type: dpiObjectAttr *
mode: IN
desc: |
The attribute from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiObjectType
kind: opaque struct
desc: |
Object type handles are used to represent types such as those created by the
SQL command CREATE OR REPLACE TYPE. They are created using the function
[`dpiConn_getObjectType()`] or implicitly when fetching from a column
containing objects by calling the function [`dpiStmt_getQueryInfo()`].
Object types are also retrieved when used as attributes in
another object by calling the function [`dpiObjectAttr_getInfo()`] or as
the element type of a collection by calling the function
[`dpiObjectType_getInfo()`]. They are destroyed when the last reference is
released by calling the function [`dpiObjectType_release()`].
functions:
- name: dpiObjectType_addRef
desc: |
Adds a reference to the object type. This is intended for situations where
a reference to the object type needs to be maintained independently of the
reference returned when the object type was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: objType
type: dpiObjectType *
mode: IN
desc: |
The object type to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiObjectType_createObject
desc: |
Creates an object of the specified type and returns a reference to it.
This reference should be released as soon as it is no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: objType
type: dpiObjectType *
mode: IN
desc: |
A reference to the object type whose information is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: obj
type: dpiObject **
mode: OUT
desc: |
A pointer to a reference to the created object, which will be
populated when the function completes successfully.
- name: dpiObjectType_getAttributes
desc: |
Returns the list of attributes that belong to the object type.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: objType
type: dpiObjectType *
mode: IN
desc: |
A reference to the object type whose attributes are to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: numAttributes
type: uint16_t
mode: OUT
desc: |
The number of attributes which will be returned. This value can be
determined using the function [`dpiObjectType_getInfo()`].
- name: attributes
type: dpiObjectAttr **
mode: OUT
desc: |
An array of references to the object’s attributes, which will be
populated with attribute references upon successful completion of
this function. It is assumed that the array is large enough to hold
numAttributes attribute references. These references must be
released when they are no longer required by calling the function
[`dpiObjectAttr_release()`].
- name: dpiObjectType_getInfo
desc: |
Returns information about the object type.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: objType
type: dpiObjectType *
mode: IN
desc: |
A reference to the object type whose information is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiObjectTypeInfo *
mode: OUT
desc: |
A pointer to a [`dpiObjectTypeInfo`]
structure which will be populated with information about the
object type when the function completes successfully.
- name: dpiObjectType_release
desc: |
Releases a reference to the object type. A count of the references to the
object type is maintained and when this count reaches zero, the memory
associated with the object type is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: objType
type: dpiObjectType *
mode: IN
desc: |
The object type from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiPool
kind: opaque struct
desc: |
Pool handles are used to represent session pools. They are created using the
function [`dpiPool_create()`] and can be closed by calling the function
[`dpiPool_close()`] or releasing the last reference to the pool by
calling the function [`dpiPool_release()`]. Pools can be used to create
connections by calling the function [`dpiPool_acquireConnection()`].
functions:
- name: dpiPool_acquireConnection
desc: |
Acquires a connection from the pool and returns a reference to it. This
reference should be released by calling [`dpiConn_release()`] as soon
as it is no longer needed, which will also return the connection back to
the pool for subsequent calls to this function. The connection can be
returned back to the pool earlier by calling [`dpiConn_close()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
The pool from which a connection is to be acquired. If the
reference is NULL or invalid, an error is returned.
- name: userName
type: const char *
mode: IN
desc: |
The name of the user used for authenticating the user, as a byte
string in the encoding used for CHAR data. NULL is also acceptable
if external authentication is being requested or credentials were
supplied when the pool was created.
- name: userNameLength
type: uint32_t
mode: IN
desc: |
The length of the userName parameter, in bytes, or 0 if the
userName parameter is NULL.
- name: password
type: const char *
mode: IN
desc: |
The password to use for authenticating the user, as a byte string
in the encoding used for CHAR data. NULL is also acceptable if
external authentication is being requested or if credentials were
supplied when the pool was created.
- name: passwordLength
type: uint32_t
mode: IN
desc: |
The length of the password parameter, in bytes, or 0 if the
password parameter is NULL.
- name: params
type: dpiConnCreateParams *
mode: IN
desc: |
A pointer to a [`dpiConnCreateParams`]
structure which is used to specify parameters for connection
creation. NULL is also acceptable in which case all default
parameters will be used when creating the connection.
- name: conn
type: dpiConn **
mode: OUT
desc: |
A reference to the connection that is acquired from the pool.
This value is populated upon successful completion of this
function.
- name: dpiPool_addRef
desc: |
Adds a reference to the pool. This is intended for situations where a
reference to the pool needs to be maintained independently of the reference
returned when the pool was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
The pool to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiPool_close
desc: |
Closes the pool and makes it unusable for further activity.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool which is to be closed. If the reference is
NULL or invalid, an error is returned.
- name: closeMode
type: dpiPoolCloseMode
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiPoolCloseMode`], OR’ed together.
- name: dpiPool_create
desc: |
Creates a session pool which creates and maintains a group of stateless
sessions to the database. The main benefit of session pooling is
performance since making a connection to the database is a time-consuming
activity, especially when the database is remote.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
If a failure occurs, the errorInfo structure is filled in with error
information.
round_trips: Maybe
return: int
params:
- name: context
type: const dpiContext *
mode: IN
desc: |
The context handle created earlier using the function
[`dpiContext_createWithParams()`]. If the handle is NULL or
invalid, an error is returned.
- name: userName
type: const char *
mode: IN
desc: |
The name of the user used for authenticating sessions, as a byte
string in the encoding used for CHAR data. NULL is also acceptable
if external authentication is being requested or if a heterogeneous
pool is being created.
- name: userNameLength
type: uint32_t
mode: IN
desc: |
The length of the userName parameter, in bytes, or 0 if the
userName parameter is NULL.
- name: password
type: const char *
mode: IN
desc: |
The password to use for authenticating sessions, as a byte string
in the encoding used for CHAR data. NULL is also acceptable if
external authentication is being requested or if a heterogeneous
pool is being created.
- name: passwordLength
type: uint32_t
mode: IN
desc: |
The length of the password parameter, in bytes, or 0 if the
password parameter is NULL.
- name: connectString
type: const char *
mode: IN
desc: |
The connect string identifying the database to which connections
are to be established by the session pool, as a byte string in
the encoding used for CHAR data. NULL is also acceptable for
local connections (identified by the environment variable
ORACLE_SID).
- name: connectStringLength
type: uint32_t
mode: IN
desc: |
The length of the connectString parameter, in bytes, or 0 if the
connectString parameter is NULL.
- name: commonParams
type: dpiCommonCreateParams *
mode: IN
desc: |
A pointer to a [`dpiCommonCreateParams`]
structure which is used to specify context parameters for pool
creation. NULL is also acceptable in which case all default
parameters will be used when creating the pool.
- name: createParams
type: dpiPoolCreateParams *
mode: IN
desc: |
A pointer to a [`dpiPoolCreateParams`]
structure which is used to specify parameters for pool creation.
NULL is also acceptable in which case all default parameters will
be used for pool creation.
- name: pool
type: dpiPool **
mode: OUT
desc: |
A pointer to a reference to the pool that is created. Call
[`dpiPool_release()`] when the reference is no longer needed.
- name: dpiPool_getBusyCount
desc: |
Returns the number of sessions in the pool that are busy.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the number of busy sessions is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getEncodingInfo
desc: |
Returns the encoding information used by the pool. This will be equivalent
to the values passed when the pool was created, or the values retrieved
from the environment variables NLS_LANG and NLS_NCHAR.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool whose encoding information is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiEncodingInfo *
mode: OUT
desc: |
A pointer to a [`dpiEncodingInfo`] structure
which will be populated with the encoding information used by the
pool.
- name: dpiPool_getGetMode
desc: |
Returns the mode used for acquiring or getting connections from the pool.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the mode used for acquiring
connections is to be retrieved. If the reference is NULL or
invalid an error is returned.
- name: value
type: dpiPoolGetMode *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getMaxLifetimeSession
desc: |
Returns the maximum lifetime a pooled session may exist, in seconds.
Sessions in use will not be closed. They become candidates for termination
only when they are released back to the pool and have existed for longer
then the returned value. Note that termination only occurs when the pool is
accessed. The value 0 means that there is no maximum length of time that a
pooled session may exist.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the maximum lifetime of
sessions is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getMaxSessionsPerShard
desc: |
Returns the maximum sessions per shard. This parameter is used for
balancing shards.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the maximum sessoins per shard
is to be retrieved. If the refernece is NULL or invalid, an error
is returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getOpenCount
desc: |
Returns the number of sessions in the pool that are open.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the number of open sessions is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getPingInterval
desc: |
Returns the ping interval duration (in seconds), which is used to check the
healthiness of idle connections before getting checked out. A negative
value indicates this check is disabled.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the ping interval is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: int *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getSodaMetadataCache
desc: |
Returns whether or not the SODA metadata cache is enabled or not.
The SODA metadata cache requires Oracle Client 21.3, or later. It is also
available in Oracle Client 19 from 19.11.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the status of the SODA metadata
cache is to be retrieved. If the reference is NULL or invalid, an
error is returned.
- name: enabled
type: int *
mode: OUT
desc: |
A pointer to an integer defining whether the SODA metadata cache
is enabled (1) or not (0), which will be populated upon successful
completion of this function.
- name: dpiPool_getStmtCacheSize
desc: |
Returns the default size of the statement cache for sessions in the pool,
in number of statements.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the default size of the
statement cache is to be retrieved. If the reference is NULL
or invalid, an error is returned.
- name: cacheSize
type: uint32_t *
mode: OUT
desc: |
A pointer to the default size of the statement cache, which will
be populated upon successful completion of this function.
- name: dpiPool_getTimeout
desc: |
Returns the length of time (in seconds) after which idle sessions in the
pool are terminated. Note that termination only occurs when the pool is
accessed. A value of 0 means that no ide sessions are terminated.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the timeout for idle sessions
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_getWaitTimeout
desc: |
Returns the amount of time (in milliseconds) that the caller will wait for
a session to become available in the pool before returning an error.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool from which the wait timeout is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiPool_reconfigure
desc: |
Changes pool configuration corresponding to members
[`dpiPoolCreateParams.minSessions`],
[`dpiPoolCreateParams.maxSessions`] and
[`dpiPoolCreateParams.sessionIncrement`] to the specified values.
Connections will be created as needed if the value of *minSessions* is
increased. Connections will be dropped from the pool as they are released
back to the pool if *minSessions* is decreased.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool which needs to be reconfigured. If the
reference is NULL or invalid, an error is returned.
- name: minSessions
type: uint32_t
mode: IN
desc: |
New value for the minimum number of sessions that should be
maintained.
- name: maxSessions
type: uint32_t
mode: IN
desc: |
New value for the maximum number of sessions that may be retained
in the pool.
- name: sessionIncrement
type: uint32
mode: IN
desc: |
New value for the number of sessions that will be created each
time the pool needs to be expanded.
- name: dpiPool_release
desc: |
Releases a reference to the pool. A count of the references to the pool is
maintained and when this count reaches zero, the memory associated with the
pool is freed and the session pool is closed if that has not already
taken place using the function [`dpiPool_close()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
The pool from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiPool_setAccessToken
desc: |
The function is used to manually set the token and private key for a
session pool. After pool creation it can be used to periodically reset
the token and private key to avoid the need for the pool token callback
function
[`dpiPoolCreateParams.accessTokenCallback`] to
be called during pool growth.
This function may also be useful for testing. By setting an expired token
and key the subsequent pool callback function behavior can be seen without
waiting for normal token expiry.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool where authentication parameters will be
set. If the pool parameter is NULL or invalid, an error is
returned.
- name: accessToken
type: dpiAccessToken *
mode: IN
desc: |
A pointer to a [`dpiAccessToken`] structure
which is used to specify parameters for token based authentication.
If the pointer is NULL, an error is returned.
- name: dpiPool_setGetMode
desc: |
Sets the mode used for acquiring or getting connections from the pool.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the mode used for acquiring
connections is to be set. If the reference is NULL or invalid, an
error is returned.
- name: value
type: dpiPoolGetMode
mode: IN
desc: |
The value to set.
- name: dpiPool_setMaxLifetimeSession
desc: |
Sets the maximum lifetime a pooled session may exist, in seconds. Sessions
in use will not be closed. They become candidates for termination only when
they are released back to the pool and have existed for longer then the
specified value. Note that termination only occurs when the pool is
accessed. The value 0 means that there is no maximum length of time that a
pooled session may exist.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the maximum lifetime of sessions
is to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t
mode: IN
desc: |
The value to set.
- name: dpiPool_setMaxSessionsPerShard
desc: |
Sets the maximum number of sessions per shard.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the maximum sessions per shard is
to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t
mode: IN
desc: |
The value to set.
- name: dpiPool_setPingInterval
desc: |
Sets the ping interval duration (in seconds) which is used to to check for
healthiness of sessions. If this time has passed since the last time the
session was checked out a ping will be performed. A negative value will
disable this check.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the ping interval is to be set.
If the reference is NULL or invalid, an error is returned.
- name: value
type: int
mode: IN
desc: |
The value to set.
- name: dpiPool_setSodaMetadataCache
desc: |
Sets whether the SODA metadata cache is enabled or not. Enabling the SODA
metadata cache can significantly improve the performance of repeated calls
to methods [`dpiSodaDb_createCollection()`] (when not specifying a
value for the metadata parameter) and [`dpiSodaDb_openCollection()`].
Note that the cache can become out of date if changes to the metadata of
cached collections are made externally.
The SODA metadata cache requires Oracle Client 21.3, or later. It is also
available in Oracle Client 19 from 19.11.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the SODA metadata cache is to be
enabled or disabled. If the reference is NULL or invalid, an error
is returned.
- name: enabled
type: int
mode: IN
desc: |
Identifies if the cache should be enabled (1) or not (0).
- name: dpiPool_setStmtCacheSize
desc: |
Sets the default size of the statement cache for sessions in the pool.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the default size of the statement
cache is to be set. If the reference is NULL or invalid, an error
is returned.
- name: cacheSize
type: uint32_t
mode: IN
desc: |
The new size of the statement cache, in number of statements.
- name: dpiPool_setTimeout
desc: |
Sets the amount of time (in seconds) after which idle sessions in the
pool are terminated. Note that termination only occurs when the pool is
accessed. A value of zero will result in no idle sessions being terminated.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the timeout for idle sessions is
to be set. If the reference is NULL or invalid, an error is
returned.
- name: value
type: uint32_t
mode: IN
desc: |
The value to set.
- name: dpiPool_setWaitTimeout
desc: |
Sets the amount of time (in milliseconds) that the caller should wait for a
session to be available in the pool before returning with an error.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: pool
type: dpiPool *
mode: IN
desc: |
A reference to the pool in which the wait timeout is to be set. If
the reference is NULL or invalid, an error is returned.
- name: value
type: uint32_t
mode: IN
desc: |
The value to set.
- name: dpiQueue
kind: opaque struct
desc: |
Queue handles are used to represent Advanced Queueing (AQ) queues. They are
created by calling the function [`dpiConn_newQueue()`] and are destroyed
when the last reference is released by calling the function
[`dpiQueue_release()`].
functions:
- name: dpiQueue_addRef
desc: |
Adds a reference to the queue. This is intended for situations where a
reference to the queue needs to be maintained independently of the
reference returned when the queue was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue to which a reference is to be added. If the reference is
NULL or invalid, an error is returned.
- name: dpiQueue_deqMany
desc: |
Dequeues multiple messages from the queue.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue from which messages are to be dequeued. If the reference
is NULL or invalid, an error is returned.
- name: numProps
type: uint32_t *
mode: IN/OUT
desc: |
A pointer to the number of elements in the props array. When the
function is called, the value refers to the length of the props
array and the maximum number of messages that should be dequeued.
After the function has completed successfully, the value refers
to the number of messages that were actually dequeued from the
queue.
- name: props
type: dpiMsgProps **
mode: OUT
desc: |
An array of references to message properties which will be
populated upon successful completion of this function. Each of
these references should be released when they are no longer
needed by calling the function [`dpiMsgProps_release()`].
- name: dpiQueue_deqOne
desc: |
Dequeues a single message from the queue.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue from which the messages is to be dequeued. If the
reference is NULL or invalid, an error is returned.
- name: props
type: dpiMsgProps **
mode: OUT
desc: |
A pointer to a reference to a message property which will be
populated upon successful completion of this function. This
reference should be released when it is no longer needed by calling
the function [`dpiMsgProps_release()`]. If no messages are
available, this reference will be NULL.
- name: dpiQueue_enqMany
desc: |
Enqueues multiple messages into the queue.
Warning: calling this function in parallel on different connections
acquired from the same pool may fail due to Oracle bug 29928074. Ensure
that this function is not run in parallel, use standalone connections or
connections from different pools, or make multiple calls to
[`dpiQueue_enqOne()`] instead. The function [`dpiQueue_deqMany()`]
call is not affected.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue into which the messages are to be enqueued. If the
reference is NULL or invalid, an error is returned.
- name: numProps
type: uint32_t
mode: IN/OUT
desc: |
The number of messages that are to be enqueued.
- name: props
type: dpiMsgProps **
mode: IN
desc: |
An array of references to message properties that are to be
enqueued. The length of the array is specified by the numProps
parameter. Each of the message properties must have the right
type of payload associated before calling this method or an error
will occur.
- name: dpiQueue_enqOne
desc: |
Enqueues a single mesasge into the queue.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue into which the message is to be enqueued. If the
reference is NULL or invalid, an error is returned.
- name: props
type: dpiMsgProps *
mode: IN
desc: |
A reference to the message that is to be enqueued. The message
properties must have the right type of payload associated before
calling this method or an error will occur.
- name: dpiQueue_getDeqOptions
desc: |
Returns a reference to the dequeue options associated with the queue. These
options affect how messages are dequeued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue from which the dequeue options are to be retrieved. If
the reference is NULL or invalid, an error is returned.
- name: options
type: dpiDeqOptions **
mode: OUT
desc: |
A reference to the dequeue options associated with the queue which
will be populated upon successful completion of this function.
This reference is owned by the queue and will remain valid as
long as a reference to the queue is held.
- name: dpiQueue_getEnqOptions
desc: |
Returns a reference to the enqueue options associated with the queue. These
options affect how messages are enqueued.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue from which the enqueue options are to be retrieved. If
the reference is NULL or invalid, an error is returned.
- name: options
type: dpiEnqOptions **
mode: OUT
desc: |
A reference to the enqueue options associated with the queue which
will be populated upon successful completion of this function. This
reference is owned by the queue and will remain valid as long as a
reference to the queue is held.
- name: dpiQueue_release
desc: |
Releases a reference to the queue. A count of the references to the queue
is maintained and when this count reaches zero, the memory associated with
the queue is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: queue
type: dpiQueue *
mode: IN
desc: |
The queue from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiRowid
kind: opaque struct
desc: |
Rowid handles are used to represent the unique identifier of a row in the
database. They cannot be created or set directly but are created implicitly
when a variable of type DPI_ORACLE_TYPE_ROWID is created. They are destroyed
when the last reference is released by a call to the function
[`dpiRowid_release()`].
functions:
- name: dpiRowid_addRef
desc: |
Adds a reference to the rowid. This is intended for situations where a
reference to the rowid needs to be maintained independently of the
reference returned when the rowid was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: rowid
type: dpiRowid *
mode: IN
desc: |
The rowid to which a reference is to be added. If the reference is
NULL or invalid, an error is returned.
- name: dpiRowid_getStringValue
desc: |
Returns the sting (base64) representation of the rowid.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: rowid
type: dpiRowid *
mode: IN
desc: |
The rowid from which the string representation is to be returned.
If the reference is NULL or invalid, an error is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the value as a byte string in the encoding used for
CHAR data, which will be populated upon successful completion of
this function. The string returned will remain valid as long as a
reference is held to the rowid.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the value parameter, in bytes, which
will be populated upon successful completion of this function.
- name: dpiRowid_release
desc: |
Releases a reference to the rowid. A count of the references to the rowid
is maintained and when this count reaches zero, the memory associated with
the rowid is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: rowid
type: dpiRowid *
mode: IN
desc: |
The rowid from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiSodaColl
kind: opaque struct
desc: |
SODA collection handles are used to represent SODA collections in the database.
They are created by calling one of the functions
[`dpiSodaDb_createCollection()`], [`dpiSodaDb_openCollection()`] or
[`dpiSodaCollCursor_getNext()`] and are destroyed when the last reference
is released by calling the function [`dpiSodaColl_release()`].
See [this tracking issue](https://github.com/oracle/odpi/issues/110) for
known issues with SODA.
functions:
- name: dpiSodaColl_addRef
desc: |
Adds a reference to the SODA collection. This is intended for situations
where a reference to the collection needs to be maintained independently of
the reference returned when the collection was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection to which a reference is to be added.
If the reference is NULL or invalid, an error is returned.
- name: dpiSodaColl_createIndex
desc: |
Create an index on the collection, which can improve the performance of
SODA query-by-examples (QBE). An index is defined by a specification,
which is a JSON-encoded string that specifies how particular QBE patterns
are to be indexed for quicker matching. See
[Overview of SODA indexing](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4848E6A0-58A7-44FD-8D6D-A033D0CCF9CB).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection on which the index is to be created.
If the reference is NULL or invalid, an error is returned.
- name: indexSpec
type: const char *
mode: IN
desc: |
The JSON specification of the index as a byte string in the
encoding used for CHAR data.
- name: indexSpecLength
type: uint32_t
mode: IN
desc: |
The length of the specification of the index, in bytes.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: dpiSodaColl_drop
desc: |
Drops a SODA collection from the database.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection which is to be dropped. If the
reference is NULL or invalid, an error is returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: isDropped
type: int *
mode: OUT
desc: |
A pointer to a boolean which indicates whether the collection was
dropped (1) or not (0). If this information is not needed, NULL
can also be passed.
- name: dpiSodaColl_dropIndex
desc: |
Drop an index on the collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection on which the index is to be dropped.
If the reference is NULL or invalid, an error is returned.
- name: name
type: const char *
mode: IN
desc: |
The name of the index that is to be dropped as a byte string in
the encoding used for CHAR data.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the index name, in bytes.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: isDropped
type: int *
mode: OUT
desc: |
A pointer to a boolean which indicates whether the specified index
was dropped (1) or not (0). If this information is not needed,
NULL can also be passed.
- name: dpiSodaColl_find
desc: |
Finds all of the documents in the collection that match the specified
options.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection which is to be searched. If the
reference is NULL or invalid, an error is returned.
- name: options
type: const dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a structure of type
[`dpiSodaOperOptions`] which specifies
options for restricting the number of documents returned. This
value can also be NULL which will result in all documents in the
collection being returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: cursor
type: dpiSodaDocCursor **
mode: OUT
desc: |
A pointer to a reference to the cursor that is populated if the
function completes successfully. The reference that is returned
should be released using [`dpiSodaDocCursor_release()`] when
it is no longer needed.
- name: dpiSodaColl_findOne
desc: |
Finds a single document in the collection that matches the specified
options.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection which is to be searched. If the
reference is NULL or invalid, an error is returned.
- name: options
type: const dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a structure of type
[`dpiSodaOperOptions`] which specifies
options for restricting the document that is returned. This
value can also be NULL which will result in the first document in
the collection being returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: doc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a reference to the document that is populated if
the function completes successfully. The reference that is
returned should be released using [`dpiSodaDoc_release()`]
when it is no longer needed. If no document matches the specified
options, the value NULL is returned instead.
- name: dpiSodaColl_getDataGuide
desc: |
Returns a document containing the data guide for the collection. See
[JSON Data Guide](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-219FC30E-89A7-4189-BC36-7B961A24067C).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection from which the data guide is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: doc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a reference to the document that is populated if the
function completes successfully. The document reference that is
returned should be released using [`dpiSodaDoc_release()`]
when it is no longer needed. If no data guide is available
because the collection contains no documents, then a NULL
reference is returned.
- name: dpiSodaColl_getDocCount
desc: |
Returns the number of documents in the collection that match the specified
options.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection which is to be searched. If the
reference is NULL or invalid, an error is returned.
- name: options
type: const dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a structure of type
[`dpiSodaOperOptions`] which specifies
options for restricting the number of documents found. This value
can also be NULL which will result in all of the documents in the
collection being counted.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: count
type: uint64_t *
mode: OUT
desc: |
A pointer to a count of the number of documents found that is
populated if the function completes successfully.
- name: dpiSodaColl_getMetadata
desc: |
Returns the metadata for the collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection from which the metadata is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: IN
desc: |
A pointer to the collection metadata, as a byte string in the
encoding used for CHAR data, which will be populated upon
successful completion of this function. The string returned will
remain valid as long as a reference to the collection is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the collection metadata, in bytes,
which will be populated upon successful completion of this
function.
- name: dpiSodaColl_getName
desc: |
Returns the name of the collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection from which the name is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: IN
desc: |
A pointer to the collection name, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The string returned will remain valid
as long as a reference to the collection is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the collection name, in bytes, which
will be populated upon successful completion of this function.
- name: dpiSodaColl_insertMany
desc: |
Inserts multiple documents into the collection and optionally returns
result documents containing information about the newly inserted documents.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
On failure the offset attribute in the [`dpiErrorInfo`]
structure will contain the index into the SODA document handles array where
the error took place.
NOTE: this function requires Oracle Client 18.5 or higher in addition to
the usual SODA requirements and is currently available only as a preview.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection into which the documents are to be
inserted. If the reference is NULL or invalid, an error is
returned.
- name: numDocs
type: uint32_t
mode: IN
desc: |
The length of the arrays passed for the docs and insertedDocs
parameters.
- name: docs
type: dpiSodaDoc **
mode: IN
desc: |
An array of SODA document handles which will be inserted into the
collection. The length of the array is determined by the numDocs
parameter.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: insertedDocs
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to an array of document references that will be
populated upon successful completion of this function. The length
of the array is determined by the numDocs parameter. Call the
function [`dpiSodaDoc_release()`] for each of the elements of
this array when the references contained in the array are no longer
needed. This parameter can also be NULL if this information is not
required.
- name: dpiSodaColl_insertManyWithOptions
desc: |
Inserts multiple documents into the collection and optionally returns
result documents containing information about the newly inserted documents.
In addition, options can be supplied to modify how the documents are
inserted or returned.
This function requires Oracle Client 21.3 or higher to be used in addition
to the normal SODA requirements (also available in Oracle Client 19 from
19.11).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
On failure the offset attribute in the [`dpiErrorInfo`]
structure will contain the index into the SODA document handles array where
the error took place.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection into which the documents are to
be inserted. If the reference is NULL or invalid, an error is
returned.
- name: numDocs
type: uint32_t
mode: IN
desc: |
The length of the arrays passed for the docs and insertedDocs
parameters.
- name: docs
type: dpiSodaDoc **
mode: IN
desc: |
An array of SODA document handles which will be inserted into
the collection. The length of the array is determined by the
numDocs parameter.
- name: options
type: dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a [`dpiSodaOperOptions`]
structure containing any desired options, or NULL. If the value
is NULL, this function behaves identically to
[`dpiSodaColl_insertMany()`]. Options can only be specified
with Oracle Client 21.3 or higher (also available in Oracle Client
19 from 19.11).
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: insertedDocs
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to an array of document references that will be
populated upon successful completion of this function. The length
of the array is determined by the numDocs parameter. Call the
function [`dpiSodaDoc_release()`] for each of the elements of
this array when the references contained in the array are no
longer needed. This parameter can also be NULL if this information
is not required.
- name: dpiSodaColl_insertOne
desc: |
Inserts a document into the collection and optionally returns it.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection into which the document is to be
inserted. If the reference is NULL or invalid, an error is
returned.
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which is to be inserted into the
collection. If the reference is NULL or invalid, an error is
returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: insertedDoc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference that will be populated upon
successful completion of this function. Call the function
[`dpiSodaDoc_release()`] when it is no longer needed. This
parameter can also be NULL if this information is not required.
- name: dpiSodaColl_insertOneWithOptions
desc: |
Inserts a document into the collection and optionally returns it. In
addition, options can be supplied to modify how the document is inserted or
returned.
This method requires Oracle Client 21.3 or higher to be used in addition to
the normal SODA requirements (also available in Oracle Client 19 from
19.11).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection into which the document is to be
inserted. If the reference is NULL or invalid, an error is
returned.
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which is to be inserted into the
collection. If the reference is NULL or invalid, an error is
returned.
- name: options
type: dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a [`dpiSodaOperOptions`]
structure containing any desired options, or NULL. If the value is
NULL, this function behaves identically to
[`dpiSodaColl_insertOne()`]. Options can only be specified
with Oracle Client 21.3 or higher (also available in Oracle Client
19 from 19.11).
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: insertedDoc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference that will be populated upon
successful completion of this function. Call the function
[`dpiSodaDoc_release()`] when it is no longer needed. This
parameter can also be NULL if this information is not required.
- name: dpiSodaColl_listIndexes
desc: |
Returns a list of indexes associated with the collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection from which the list of indexes is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: list
type: dpiStringList *
mode: OUT
desc: |
A pointer to a structure of type
[`dpiStringList`] which is populated if the
function completes successfully. The memory associated with this
list should be freed by calling [`dpiContext_freeStringList()`]
when it is no longer needed.
- name: dpiSodaColl_release
desc: |
Releases a reference to the SODA collection. A count of the references to
the collection is maintained and when this count reaches zero, the memory
associated with the collection is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection from which a reference is to be
released. If the reference is NULL or invalid, an error is
returned.
- name: dpiSodaColl_remove
desc: |
Removes all of the documents in the collection that match the specified
options.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection from which documents are to be
removed. If the reference is NULL or invalid, an error is
returned.
- name: options
type: const dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a structure of type
[`dpiSodaOperOptions`] which specifies
options for restricting the number of documents removed. This
value can also be NULL which will result in all documents in the
collection being removed.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: count
type: uint64_t *
mode: OUT
desc: |
A pointer to a count of the number of documents removed that is
populated if the function completes successfully.
- name: dpiSodaColl_replaceOne
desc: |
Replaces the single document in the collection matching the given options
with the new document.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection in which the document is to be
replaced. If the reference is NULL or invalid, an error is
returned.
- name: options
type: const dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a structure of type
[`dpiSodaOperOptions`] which identifies
options for specifying the document which is to be replaced.
Currently at least the [`dpiSodaOperOptions.key`] member
must be specified or the error “ORA-40734: key for the document to
replace must be specified using the key attribute” will be raised.
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which is to replace the document in
the collection found using the provided options. If the reference
is NULL or invalid, an error is returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: replaced
type: int *
mode: OUT
desc: |
A pointer to a boolean value indicating if the document was
replaced (1) or not (0). This parameter may also be NULL if this
information is not required.
- name: replacedDoc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference which will be populated when
this function returns successfully. Call the function
[`dpiSodaDoc_release()`] when the reference is no longer
needed. This parameter can also be NULL if this information is not
required.
- name: dpiSodaColl_save
desc: |
Saves a document into the collection. This method is equivalent to
[`dpiSodaColl_insertOne()`] except that if client-assigned keys are
used, and the document with the specified key already exists in the
collection, it will be replaced with the input document.
This method requires Oracle Client 19.9 or higher to be used in addition to
the normal SODA requirements.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection in which the document is to be
saved. If the reference is NULL or invalid, an error is returned.
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which is to be saved into the
collection. If the reference is NULL or invalid, an error is
returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: savedDoc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference which will be populated when
this function returns successfully. Call the function
[`dpiSodaDoc_release()`] when the reference is no longer
needed. This parameter can also be NULL if this information is not
required.
- name: dpiSodaColl_saveWithOptions
desc: |
Saves a document into the collection. This method is equivalent to
[`dpiSodaColl_insertOneWithOptions()`] except that if client-assigned
keys are used, and the document with the specified key already exists in
the collection, it will be replaced with the input document.
This method requires Oracle Client 21.3 or higher to be used in addition to
the normal SODA requirements (also available in Oracle Client 19 from
19.11).
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection in which the document is to be saved.
If the reference is NULL or invalid, an error is returned.
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which is to be saved into the
collection. If the reference is NULL or invalid, an error is
returned.
- name: options
type: dpiSodaOperOptions *
mode: IN
desc: |
A pointer to a [`dpiSodaOperOptions`]
structure containing any desired options, or NULL. If the value is
NULL, this function behaves identically to
[`dpiSodaColl_save()`]. Options can only be specified with
Oracle Client 21.3 or higher (also available in Oracle Client 19
from 19.11).
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: savedDoc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference which will be populated when
this function returns successfully. Call the function
[`dpiSodaDoc_release()`] when the reference is no longer
needed. This parameter can also be NULL if this information is not
required.
- name: dpiSodaColl_truncate
desc: |
Removes all of the documents in a SODA collection in a similar manner to
a TRUNCATE TABLE statement.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: coll
type: dpiSodaColl *
mode: IN
desc: |
A reference to the collection in which all of the documents are to
be removed. If the reference is NULL or invalid, an error is
returned.
- name: dpiSodaCollCursor
kind: opaque struct
desc: |
SODA collection cursor handles are used to represent SODA collection cursors.
They are created by calling the function [`dpiSodaDb_getCollections()`]
and are destroyed when the last reference is released by calling the function
[`dpiSodaCollCursor_release()`].
See [this tracking issue](https://github.com/oracle/odpi/issues/110) for
known issues with SODA.
functions:
- name: dpiSodaCollCursor_addRef
desc: |
Adds a reference to the SODA collection cursor. This is intended for
situations where a reference to the cursor needs to be maintained
independently of the reference returned when the cursor was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: cursor
type: dpiSodaCollCursor *
mode: IN
desc: |
The cursor to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiSodaCollCursor_close
desc: |
Closes the cursor and makes it unusable for further work immediately,
rather than when the reference count reaches zero.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: cursor
type: dpiSodaCollCursor *
mode: IN
desc: |
A reference to the cursor which is to be closed. If the reference
is NULL or invalid, an error is returned.
- name: dpiSodaCollCursor_getNext
desc: |
Gets the next collection from the cursor, if there is one.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: cursor
type: dpiSodaCollCursor *
mode: IN
desc: |
The cursor from which the next collection is to be retrieved. The
reference is NULL or invalid, an error is returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together. Only the value
DPI_SODA_FLAGS_DEFAULT is currently supported.
- name: coll
type: dpiSodaColl **
mode: OUT
desc: |
A pointer to a reference to the next collection in the cursor, if
one exists. If no further collections are available from the
cursor, NULL is returned instead. The function
[`dpiSodaColl_release()`] should be called when the collection
is no longer required.
- name: dpiSodaCollCursor_release
desc: |
Releases a reference to the SODA collection cursor. A count of the
references to the cursor is maintained and when this count reaches zero,
the memory associated with the cursor is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: cursor
type: dpiSodaCollCursor *
mode: IN
desc: |
The cursor from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiSodaDb
kind: opaque struct
desc: |
SODA database handles are used to represent connections to the SODA database.
They are created by calling the function [`dpiConn_getSodaDb()`]. They are
destroyed when the last reference is released by calling
[`dpiSodaDb_release()`].
See [this tracking issue](https://github.com/oracle/odpi/issues/110) for
known issues with SODA.
functions:
- name: dpiSodaDb_addRef
desc: |
Adds a reference to the SODA database. This is intended for situations
where a reference to the SODA database needs to be maintained independently
of the reference returned when the database was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
The database to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiSodaDb_createCollection
desc: |
Creates a new SODA collection if a collection by that name does not exist.
If a collection by that name already exists, the collection is opened if
the metadata of the collection is equivalent to the supplied metadata;
otherwise, an error is returned.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
NOTE: the creation of the collection is performed using an autonomous
transaction. Any current transaction is left unchanged.
round_trips: Maybe
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
A reference to the database in which the SODA collection is to be
created. If the reference is NULL or invalid, an error is
returned.
- name: name
type: const char *
mode: IN
desc: |
The name of the collection which is to be created or opened.
NOTE: the name is case sensitive.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: metadata
type: const char *
mode: IN
desc: |
The metadata to use when creating the collection, or NULL if
default metadata should be used instead.
- name: metadataLength
type: uint32_t
mode: IN
desc: |
The length of the metadata parameter, in bytes, or 0 if metadata
is NULL.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: coll
type: dpiSodaColl **
mode: OUT
desc: |
A pointer to a reference to the newly created or opened SODA
collection if the function completes successfully. The function
[`dpiSodaColl_release()`] should be called when the collection
is no longer required.
- name: dpiSodaDb_createDocument
desc: |
Creates a SODA document that can later be inserted into a collection or
used to replace an existing document in a collection. This method should be
used when the content is binary or encoded text.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
A reference to the database in which the SODA document is going to
be inserted or replaced. If the reference is NULL or invalid, an
error is returned.
- name: key
type: const char *
mode: IN
desc: |
The key used to identify this document, or NULL if a key should be
generated instead (and the collection metadata supports key
generation).
- name: keyLength
type: uint32_t
mode: IN
desc: |
The length of the key used to identify the document, in bytes, or
0 if the key is NULL.
- name: content
type: const char *
mode: IN
desc: |
The content of the document to create, as a byte string. The type
of content is controlled by the mediaType parameter. If the
mediaType parameter is set to NULL or “application/json”, the
content must be a valid UTF-8 or UTF-16 encoded JSON string.
- name: contentLength
type: uint32_t
mode: IN
desc: |
The length of the document content, in bytes.
- name: mediaType
type: const char *
mode: IN
desc: |
The type of content that is found in the content parameter. This
value may also be NULL, in which case the default value of
“application/json” is assumed.
- name: mediaTypeLength
type: uint32_t
mode: IN
desc: |
The length of the mediaType parameter, in bytes, or 0 if the
mediaType parameter is NULL.
- name: flags
type: uint32_t
mode: IN
desc: |
Currently unused.
- name: doc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference that will be populated upon
successful completion of this function. Call the function
[`dpiSodaDoc_release()`] when it is no longer needed.
- name: dpiSodaDb_createJsonDocument
desc: |
Creates a SODA document that can later be inserted into a collection or
used to replace an existing document in a collection. This method should be
used when the content is JSON and Oracle Client 23 or higher is being used.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
A reference to the database in which the SODA document is going to
be inserted or replaced. If the reference is NULL or invalid, an
error is returned.
- name: key
type: const char *
mode: IN
desc: |
The key used to identify this document, or NULL if a key should be
generated instead (and the collection metadata supports key
generation).
- name: keyLength
type: uint32_t
mode: IN
desc: |
The length of the key used to identify the document, in bytes, or
0 if the key is NULL.
- name: content
type: const dpiJsonNode *
mode: IN
desc: |
The content of the document to create, as a value of type
[`dpiJsonNode`].
- name: flags
type: uint32_t
mode: IN
desc: |
Currently unused.
- name: doc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a document reference that will be populated upon
successful completion of this function. Call the function
[`dpiSodaDoc_release()`] when it is no longer needed.
- name: dpiSodaDb_getCollections
desc: |
Return a cursor to iterate over the SODA collections available in the
database.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
A reference to the database to use for iterating over available
SODA collections. If the reference is NULL or invalid, an error
is returned.
- name: startName
type: const char *
mode: IN
desc: |
A name from which to start iterating over collections available
in the database or NULL if all collections should be returned.
- name: startNameLength
type: uint32_t
mode: IN
desc: |
The length of the startName parameter, in bytes, or 0 if startName
is NULL.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: cursor
type: dpiSodaCollCursor **
mode: OUT
desc: |
A pointer to a reference to a newly allocated cursor if the
function completes successfully. The function
[`dpiSodaCollCursor_getNext()`] should be used to get the next
collection from the database and
[`dpiSodaCollCursor_release()`] should be used when the cursor
is no longer required.
- name: dpiSodaDb_getCollectionNames
desc: |
Return an array of names of SODA collections available in the database.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
A reference to the database to use for getting the names of
available SODA collections. If the reference is NULL or invalid,
an error is returned.
- name: startName
type: const char *
mode: IN
desc: |
The value from which to start getting the names of collections
available in the database or NULL if the names of all
collections should be returned.
- name: startNameLength
type: uint32_t
mode: IN
desc: |
The length of the startName parameter, in bytes, or 0 if startName
is NULL.
- name: limit
type: uint32_t
mode: IN
desc: |
The maximum number of collection names to return, or 0 if all
names matching the criteria should be returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: names
type: dpiStringList *
mode: IN
desc: |
A pointer to structure of type [`dpiStringList`]
which will be populated upon successful completion of this
function. A call to the function
[`dpiContext_freeStringList()`] should be made once the
names of the collections returned in this structure are no longer
needed.
- name: dpiSodaDb_openCollection
desc: |
Opens an existing SODA collection.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
A reference to the database in which the SODA collection is to be
opened. If the reference is NULL or invalid, an error is returned.
- name: name
type: const char *
mode: IN
desc: |
The name of the collection which is to be opened. NOTE: the name
is case sensitive.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together.
- name: coll
type: dpiSodaColl **
mode: OUT
desc: |
A pointer to a reference to the newly opened SODA collection if
the function completes successfully. The function
[`dpiSodaColl_release()`] should be called when the collection
is no longer required. If the collection with the specified name
does not exist, the returned reference is NULL and no error is
returned.
- name: dpiSodaDb_release
desc: |
Releases a reference to the database. A count of the references to the
database is maintained and when this count reaches zero, the memory
associated with the database is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: db
type: dpiSodaDb *
mode: IN
desc: |
The database from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiSodaDoc
kind: opaque struct
desc: |
SODA document handles are used to represent SODA documents in the database.
They are created by calling one of the functions
[`dpiSodaDb_createDocument()`], [`dpiSodaDocCursor_getNext()`],
[`dpiSodaColl_findOne()`], [`dpiSodaColl_getDataGuide()`],
[`dpiSodaColl_insertMany()`], [`dpiSodaColl_insertOne()`],
[`dpiSodaColl_replaceOne()`] or [`dpiSodaColl_save()`] and
are destroyed when the last reference is released by calling the function
[`dpiSodaDoc_release()`].
See [this tracking issue](https://github.com/oracle/odpi/issues/110) for
known issues with SODA.
functions:
- name: dpiSodaDoc_addRef
desc: |
Adds a reference to the SODA document. This is intended for situations
where a reference to the document needs to be maintained independently of
the reference returned when the document was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
The document to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiSodaDoc_getContent
desc: |
Returns the content of the document. If the document contains JSON an
exception will be thrown. Use [`dpiSodaDoc_getIsJson()`] to determine
whether to call this function or [`dpiSodaDoc_getJsonContent()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document from which the content is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the document content, as a byte string, which will be
populated upon successful comletion of this function. The pointer
returned will remain valid as long as a reference to the document
is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the document content, in bytes, which
will be populated upon successful completion of this function.
- name: encoding
type: const char **
mode: OUT
desc: |
A pointer to the the encoding in which the content was stored,
which will be populated upon successful completion of this
function. If the document content is not “application/json”, a
NULL value will be returned.
- name: dpiSodaDoc_getCreatedOn
desc: |
Returns the timestamp when the document was created, as a string, in ISO
format. This value will be empty if the metadata used to create the
collection in which the document is found does not support the storage of
this attribute, or if the document was created using
[`dpiSodaDb_createDocument()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document from which the creation timestamp is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the document creation timestamp, as a byte string in
the encoding used for CHAR data, which will be populated upon
successful completion of this function. The pointer returned will
remain valid as long as a reference to the document is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the document creation timestamp, in
bytes, which will be populated upon successful completion of this
function.
- name: dpiSodaDoc_getIsJson
desc: |
Returns a boolean value indicating if the document contains JSON or not.
This method should be used to determine if [`dpiSodaDoc_getContent()`]
or [`dpiSodaDoc_getJsonContent()`] should be called to get the content
of the document.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which will be checked to see if it
contains JSON content. If the reference is NULL or invalid, an
error is returned.
- name: isJson
type: int *
mode: OUT
desc: |
A pointer to a boolean value which will be populated upon
successful completion of this function.
- name: dpiSodaDoc_getJsonContent
desc: |
Returns the content of the document. If the document does not contain JSON
an exception will be thrown. Use [`dpiSodaDoc_getIsJson()`] to
determine whether to call this function or [`dpiSodaDoc_getContent()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document which will be checked to see if it
contains JSON content. If the reference is NULL or invalid, an
error is returned.
- name: value
type: dpiJson **
mode: OUT
desc: |
A pointer to a dpiJson reference which will be populated upon
successful completion of this function. This reference will remain
valid as long as the SODA document itself is valid.
- name: dpiSodaDoc_getKey
desc: |
Returns the key that uniquely identifies the document in the collection.
This value will be empty if no key was supplied when the document was
created using [`dpiSodaDb_createDocument()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document from which the key is to be retrieved.
If the reference is NULL or invalid, an error is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the document key, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The pointer returned will remain
valid as long as a reference to the document is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the document key, in bytes, which will
be populated upon successful completion of this function.
- name: dpiSodaDoc_getLastModified
desc: |
Returns the timestamp when the document was last modified, as a string, in
ISO format. This value will be empty if the metadata used to create the
collection in which the document is found does not support the storage of
this attribute, or if the document was created using
[`dpiSodaDb_createDocument()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document from which the last modified timestamp
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the document last modified timestamp, as a byte
string in the encoding used for CHAR data, which will be populated
upon successful completion of this function. The pointer returned
will remain valid as long as a reference to the document is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the document last modified timestamp,
in bytes, which will be populated upon successful completion of
this function.
- name: dpiSodaDoc_getMediaType
desc: |
Returns the media type of the document.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document from which the media type is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the media type, as a byte string in the encoding
used for CHAR data, which will be populated upon successful
completion of this function. The pointer returned will remain
valid as long as a reference to the document is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the media type, in bytes, which will
be populated upon successful completion of this function.
- name: dpiSodaDoc_getVersion
desc: |
Returns the current version of the document. This value will be empty if
the metadata used to create the collection in which the document is found
does not support the storage of this attribute, or if the document was
created using [`dpiSodaDb_createDocument()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
A reference to the document from which the version is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: value
type: const char **
mode: OUT
desc: |
A pointer to the version, as a byte string in the encoding used
for CHAR data, which will be populated upon successful completion
of this function. The pointer returned will remain valid as long
as a reference to the document is held.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
A pointer to the length of the version, in bytes, which will be
populated upon successful completion of this function.
- name: dpiSodaDoc_release
desc: |
Releases a reference to the SODA document. A count of the references to
the document is maintained and when this count reaches zero, the memory
associated with the document is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: doc
type: dpiSodaDoc *
mode: IN
desc: |
The document from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiSodaDocCursor
kind: opaque struct
desc: |
SODA document cursor handles are used to represent SODA document cursors.
They are created by calling the function [`dpiSodaColl_find()`]
and are destroyed when the last reference is released by calling the function
[`dpiSodaDocCursor_release()`].
See [this tracking issue](https://github.com/oracle/odpi/issues/110) for
known issues with SODA.
functions:
- name: dpiSodaDocCursor_addRef
desc: |
Adds a reference to the SODA document cursor. This is intended for
situations where a reference to the cursor needs to be maintained
independently of the reference returned when the cursor was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: cursor
type: dpiSodaDocCursor *
mode: IN
desc: |
The cursor to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiSodaDocCursor_close
desc: |
Closes the cursor and makes it unusable for further work immediately,
rather than when the reference count reaches zero.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: cursor
type: dpiSodaDocCursor *
mode: IN
desc: |
A reference to the cursor which is to be closed. If the reference
is NULL or invalid, an error is returned.
- name: dpiSodaDocCursor_getNext
desc: |
Gets the next document from the cursor, if there is one.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: cursor
type: dpiSodaDocCursor *
mode: IN
desc: |
The cursor from which the next document is to be retrieved. The
reference is NULL or invalid, an error is returned.
- name: flags
type: uint32_t
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiSodaFlags`], OR’ed together. Only the value
DPI_SODA_FLAGS_DEFAULT is currently supported.
- name: doc
type: dpiSodaDoc **
mode: OUT
desc: |
A pointer to a reference to the next document in the cursor, if
one exists. If no further documents are available from the cursor,
NULL is returned instead. The function
[`dpiSodaDoc_release()`] should be called when the document
is no longer required.
- name: dpiSodaDocCursor_release
desc: |
Releases a reference to the SODA document cursor. A count of the
references to the cursor is maintained and when this count reaches zero,
the memory associated with the cursor is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: cursor
type: dpiSodaDocCursor *
mode: IN
desc: |
The cursor from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiStmt
kind: opaque struct
desc: |
Statement handles are used to represent statements of all types (queries, DML,
DDL and PL/SQL). They are created by calling the function
[`dpiConn_prepareStmt()`] or the function [`dpiSubscr_prepareStmt()`].
They are also created implicitly when a variable of type DPI_ORACLE_TYPE_STMT
is created. Statement handles can be closed by calling the function
[`dpiStmt_close()`] or by releasing the last reference to the statement by
calling the function [`dpiStmt_release()`].
functions:
- name: dpiStmt_addRef
desc: |
Adds a reference to the statement. This is intended for situations where a
reference to the statement needs to be maintained independently of the
reference returned when the statement was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
The statement to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiStmt_bindByName
desc: |
Binds a variable to a named placeholder in the statement. A reference to
the variable is retained by the library and is released when the statement
itself is released or a new variable is bound to the same name.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to have the variable bound.
If the reference is NULL or invalid, an error is returned.
- name: name
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data giving the name
of the placeholder which is to be bound.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which is to be bound. If the reference
is NULL or invalid, an error is returned.
- name: dpiStmt_bindByPos
desc: |
Binds a variable to a placeholder in the statement by position. A reference
to the variable is retained by the library and is released when the
statement itself is released or a new variable is bound to the same
position.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to have the variable bound.
If the reference is NULL or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The position which is to be bound. The position of a placeholder
is determined by its location in the statement. Placeholders are
numbered from left to right, starting from 1, and duplicate names
do not count as additional placeholders.
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which is to be bound. If the reference
is NULL or invalid, an error is returned.
- name: dpiStmt_bindValueByName
desc: |
Binds a value to a named placeholder in the statement without the need to
create a variable directly. One is created implicitly and released when the
statement is released or a new value is bound to the same name.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to have the variable bound.
If the reference is NULL or invalid, an error is returned.
- name: name
type: const char *
mode: IN
desc: |
A byte string in the encoding used for CHAR data giving the name
of the placeholder which is to be bound.
- name: nameLength
type: uint32_t
mode: IN
desc: |
The length of the name parameter, in bytes.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The type of data that is being bound. It is expected to be one of
the values from the enumeration
[`dpiNativeTypeNum`].
- name: data
type: dpiData *
mode: IN
desc: |
The data which is to be bound, as a pointer to a
[`dpiData`] structure. A variable will be created
based on the type of data being bound and a reference to this
variable retained. Once the statement has been executed, this new
variable will be released.
- name: dpiStmt_bindValueByPos
desc: |
Binds a value to a placeholder in the statement without the need to create
a variable directly. One is created implicitly and released when the
statement is released or a new value is bound to the same position.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to have the variable bound.
If the reference is NULL or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The position which is to be bound. The position of a placeholder
is determined by its location in the statement. Placeholders are
numbered from left to right, starting from 1, and duplicate names
do not count as additional placeholders.
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The type of data that is being bound. It is expected to be one of
the values from the enumeration
[`dpiNativeTypeNum`].
- name: data
type: dpiData *
mode: IN
desc: |
The data which is to be bound, as a pointer to a
[`dpiData`] structure. A variable will be created
based on the type of data being bound and a reference to this
variable retained. Once the statement has been executed, this
new variable will be released.
- name: dpiStmt_close
desc: |
Closes the statement and makes it unusable for further work immediately,
rather than when the reference count reaches zero.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to be closed. If the
reference is NULL or invalid, an error is returned.
- name: tag
type: const char *
mode: IN
desc: |
A key to associate the statement with in the statement cache, in
the encoding used for CHAR data. NULL is also acceptable in which
case the statement is not tagged. This value is ignored for
statements that are acquired through bind variables (REF CURSOR)
or implicit results.
- name: tagLength
type: uint32_t
mode: IN
desc: |
The length of the tag parameter, in bytes, or 0 if the tag
parameter is NULL.
- name: dpiStmt_define
desc: |
Defines the variable that will be used to fetch rows from the statement. A
reference to the variable will be retained until the next define is
performed on the same position or the statement is closed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement on which the variable is to be
defined. If the reference is NULL or invalid, an error is
returned. Note that the statement must have already been executed
or an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The position which is to be defined. The first position is 1.
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which is to be used for fetching rows
from the statement at the given position. If the reference is NULL
or invalid, an error is returned.
- name: dpiStmt_defineValue
desc: |
Defines the type of data that will be used to fetch rows from the
statement. This is intended for use with the function
[`dpiStmt_getQueryValue()`], when the default data type derived from
the column metadata needs to be overridden by the application. Internally,
a variable is created with the specified data type and size.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement on which the define is to take place.
If the reference is NULL or invalid, an error is returned. Note
that the statement must have already been executed or an error is
returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The position which is to be defined. The first position is 1.
- name: oracleTypeNum
type: dpiOracleTypeNum
mode: IN
desc: |
The type of Oracle data that is to be used. It should be one of
the values from the enumeration
[`dpiOracleTypeNum`].
- name: nativeTypeNum
type: dpiNativeTypeNum
mode: IN
desc: |
The type of native C data that is to be used. It should be one of
the values from the enumeration
[`dpiNativeTypeNum`].
- name: size
type: uint32_t
mode: IN
desc: |
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 sizeIsBytes 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.
- name: sizeIsBytes
type: int
mode: IN
desc: |
A boolean value indicating if the size parameter refers to
characters or bytes. This flag is only used if the variable refers
to character data.
- name: objType
type: dpiObjectType *
mode: IN
desc: |
A reference to the object type of the object that is being bound
or fetched. This value is only used if the Oracle type is
DPI_ORACLE_TYPE_OBJECT.
- name: dpiStmt_deleteFromCache
desc: |
Excludes the associated SQL statement from the statement cache. If the
SQL statement was not already in the cache, it will not be added. This
function can be called before or after the statment is executed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to be excluded from the
statement cache. If the reference is NULL or invalid, an error is
returned.
- name: dpiStmt_execute
desc: |
Executes the statement using the bound values. For queries this makes
available metadata which can be acquired using the function
[`dpiStmt_getQueryInfo()`]. For non-queries, out and in-out variables
are populated with their values.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to be executed. If the
reference is NULL or invalid, an error is returned.
- name: mode
type: dpiExecMode
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiExecMode`], OR’ed together.
- name: numQueryColumns
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of columns which are being queried, which
will be populated upon successful execution of the statement. If
the statement does not refer to a query, the value is set to 0.
This parameter may also be NULL.
- name: dpiStmt_executeMany
desc: |
Executes the statement the specified number of times using the bound
values. Each bound variable must have at least this many elements allocated
or an error is returned.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to be executed. If the
reference is NULL or invalid, an error is returned.
- name: mode
type: dpiExecMode
mode: IN
desc: |
One or more of the values from the enumeration
[`dpiExecMode`], OR’ed together. Note that modes
DPI_MODE_EXEC_BATCH_ERRORS and DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS
are only supported with insert, update, delete and merge
statements.
- name: numIters
type: uint32_t
mode: IN
desc: |
The number of times the statement is executed. Each iteration
corresponds to one of the elements of the array that was bound
earlier.
- name: dpiStmt_fetch
desc: |
Fetches a single row from the buffers defined for the query. If no row is
available in the buffers, an internal fetch takes place to populate them,
if rows are available. The number of rows fetched into the internal
buffers can be set by calling [`dpiStmt_setFetchArraySize()`]. If the
statement does not refer to a query an error is returned. All columns that
have not been defined prior to this call are implicitly defined using the
metadata made available when the statement was executed.
The function [`dpiStmt_fetchRows()`] should be used instead of this
function if it is important to control when the internal fetch (and
round-trip to the database) takes place.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which a row is to be fetched. If
the reference is NULL or invalid, an error is returned.
- name: found
type: int *
mode: OUT
desc: |
A pointer to a boolean value indicating if a row was fetched or
not, which will be populated upon successful completion of this
function.
- name: bufferRowIndex
type: uint32_t *
mode: OUT
desc: |
A pointer to the buffer row index which will be populated upon
successful completion of this function if a row is found. This
index is used as the array position for getting values from the
variables that have been defined for the statement.
- name: dpiStmt_fetchRows
desc: |
Returns the number of rows that are available in the buffers defined for
the query. If no rows are currently available in the buffers, an internal
fetch takes place in order to populate them, if rows are available. The
number of rows fetched into the internal buffers can be set by calling
[`dpiStmt_setFetchArraySize()`]. If the statement does not refer to a
query an error is returned. All columns that have not been defined prior to
this call are implicitly defined using the metadata made available when the
statement was executed.
This function should be used instead of [`dpiStmt_fetch()`] if it is
important to control when the internal fetch (and round-trip to the
database) takes place.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which rows are to be fetched. If
the reference is NULL or invalid, an error is returned.
- name: maxRows
type: uint32_t
mode: IN
desc: |
The maximum number of rows to fetch. If the number of rows
available exceeds this value only this number will be fetched.
- name: bufferRowIndex
type: uint32_t *
mode: OUT
desc: |
A pointer to the buffer row index which will be populated upon
successful completion of this function. This index is used as the
array position for getting values from the variables that have
been defined for the statement.
- name: numRowsFetched
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of rows that have been fetched, populated
after the call has completed successfully.
- name: moreRows
type: int *
mode: OUT
desc: |
A pointer to a boolean value indicating if there are potentially
more rows that can be fetched after the ones fetched by this
function call.
- name: dpiStmt_getBatchErrorCount
desc: |
Returns the number of batch errors that took place during the last
execution with batch mode enabled. Batch errors are only available when
both the client and the server are at 12.1.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the number of batch errors
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: count
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of batch errors that took place, which is
populated after successful completion of the function.
- name: dpiStmt_getBatchErrors
desc: |
Returns the batch errors that took place during the last execution with
batch mode enabled. Batch errors are only available when both the client
and the server are at 12.1.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the batch errors are to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: numErrors
type: uint32_t
mode: IN
desc: |
The size of the errors array in number of elements. The number of
batch errors that are available can be determined using
[`dpiStmt_getBatchErrorCount()`].
- name: errors
type: dpiErrorInfo *
mode: IN
desc: |
A pointer to the first element of an array of
[`dpiErrorInfo`] structures which is assumed to
contain the number of elements specified by the numErrors
parameter.
- name: dpiStmt_getBindCount
desc: |
Returns the number of bind variables in the prepared statement. In SQL
statements this is the total number of bind variables whereas in PL/SQL
statements this is the count of the **unique** bind variables.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the number of bind
variables is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: count
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of bind variables found in the statement,
which is populated upon successful completion of the function.
- name: dpiStmt_getBindNames
desc: |
Returns the names of the unique bind variables in the prepared statement.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the names of bind variables
are to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: numBindNames
type: uint32_t *
mode: IN/OUT
desc: |
A pointer to the size of the bindNames and bindNameLengths arrays
in number of elements. This value must be large enough to hold all
of the unique bind variables in the prepared statement or an error
will be returned. The maximum number of bind variables can be
determined by calling [`dpiStmt_getBindCount()`]. Upon
successful completion of this function, the actual number of
unique bind variables in the prepared statement will be populated.
- name: bindNames
type: const char **
mode: OUT
desc: |
An array of pointers to byte strings in the encoding used for CHAR
data. The size of the array is specified using the numBindNames
parameter. When the function completes this array will be filled
with the names of the unique bind variables in the statement.
- name: bindNameLengths
type: uint32_t *
mode: OUT
desc: |
A pointer to the first element of an array of integers containing
the lengths of the bind variable names which is filled in upon
successful completion of the function. The number of elements is
assumed to be specified by the numBindNames parameter.
- name: dpiStmt_getFetchArraySize
desc: |
Gets the array size used for performing fetches.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the fetch array size is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: arraySize
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiStmt_getImplicitResult
desc: |
Returns the next implicit result available from the last execution of the
statement. Implicit results are only available when both the client and
server are 12.1 or higher.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the next implicit result
is to be retrieved. If the reference is NULL or invalid, an error
is returned.
- name: implicitResult
type: dpiStmt **
mode: OUT
desc: |
A pointer to a reference to a statement which will be populated
with the next implicit result upon successful completion of the
function. If no implicit results remain, the reference will be set
to NULL. The reference that is returned must be released as soon
as it is no longer needed.
- name: dpiStmt_getInfo
desc: |
Returns information about the statement.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which information is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiStmtInfo *
mode: OUT
desc: |
A pointer to a structure of type [`dpiStmtInfo`]
which will be filled in with information about the statement upon
successful completion of the function.
- name: dpiStmt_getLastRowid
desc: |
Returns the rowid of the last row that was affected by the statement.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the rowid of the last row
affected is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: rowid
type: dpiRowid **
mode: OUT
desc: |
A pointer to a rowid which will be populated upon successful
completion of this function. If no statement has been executed,
the last statement executed was not a DML statement or no rows
were affected by a DML statement, the value returned will be NULL.
If a rowid is returned, the reference will remain valid until the
next call to this function or until the statement is closed. If
the reference is needed for a longer period of time, call
[`dpiRowid_addRef()`] to acquire an independent reference (and
call [`dpiRowid_release()`] when that reference is no longer
required).
- name: dpiStmt_getNumQueryColumns
desc: |
Returns the number of columns that are being queried.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the number of query columns
is to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: numQueryColumns
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of columns which are being queried by the
statement, which is filled in upon successful completion of the
function. If the statement does not refer to a query, the value is
populated with 0.
- name: dpiStmt_getOciAttr
desc: |
Returns the value of an OCI attribute. This is intended solely for testing
attributes that are not otherwise supported by ODPI-C and should not be
used for any other purpose. Use only as directed by Oracle.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the OCI attribute is to be
returned. If the reference is NULL or invalid, an error is
returned.
- name: attribute
type: uint32_t
mode: IN
desc: |
The attribute to acquire.
- name: value
type: dpiDataBuffer *
mode: OUT
desc: |
A data buffer which will be populated with the value of the OCI
attribute upon successfully completing this function.
- name: valueLength
type: uint32_t *
mode: OUT
desc: |
The length of the attribute which will be populated upon
succesfully completing this function.
- name: dpiStmt_getPrefetchRows
desc: |
Gets the number of rows that will be prefetched by the Oracle Client
library when a query is executed.
The value may be changed by calling [`dpiStmt_setPrefetchRows()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the number of rows to
prefetch is to be retrieved. If the reference is NULL or invalid,
an error is returned.
- name: numRows
type: uint32_t *
mode: OUT
desc: |
A pointer to the value which will be populated upon successful
completion of this function.
- name: dpiStmt_getQueryInfo
desc: |
Returns information about the column that is being queried.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the column metadata is to
be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The position of the column whose metadata is to be retrieved. The
first position is 1.
- name: info
type: dpiQueryInfo *
mode: OUT
desc: |
A pointer to a [`dpiQueryInfo`] structure which
will be filled in upon successful completion of the function.
- name: dpiStmt_getQueryValue
desc: |
Returns the value of the column at the given position for the currently
fetched row, without needing to provide a variable. If the data type of
the column needs to be overridden, the function
[`dpiStmt_defineValue()`] can be called to specify a different type
after executing the statement but before fetching any data.
This function should only be called after a call to the function
[`dpiStmt_fetch()`] has succeeded and indicated that a row is
available.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the column value is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The position of the column whose value is to be retrieved. The
first position is 1.
- name: nativeTypeNum
type: dpiNativeTypeNum *
mode: OUT
desc: |
A pointer to the native type that is used by the value, which will
be populated upon successful completion of this function. It will
be one of the values from the enumeration
[`dpiNativeTypeNum`].
- name: data
type: dpiData **
mode: OUT
desc: |
A pointer to a reference to an internally created
[`dpiData`] structure which will be populated upon
successful completion of this function. The structure contains the
value of the column at the specified position. Note that any
references to LOBs, statements, objects, and rowids are owned by
the statement. If you wish to retain these values independently of
the statement, a reference must be added by calling one of
[`dpiLob_addRef()`], [`dpiStmt_addRef()`],
[`dpiObject_addRef()`] or [`dpiRowid_addRef()`].
- name: dpiStmt_getRowCount
desc: |
Returns the number of rows affected by the last DML statement that was
executed, the number of rows currently fetched from a query, or the number
of successful executions of a PL/SQL block. In all other cases 0 is
returned.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the row count is to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: count
type: uint64_t *
mode: OUT
desc: |
A pointer to the row count which will be populated upon successful
completion of the function.
- name: dpiStmt_getRowCounts
desc: |
Returns an array of row counts affected by the last invocation of
[`dpiStmt_executeMany()`] with the array DML rowcounts mode enabled.
This feature is only available if both client and server are at 12.1.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the row counts are to be
retrieved. If the reference is NULL or invalid, an error is
returned.
- name: numRowCounts
type: uint32_t *
mode: OUT
desc: |
A pointer to the size of the rowCounts array which is being
returned. It is populated upon successful completion of the
function.
- name: rowCounts
type: uint64_t **
mode: OUT
desc: |
A pointer to an array of row counts which is populated upon
successful completion of the function. This array should be
considered read-only.
- name: dpiStmt_getSubscrQueryId
desc: |
Returns the id of the query that was just registered on the subscription
by calling [`dpiStmt_execute()`] on a statement prepared by calling
[`dpiSubscr_prepareStmt()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement from which the query id should be
retrieved. This statement should have been prepared using the
function [`dpiSubscr_prepareStmt()`]. If the reference is NULL
or invalid an error is returned.
- name: queryId
type: uint64_t *
mode: OUT
desc: |
A pointer to the query id, which is filled in upon successful
completion of the function.
- name: dpiStmt_release
desc: |
Releases a reference to the statement. A count of the references to the
statement is maintained and when this count reaches zero, the memory
associated with the statement is freed and the statement is closed if that
has not already taken place using the function [`dpiStmt_close()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
The statement from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiStmt_scroll
desc: |
Scrolls the statement to the position in the cursor specified by the mode
and offset.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Yes
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which is to be scrolled to a
particular row position. If the reference is NULL or invalid, an
error is returned.
- name: mode
type: dpiFetchMode
mode: IN
desc: |
One of the values from the enumeration
[`dpiFetchMode`].
- name: offset
type: int32_t
mode: IN
desc: |
A value which is used with the mode in order to determine the row
position in the cursor.
- name: rowCountOffset
type: int32_t
mode: IN
desc: |
An offset to the row count used when calculating the desired row
to be fetched. This is needed when a client has fetched multiple
rows but has not yet consumed all of them. If this is not being
done by the client, the value 0 is appropriate.
- name: dpiStmt_setFetchArraySize
desc: |
Sets the array size used for performing fetches. All variables defined for
fetching must have this many (or more) elements allocated for them. The
higher this value is the less network round trips are required to fetch
rows from the database but more memory is also required. A value of zero
will reset the array size to the default value of
DPI_DEFAULT_FETCH_ARRAY_SIZE.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement on which the fetch array size is to
be set. If the reference is NULL or invalid, an error is returned.
- name: arraySize
type: uint32_t
mode: IN
desc: |
The number of rows which should be fetched each time more rows
need to be fetched from the database.
- name: dpiStmt_setOciAttr
desc: |
Sets the value of an OCI attribute. This is intended solely for testing
attributes that are not otherwise supported by ODPI-C and should not be
used for any other purpose. Use only as directed by Oracle.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement on which the OCI attribute is to be
set. If the reference is NULL or invalid, an error is returned.
- name: attribute
type: uint32_t
mode: IN
desc: |
The attribute to set.
- name: value
type: void *
mode: IN
desc: |
A pointer to the data which is to be set.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the data which is to be set.
- name: dpiStmt_setPrefetchRows
desc: |
Sets the number of rows that will be prefetched by the Oracle Client
library when a query is executed. The default value is
*DPI_DEFAULT_PREFETCH_ROWS* (2). Increasing this value may reduce the
number of round-trips to the database that are required in order to
fetch rows, but at the cost of increasing memory requirements. Setting this
value to 0 will disable prefetch completely, which may be useful when
the timing for fetching rows must be controlled by the caller.
The current value can be determined by calling
[`dpiStmt_getPrefetchRows()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement on which the number of rows to
prefetch is to be set. If the reference is NULL or invalid, an
error is returned.
- name: numRows
type: uint32_t
mode: OUT
desc: |
The number of rows to prefetch.
- name: dpiSubscr
kind: opaque struct
desc: |
Subscription handles are used to represent subscriptions to events such as
continuous query notification and object change notification. They are created
by calling the function [`dpiConn_subscribe()`] and are destroyed
by calling the function [`dpiConn_unsubscribe()`] or releasing the last
reference by calling the function [`dpiSubscr_release()`].
functions:
- name: dpiSubscr_addRef
desc: |
Adds a reference to the subscription. This is intended for situations where
a reference to the subscription needs to be maintained independently of the
reference returned when the subscription was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: subscr
type: dpiSubscr *
mode: IN
desc: |
The subscription to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiSubscr_prepareStmt
desc: |
Prepares a statement for registration on the subscription. The statement is
then registered by calling the function [`dpiStmt_execute()`]. The
reference to the statement that is returned should be released as soon as
it is no longer needed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: subscr
type: dpiSubscr *
mode: IN
desc: |
A reference to the subscription on which the statement is to be
prepared for registration. If the reference is NULL or invalid, an
error is returned.
- name: sql
type: const char *
mode: IN
desc: |
The SQL that is to be prepared, as a byte string in the encoding
used for CHAR data.
- name: sqlLength
type: uint32_t
mode: IN
desc: |
The length of the sql parameter, in bytes.
- name: stmt
type: dpiStmt **
mode: OUT
desc: |
A reference to the statement that was prepared, which will be
populated when the function completes successfully.
- name: dpiSubscr_release
desc: |
Releases a reference to the subscription. A count of the references to the
subscription is maintained and when this count reaches zero, the memory
associated with the subscription is freed. The subscription is also
deregistered so that notifications are no longer sent, if this was not
already done using the function [`dpiConn_unsubscribe()`].
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: subscr
type: dpiSubscr *
mode: IN
desc: |
The subscription from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiVar
kind: opaque struct
desc: |
Variable handles are used to represent memory areas used for transferring data
to and from the database. They are created by calling the function
[`dpiConn_newVar()`]. They are destroyed when the last reference to the
variable is released by calling the function [`dpiVar_release()`]. They are
bound to statements by calling the function [`dpiStmt_bindByName()`] or the
function [`dpiStmt_bindByPos()`]. They can also be used for fetching data
from the database by calling the function [`dpiStmt_define()`].
functions:
- name: dpiVar_addRef
desc: |
Adds a reference to the variable. This is intended for situations where a
reference to the variable needs to be maintained independently of the
reference returned when the variable was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
The variable to which a reference is to be added. If the reference
is NULL or invalid, an error is returned.
- name: dpiVar_copyData
desc: |
Copies the data from one variable to another variable.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
The variable into which data is to be copied. If the reference is
NULL or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position into which the data is to be copied. The first
position is 0. If the array position specified exceeds the number
of elements allocated in the variable, an error is returned.
- name: sourceVar
type: dpiVar *
mode: IN
desc: |
The variable from which is to be copied. If the reference is NULL
or invalid, an error is returned.
- name: sourcePos
type: uint32_t
mode: IN
desc: |
The array position from which the data is to be copied. The first
position is 0. If the array position specified exceeds the number
of elements allocated in the source variable, an error is
returned.
- name: dpiVar_getNumElementsInArray
desc: |
Returns the number of elements in a PL/SQL index-by table if the variable
was created as an array by the function [`dpiConn_newVar()`]. If the
variable is one of the output bind variables of a DML returning statement,
however, the value returned will correspond to the number of rows returned
by the DML returning statement. In all other cases, the value returned will
be the number of elements the variable was created with.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable from which the number of elements is
to be retrieved. If the reference is NULL or invalid, an error is
returned.
- name: numElements
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of elements, which will be populated when
the function completes successfully.
- name: dpiVar_getReturnedData
desc: |
Returns a pointer to an array of [`dpiData`] structures used
for transferring data to and from the database. These structures are
allocated by the variable itself when a DML returning statement is executed
and the variable is bound.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which contains the data structures
used for transferring data to and from the database. If the
reference is NULL or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable from which returned data is to
be determined. The first position is 0. If the position exceeds
the number of elements allocated by the variable an error is
returned.
- name: numElements
type: uint32_t *
mode: OUT
desc: |
A pointer to the number of elements that have been allocated by
the variable, which will be populated when the function completes
successfully. The value 0 is returned if the statement is not a
DML returning statement or the statement returned no data.
- name: data
type: dpiData **
mode: OUT
desc: |
A pointer to an array of [`dpiData`] structures which
will be populated when the function completes successfully. A NULL
value is returned if the statement is not a DML returning
statement or the statement returned no data.
- name: dpiVar_getSizeInBytes
desc: |
Returns the size of the buffer used for one element of the array used for
fetching/binding Oracle data.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable whose buffer size is to be retrieved.
If the reference is NULL or invalid, an error is returned.
- name: sizeInBytes
type: uint32_t *
mode: OUT
desc: |
A pointer to the size of the buffer, in bytes, which will be
populated when the function completes successfully.
- name: dpiVar_release
desc: |
Releases a reference to the variable. A count of the references to the
variable is maintained and when this count reaches zero, the memory
associated with the variable is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
The variable from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiVar_setFromBytes
desc: |
Sets the variable value to the specified byte string. In the case of the
variable’s Oracle type being DPI_ORACLE_TYPE_NUMBER, the byte string is
converted to an Oracle number during the call to this function.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: Maybe
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned. If the variable does not
use native type DPI_NATIVE_TYPE_BYTES or DPI_NATIVE_TYPE_LOB, an
error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: value
type: const char *
mode: IN
desc: |
A pointer to the byte string which contains the data to be set.
The data is copied to the variable buffer and does not need to be
retained after this function call has completed. This value can be
NULL if the valueLength parameter is 0.
- name: valueLength
type: uint32_t
mode: IN
desc: |
The length of the data to be set, in bytes. The maximum value
permitted is 2 bytes less than 1 GB (1,073,741,822 bytes).
- name: dpiVar_setFromJson
desc: |
Sets the variable value to the specified JSON value.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned. If the variable does not
use native type DPI_NATIVE_TYPE_JSON, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: json
type: dpiJson *
mode: IN
desc: |
A reference to the JSON value which should be set. If the
reference is null or invalid, an error is returned. A reference is
retained by the variable until a new value is set or the variable
itself is freed.
- name: dpiVar_setFromLob
desc: |
Sets the variable value to the specified LOB.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB which should be set. If the reference is
null or invalid, an error is returned. A reference is retained by
the variable until a new value is set or the variable itself is freed.
- name: dpiVar_setFromObject
desc: |
Sets the variable value to the specified object.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: obj
type: dpiObject *
mode: IN
desc: |
A reference to the object which should be set. If the reference is
null or invalid, an error is returned. A reference is retained by
the variable until a new value is set or the variable itself is
freed.
- name: dpiVar_setFromRowid
desc: |
Sets the variable value to the specified rowid.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: rowid
type: dpiRowid *
mode: IN
desc: |
A reference to the rowid which should be set. If the reference is
null or invalid, an error is returned. A reference is retained by
the variable until a new value is set or the variable itself is
freed.
- name: dpiVar_setFromStmt
desc: |
Sets the variable value to the specified statement.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement which should be set. If the reference
is null or invalid, an error is returned. A reference is retained
by the variable until a new value is set or the variable itself is
freed.
- name: dpiVar_setFromVector
desc: |
Sets the variable value to the specified vector value.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable which should be set. If the reference
is null or invalid, an error is returned. If the variable does not
use native type DPI_NATIVE_TYPE_VECTOR, an error is returned.
- name: pos
type: uint32_t
mode: IN
desc: |
The array position in the variable which is to be set. The first
position is 0. If the position exceeds the number of elements
allocated by the variable an error is returned.
- name: vector
type: dpiVector *
mode: IN
desc: |
A reference to the vector value which should be set. If the
reference is null or invalid, an error is returned. A reference is
retained by the variable until a new value is set or the variable
itself is freed.
- name: dpiVar_setNumElementsInArray
desc: |
Sets the number of elements in a PL/SQL index-by table.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: var
type: dpiVar *
mode: IN
desc: |
A reference to the variable in which the number of elements is to
be set. If the reference is NULL or invalid, an error is returned.
- name: numElements
type: uint32_t
mode: IN
desc: |
The number of elements that PL/SQL should consider part of the
array. This number should not exceed the number of elements that
have been allocated in the variable.
- name: dpiVector
kind: opaque struct
desc: |
Vector handles are used to represent vector values stored in the database. They
are only available from Oracle Client and Database 23.4 and higher. They can be
created explicitly by a call to [`dpiConn_newVector()`] or implicitly when
a variable of type DPI_ORACLE_TYPE_VECTOR is created. They are destroyed when
the last reference is released by a call to the function
[`dpiVector_release()`].
functions:
- name: dpiVector_addRef
desc: |
Adds a reference to the vector value. This is intended for situations where
a reference to the vector value needs to be maintained independently of the
reference returned when the vector value was created.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: vector
type: dpiVector *
mode: IN
desc: |
The vector value to which a reference is to be added. If the
reference is NULL or invalid, an error is returned.
- name: dpiVector_getValue
desc: |
Returns information about the vector.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: vector
type: dpiVector *
mode: IN
desc: |
The vector value from which the information is to be extracted. If
the reference is NULL or invalid, an error is returned.
- name: info
type: dpiVectorInfo *
mode: OUT
desc: |
A pointer to a structure of type
[`dpiVectorInfo`] which will be populated upon
successful completion of this function. The structure’s contents
will remain valid as long as a reference is held to the vector
value and the vector value itself is not modified.
- name: dpiVector_release
desc: |
Releases a reference to the vector value. A count of the references to the
vector value is maintained and when this count reaches zero, the memory
associated with the vector value is freed.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: vector
type: dpiVector *
mode: IN
desc: |
The vector value from which a reference is to be released. If the
reference is NULL or invalid, an error is returned.
- name: dpiVector_setValue
desc: |
Sets the vector value from the supplied information.
The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.
round_trips: No
return: int
params:
- name: vector
type: dpiVector *
mode: IN
desc: |
The vector value which is to be modified using the supplied
information. If the reference is NULL or invalid, an error is
returned.
- name: info
type: dpiVectorInfo *
mode: IN
desc: |
A pointer to a structure of type
[`dpiVectorInfo`] which contains the information
to be set on the vector.
- name: dpiAccessToken
kind: struct
desc: |
This structure is used when creating connection pools and standalone
connections using token based authentication. Oracle Client libraries
must be 19.14 (or later), or 21.5 (or later).
The externalAuth must be set to 1 and in addition, homogeneous must be
set to 1 when creating a pool. The user (or username) and password properties
should not be set.
Both token and privateKey (and their lengths) must be set while using IAM
for token based authentication.
Only token and it’s length must be set while using OAuth for token based
authentication.
members:
- name: token
type: const char *
desc: |
Specifies the database authentication token string used for token based
authentication.
- name: tokenLength
type: uint32_t
desc: |
Specifies the database authentication token string length used for token
based authentication.
- name: privateKey
type: const char *
desc: |
Specifies the database authentication private key string used for token
based authentication.
- name: privateKeyLength
type: uint32_t
desc: |
Specifies the database authentication private key string length used for
token based authentication.
- name: dpiAnnotation
kind: struct
desc: |
This structure is part of the structure [`dpiDataTypeInfo`]
and provides information about [annotations](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/annotations_clause.html#GUID-1AC16117-BBB6-4435-8794-2B99F8F68052)
associated with columns that are fetched from the database. Annotations are
only available with Oracle Database 23ai (or later). Oracle Client libraries
must also be 23.1 (or later).
members:
- name: key
type: const char *
desc: |
Specifies the annoation key.
- name: keyLength
type: uint32_t
desc: |
Specifies the length of the annotation key, in bytes.
- name: value
type: const char *
desc: |
Specifies the annoation value.
- name: valueLength
type: uint32_t
desc: |
Specifies the length of the annotation value, in bytes.
- name: dpiAppContext
kind: struct
desc: |
This structure is used for passing application context to the database during
the process of creating standalone connections. These values are ignored when
acquiring a connection from a session pool or when using DRCP (Database
Resident Connection Pooling). All values must be set to valid values prior to
being used in the [`dpiConnCreateParams`] structure and
must remain valid until the execution of [`dpiConn_create()`] completes.
Values set using this structure are available in logon triggers by using the
sys_context() SQL function.
members:
- name: namespaceName
type: const char *
desc: |
Specifies the value of the “namespace” parameter to sys_context(). It is
expected to be a byte string in the encoding specified in the
[`dpiConnCreateParams`] structure and must not be
NULL.
- name: namespaceNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiAppContext.namespaceName`] member,
in bytes.
- name: name
type: const char *
desc: |
Specifies the value of the “parameter” parameter to sys_context(). It is
expected to be a byte string in the encoding specified in the
[`dpiConnCreateParams`] structure and must not be
NULL.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiAppContext.name`] member, in bytes.
- name: value
type: const char *
desc: |
Specifies the value that will be returned from sys_context(). It is
expected to be a byte string in the encoding specified in the
[`dpiConnCreateParams`] structure and must not be
NULL.
- name: valueLength
type: uint32_t
desc: |
Specifies the length of the [`dpiAppContext.value`] member, in bytes.
- name: dpiBytes
kind: struct
desc: |
This structure is used for passing byte strings to and from the database in
the structure [`dpiData`].
members:
- name: ptr
type: char *
desc: |
Specifies the pointer to the memory allocated by ODPI-C for the variable.
For strings, data written to this memory should be in the encoding
appropriate to the type of data being transferred. When data is transferred
from the database it will be in the correct encoding already.
- name: length
type: uint32_t
desc: |
Specifies the length of the byte string, in bytes.
- name: encoding
type: const char *
desc: |
Specifies the encoding for character data. This value is populated when
data is transferred from the database. It is ignored when data is being
transferred to the database.
- name: dpiCommonCreateParams
kind: struct
desc: |
This structure is used for creating session pools and standalone connections to
the database. All members are initialized to default values using the
[`dpiContext_initCommonCreateParams()`] function.
members:
- name: createMode
type: dpiCreateMode
desc: |
Specifies the mode used for creating connections. It is expected to be
one or more of the values from the enumeration
[`dpiCreateMode`], OR’ed together. The default value is
*DPI_MODE_CREATE_DEFAULT*.
Note that when this structure is used during creation of a pool, the mode
*DPI_MODE_CREATE_THREADED* is automatically enabled regardless of what
value is set in this member.
- name: encoding
type: const char *
desc: |
Specifies the encoding to use for CHAR data, as a null-terminated ASCII
string. Either an IANA or Oracle specific character set name is expected.
NULL is also acceptable which implies the use of the NLS_LANG environment
variable (or ASCII, if the NLS_LANG environment variable is not set).
The default value is the value of the member
[`dpiContextCreateParams.defaultEncoding`] specified when the call to
[`dpiContext_createWithParams()`] was made.
- name: nencoding
type: const char *
desc: |
Specifies the encoding to use for NCHAR data, as a null-terminated ASCII
string. Either an IANA or Oracle specific character set name is expected.
NULL is also acceptable which implies the use of the NLS_NCHAR environment
variable (or the same value as the [`dpiCommonCreateParams.encoding`]
member if the NLS_NCHAR environment variable is not set). The default
value is the value of the member
[`dpiContextCreateParams.defaultEncoding`] specified when the call to
[`dpiContext_createWithParams()`] was made.
- name: edition
type: const char *
desc: |
Specifies the edition to be used when creating a standalone connection. It
is expected to be NULL (meaning that no edition is set) or a byte string in
the encoding specified by the [`dpiCommonCreateParams.encoding`]
member. The default value is NULL.
- name: editionLength
type: uint32_t
desc: |
Specifies the length of the [`dpiCommonCreateParams.edition`] member,
in bytes. The default value is 0.
- name: driverName
type: const char *
desc: |
Specifies the name of the driver that is being used. It is expected to be
NULL or a byte string in the encoding specified by the
[`dpiCommonCreateParams.encoding`] member. The default value is the
value of the member [`dpiContextCreateParams.defaultDriverName`]
specified when the call to
[`dpiContext_createWithParams()`] was made.
- name: driverNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiCommonCreateParams.driverName`]
member, in bytes. The default value is the length of the member
[`dpiContextCreateParams.defaultDriverName`] specified when the call
to [`dpiContext_createWithParams()`] was made.
- name: sodaMetadataCache
type: int
desc: |
Specifies whether to enable the SODA metadata cache or not, which can
significantly improve the performance of repeated calls to methods
[`dpiSodaDb_createCollection()`] (when not specifying a value for the
metadata parameter) and [`dpiSodaDb_openCollection()`]. This requires
Oracle Client 21.3 or higher (also available in Oracle Client 19 from
19.11).
- name: stmtCacheSize
type: uint32_t
desc: |
Specifies the number of statements to retain in the statement cache. Use a
value of 0 to disable the statement cache completely.
- name: accessToken
type: dpiAccessToken *
desc: |
Specifies a pointer to a [`dpiAccessToken`] structure.
Each member of structure is populated with authentication parameters used for
token based authentication. This requires Oracle Client 19.4 (or later),
or 21.5 (or later).
- name: dpiConnCreateParams
kind: struct
desc: |
This structure is used for creating connections to the database, whether
standalone or acquired from a session pool. All members are initialized to
default values using the [`dpiContext_initConnCreateParams()`] function.
Care should be taken to ensure a copy of this structure exists only as long as
needed to create the connection since it can contain a clear text copy of
credentials used for connecting to the database.
members:
- name: authMode
type: dpiAuthMode
desc: |
Specifies the mode used for authorizing connections. It is expected to be
one or more of the values from the enumeration
[`dpiAuthMode`], OR’ed together. The default value is
DPI_MODE_AUTH_DEFAULT.
- name: connectionClass
type: const char *
desc: |
Specifies the connection class to use when connecting to the database. This
is used with DRCP (database resident connection pooling) or to further
subdivide a session pool. It is expected to be NULL (meaning that no
connection class will be set) or a byte string in the encoding used for
CHAR data. The default value is NULL.
- name: connectionClassLength
type: uint32_t
desc: |
Specifies the length of the
[`dpiConnCreateParams.connectionClass`] member, in bytes. The
default value is 0.
- name: purity
type: dpiPurity
desc: |
Specifies the level of purity required when creating a connection using a
connection class. It is expected to be one of the values from the
enumeration [`dpiPurity`]. The default value is
DPI_PURITY_DEFAULT.
- name: newPassword
type: const char *
desc: |
Specifies the new password to set when creating a connection. This value
is only used when creating a standalone connection. It is expected to be
NULL or a byte string in the encoding used for CHAR data. The default value
of this member is NULL. If specified, the password for the user is changed
when the connection is created (useful when the password has expired and a
session cannot be established without changing the password).
- name: newPasswordLength
type: uint32_t
desc: |
Specifies the length of the [`dpiConnCreateParams.newPassword`]
member, in bytes. The default value is 0.
- name: appContext
type: dpiAppContext *
desc: |
Specifies the application context that will be set when the connection is
created. This value is only used when creating standalone connections. It
is expected to be NULL or an array of [`dpiAppContext`]
structures. The context specified here can be used in logon triggers, for
example. The default value is NULL.
- name: numAppContext
type: uint32_t
desc: |
Specifies the number of elements found in the
[`dpiConnCreateParams.appContext`] member. The default value is 0.
- name: externalAuth
type: int
desc: |
Specifies whether external authentication should be used to create the
connection. If this value is 0, the user name and password values must be
specified in the call to [`dpiConn_create()`]; otherwise, the user
name and password values must be zero length or NULL. The default value is
0.
- name: externalHandle
type: void *
desc: |
Specifies an OCI service context handle created externally that will be
used instead of creating a connection from scratch. The default value is
NULL. Note that this connection depends on the external handle remaining
valid for the lifetime of this connection. It is also important to ensure
that the last reference to this connection is released before the external
service context handle and environment handle are destroyed. Unlike regular
connections, no attempt is made to rollback any outstanding transactions or
close any open statements, objects and LOBs when the last reference to this
connection is released, since attempts to do so after the external service
context handle and environment are destroyed may result in crashes and
other undesirable behavior.
- name: pool
type: dpiPool *
desc: |
Specifies the session pool from which to acquire a connection or NULL if
a standalone connection should be created. The default value is NULL. If
the method [`dpiPool_acquireConnection()`] is being called, this value
is ignored.
- name: tag
type: const char *
desc: |
Specifies the tag to use when acquiring a connection from a session pool.
This member is ignored when creating a standalone connection. If specified,
the tag restricts the type of session that can be returned to those with
that tag or a NULL tag. If the member
[`dpiConnCreateParams.matchAnyTag`] is set, however, any session can
be returned if no matching sessions are found.
The value is expected to be NULL (any session can be returned) or a byte
string in the encoding used for CHAR data. The default value is NULL. If
specified, the value should be one or more properties (specified in the
form *key=value*) separated by semicolons.
- name: tagLength
type: uint32_t
desc: |
Specifies the length of the [`dpiConnCreateParams.tag`] member, in
bytes. The default value is 0.
- name: matchAnyTag
type: int
desc: |
Specifies whether any tagged session should be accepted when acquiring a
connection from a session pool, if no connection using the tag specified
in the [`dpiConnCreateParams.tag`] is available. This value is only
used when acquiring a connection from a session pool. The default value is
0.
- name: outTag
type: const char *
desc: |
Specifies the tag of the connection that was acquired from a session pool,
or NULL if the session was not tagged. This member is left untouched when
creating a standalone connection and is filled in only if the connection
acquired from the session pool was tagged. If filled in, it is a byte
string in the encoding used for CHAR data.
- name: outTagLength
type: uint32_t
desc: |
Specifies the length of the [`dpiConnCreateParams.outTag`]
member, in bytes.
- name: outTagFound
type: int
desc: |
Specifies if the connection created used the tag specified by the
[`dpiConnCreateParams.tag`] member. It is only filled in if the
connection was acquired from a session pool and a tag was initially
specified.
- name: shardingKeyColumns
type: dpiShardingKeyColumn *
desc: |
Specifies an array of [`dpiShardingKeyColumn`]
structures which are used to identify which database shard should be
connected to. The number of elements in the array is assumed to contain at
least [`dpiConnCreateParams.numShardingKeyColumns`] elements.
- name: numShardingKeyColumns
type: uint8_t
desc: |
Specifies the number of elements in the array of sharding key columns found
in the member [`dpiConnCreateParams.shardingKeyColumns`].
- name: superShardingKeyColumns
type: dpiShardingKeyColumn *
desc: |
Specifies an array of [`dpiShardingKeyColumn`]
structures which are used to identify which database shard should be
connected to. The number of elements in the array is assumed to contain at
least [`dpiConnCreateParams.numSuperShardingKeyColumns`] elements.
- name: numSuperShardingKeyColumns
type: uint8_t
desc: |
Specifies the number of elements in the array of sharding key columns found
in the member [`dpiConnCreateParams.superShardingKeyColumns`].
- name: outNewSession
type: int
desc: |
Specifies if the connection created was newly created by the session pool
and has never been acquired from the pool (1) or not (0). It is only filled
in if the connection was acquired from a session pool.
- name: dpiConnInfo
kind: struct
desc: |
This structure is used for passing information about a connection from ODPI-C.
It is used by the function [`dpiConn_getInfo()`].
members:
- name: dbDomain
type: const char *
desc: |
A pointer to the name of the Oracle Database Domain name associated with
the connection, encoded in the encoding used for CHAR data. This is the
same value returned by the SQL expression
`SELECT VALUE FROM V$PARAMETER WHERE NAME = 'db_domain'`.
- name: dbDomainLength
type: uint32_t
desc: |
Contains the length of the [`dpiConnInfo.dbDomain`] member, in bytes.
- name: dbName
type: const char *
desc: |
A pointer to the Oracle Database name associated with the connection,
encoded in the encoding used for CHAR data. This is the same value returned
by the SQL expression `SELECT NAME FROM V$DATABASE`. Note the values may
have different cases.
- name: dbNameLength
type: uint32_t
desc: |
Contains the length of the [`dpiConnInfo.dbName`] member, in bytes.
- name: instanceName
type: const char *
desc: |
A pointer to the Oracle Database instance name associated with the
connection, encoded in the encoding used for CHAR data. This is the same
value returned by the SQL expression
`SELECT SYS_CONTEXT('USERENV', 'INSTANCE_NAME') FROM DUAL`. Note the
values may have different cases.
- name: instanceNameLength
type: uint32_t
desc: |
Contains the length of the [`dpiConnInfo.instanceName`] member, in
bytes.
- name: serviceName
type: const char *
desc: |
A pointer to the Oracle Database service name associated with the
connection, encoded in the encoding used for CHAR data. This is the same
value returned by the SQL expression
`SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL`.
- name: serviceNameLength
type: uint32_t
desc: |
Contains the length of the [`dpiConnInfo.serviceName`] member, in
bytes.
- name: maxIdentifierLength
type: uint32_t
desc: |
Specifies the maximum length of identifiers (in bytes) supported by the
database to which the connection has been established. See [Database Object
Naming Rules](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-75337742-67FD-4EC0-985F-741C93D918DA). The value
may be 0, 30, or 128. The value 0 indicates the size cannot be reliably
determined by ODPI-C, which occurs when using Oracle Client libraries 12.1
(or older) and also connected to Oracle Database 12.2, or later.
- name: maxOpenCursors
type: uint32_t
desc: |
Specifies the maximum number of cursors that can be opened. This is the
same value returned by the SQL expression
`SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'`.
- name: serverType
type: uint8_t
desc: |
Specifies the type of server process used by the connection. This value
will be one of the values in the enumeration
[`dpiServerType`].
- name: dpiContextCreateParams
kind: struct
desc: |
This structure is used for specifying parameters when creating an ODPI-C
context by calling [`dpiContext_createWithParams()`].
members:
- name: defaultDriverName
type: const char *
hints:
type: c-string
desc: |
A null-terminated string defining the default driver name to use when
creating pools or standalone connections.
The standard is to set this value to `"<name> : <version>"`, where <name>
is the name of the driver and <version> is its version. There should be a
single space character before and after the colon.
This value is shown in database views that give information about
connections. For example, it is in the `CLIENT_DRIVER` column
of `V$SESSION_CONNECT_INFO`.
If this member is NULL, then the default value will be the value of
`DPI_DEFAULT_DRIVER_NAME` from [dpi.h](https://github.com/oracle/odpi/blob/main/include/dpi.h).
This member is propagated to the [`dpiCommonCreateParams.driverName`]
and [`dpiCommonCreateParams.driverNameLength`] members when the
function [`dpiContext_initCommonCreateParams()`] is called.
- name: defaultEncoding
type: const char *
hints:
type: c-string
desc: |
A null-terminated string defining the default encoding to use for all
string data (including NCHAR, NVARCHAR2 and NCLOB data) passed into or
returned from the database.
If this member is NULL, then the default value will be “UTF-8”. The Oracle
equivalent of this is “AL32UTF8”.
This member is propagated to the [`dpiCommonCreateParams.encoding`]
and [`dpiCommonCreateParams.nencoding`] members when the
function [`dpiContext_initCommonCreateParams()`] is called.
- name: loadErrorUrl
type: const char *
hints:
type: c-string
desc: |
A null-terminated UTF-8 encoded string defining the URL that should be
provided in the error message returned when the Oracle Client library
cannot be loaded. This URL should direct the user to the installation
instructions for the application or driver using ODPI-C. If this value is
NULL then the default ODPI-C URL is provided in the error message instead.
- name: oracleClientLibDir
type: const char *
hints:
type: c-string
encoding: ansi
desc: |
A null-terminated UTF-8 encoded string defining the location from which to
load the Oracle Client library. If this value is not NULL it is the only
location that is searched; otherwise, if this value is NULL the Oracle
Client library is searched for in the usual fashion as noted in
[`Oracle Client Library Loading`]. Also see that
section for limitations on using this member.
- name: oracleClientConfigDir
type: const char *
hints:
type: c-string
encoding: ansi
desc: |
A null-terminated UTF-8 encoded string defining the location the Oracle
client library will search for configuration files. This is equivalent to
setting the environment variable `TNS_ADMIN`. If this value is not NULL,
it overrides any value set by the environment variable `TNS_ADMIN`.
- name: sodaUseJsonDesc
type: int
hints:
type: boolean
desc: |
A boolean value indicating whether or not to use JSON descriptors with
SODA. This requires Oracle Client 23.4 or higher and setting this value to
1 in earlier versions will simply be ignored. Once a call to
[`dpiContext_createWithParams()`] is made with this structure, this
member will be cleared if JSON descriptors cannot be used.
- name: useJsonId
type: int
hints:
type: boolean
desc: |
A boolean value indicating whether or not to treat JSON ID values
distinctly from other binary data.
- name: dpiData
kind: struct
desc: |
This structure is used for passing data to and from the database in variables
and for getting and setting object attributes and collection values. The data
that is stored in the structure will remain valid for differing durations
depending on the source of the data.
For data that is supplied by the application (for passing data into the
database) the duration of the data is under the control of the application
itself and the application should ensure that it remains valid for as long as
any call that uses that data.
For data that is supplied by the database in a variable (either fetching data
or binding data out) the data will remain valid as long as a reference to the
variable is retained; the contents of the data may change however if a
statement to which the variable is bound or defined is executed or fetched
again.
For data that is acquired from an object attribute or a collection element the
data will remain valid as long as a reference to the object is retained; the
contents of the data may change however if the object is modified.
members:
- name: isNull
type: int
desc: |
Specifies if the value refers to a null value (1) or not (0).
- name: value
type: dpiDataBuffer
desc: |
Specifies the value that is being passed or received. It is only examined
when the member [`dpiData.isNull`] is 0. It is a union of type
[`dpiDataBuffer`].
functions:
- name: dpiData_getBool
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_BOOLEAN.
round_trips: No
return: int
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getBytes
desc: |
Returns a pointer to the value of the data when the native type is
DPI_NATIVE_TYPE_BYTES.
round_trips: No
return: dpiBytes *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getDouble
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_DOUBLE.
round_trips: No
return: double
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getFloat
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_FLOAT.
round_trips: No
return: float
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getInt64
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_INT64.
round_trips: No
return: int64_t
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getIntervalDS
desc: |
Returns a pointer to the value of the data when the native type is
DPI_NATIVE_TYPE_INTERVAL_DS.
round_trips: No
return: dpiIntervalDS *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getIntervalYM
desc: |
Returns a pointer to the value of the data when the native type is
DPI_NATIVE_TYPE_INTERVAL_YM.
round_trips: No
return: dpiIntervalYM *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getIsNull
desc: |
Returns whether the data refers to a null value (1) or not (0).
round_trips: No
return: int
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the null indicator.
- name: dpiData_getLOB
desc: |
Returns the value of the data when the native type is DPI_NATIVE_TYPE_LOB.
round_trips: No
return: dpiLob *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getJson
desc: |
Returns the value of the data when the native type is DPI_NATIVE_TYPE_JSON.
round_trips: No
return: dpiJson *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getJsonArray
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_JSON_ARRAY.
round_trips: No
return: dpiJsonArray *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getJsonObject
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_JSON_OBJECT.
round_trips: No
return: dpiJsonObject *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getObject
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_OBJECT.
round_trips: No
return: dpiObject *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getStmt
desc: |
Returns the value of the data when the native type is DPI_NATIVE_TYPE_STMT.
round_trips: No
return: dpiStmt *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getTimestamp
desc: |
Returns a pointer to the value of the data when the native type is
DPI_NATIVE_TYPE_TIMESTAMP.
round_trips: No
return: dpiTimestamp *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getUint64
desc: |
Returns the value of the data when the native type is
DPI_NATIVE_TYPE_UINT64.
round_trips: No
return: uint64_t
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_getVector
desc: |
Returns the value of the data when the native type is DPI_NATIVE_TYPE_VECTOR.
round_trips: No
return: dpiVector *
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure from which to
get the value.
- name: dpiData_setBool
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_BOOLEAN.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: value
type: int
mode: IN
desc: |
The value to set.
- name: dpiData_setBytes
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_BYTES.
Do *not* use this function when setting data for variables. Instead, use
the function [`dpiVar_setFromBytes()`].
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: ptr
type: char *
mode: IN
desc: |
The byte string containing the data to set.
- name: length
type: uint32_t
mode: IN
desc: |
The length of the byte string.
- name: dpiData_setDouble
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_DOUBLE.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: value
type: double
mode: IN
desc: |
The value to set.
- name: dpiData_setFloat
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_FLOAT.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: value
type: float
mode: IN
desc: |
The value to set.
- name: dpiData_setInt64
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_INT64.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: value
type: int64_t
mode: IN
desc: |
The value to set.
- name: dpiData_setIntervalDS
desc: |
Sets the value of the data when the native type is
DPI_NATIVE_TYPE_INTERVAL_DS.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: days
type: int32_t
mode: IN
desc: |
The number of days to set in the value.
- name: hours
type: int32_t
mode: IN
desc: |
The number of hours to set in the value.
- name: minutes
type: int32_t
mode: IN
desc: |
The number of minutes to set in the value.
- name: seconds
type: int32_t
mode: IN
desc: |
The number of seconds to set in the value.
- name: fseconds
type: int32_t
mode: IN
desc: |
The number of fractional seconds to set in the value.
- name: dpiData_setIntervalYM
desc: |
Sets the value of the data when the native type is
DPI_NATIVE_TYPE_INTERVAL_YM.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: years
type: int32_t
mode: IN
desc: |
The number of years to set in the value.
- name: months
type: int32_t
mode: IN
desc: |
The number of months to set in the value.
- name: dpiData_setLOB
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_LOB.
Do *not* use this function when setting data for variables. Instead, use
the function [`dpiVar_setFromLob()`].
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: lob
type: dpiLob *
mode: IN
desc: |
A reference to the LOB to assign to the value.
- name: dpiData_setNull
desc: |
Sets the value of the data to be the null value.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: dpiData_setObject
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_OBJECT.
Do *not* use this function when setting data for variables. Instead, use
the function [`dpiVar_setFromObject()`].
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: obj
type: dpiObject *
mode: IN
desc: |
A reference to the object to assign to the value.
- name: dpiData_setStmt
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_STMT.
Do *not* use this function when setting data for variables. Instead, use
the function [`dpiVar_setFromStmt()`].
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: stmt
type: dpiStmt *
mode: IN
desc: |
A reference to the statement to assign to the value.
- name: dpiData_setTimestamp
desc: |
Sets the value of the data when the native type is
DPI_NATIVE_TYPE_TIMESTAMP.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: year
type: int16_t
mode: IN
desc: |
The year to set in the value.
- name: month
type: uint8_t
mode: IN
desc: |
The month to set in the value.
- name: day
type: uint8_t
mode: IN
desc: |
The day to set in the value.
- name: hour
type: uint8_t
mode: IN
desc: |
The hour to set in the value.
- name: minute
type: uint8_t
mode: IN
desc: |
The minute to set in the value.
- name: second
type: uint8_t
mode: IN
desc: |
The second to set in the value.
- name: fsecond
type: uint32_t
mode: IN
desc: |
The fractional seconds to set in the value.
- name: tzHourOffset
type: int8_t
mode: IN
desc: |
The time zone hour offset to set in the value.
- name: tzMinuteOffset
type: int8_t
mode: IN
desc: |
The time zone minute offset to set in the value.
- name: dpiData_setUint64
desc: |
Sets the value of the data when the native type is DPI_NATIVE_TYPE_UINT64.
round_trips: No
return: void
params:
- name: data
type: dpiData *
mode: IN
desc: |
A pointer to the [`dpiData`] structure to set.
- name: value
type: uint64_t
mode: IN
desc: |
The value to set.
- name: dpiDataTypeInfo
kind: struct
desc: |
This structure is used for passing data type information from ODPI-C. It is
part of the structures [`dpiObjectAttrInfo`],
[`dpiObjectTypeInfo`] and
[`dpiQueryInfo`].
members:
- name: oracleTypeNum
type: dpiOracleTypeNum
desc: |
Specifies the type of the data. It will be one of the values from the
enumeration [`dpiOracleTypeNum`], or 0 if the type
is not supported by ODPI-C.
- name: defaultNativeTypeNum
type: dpiNativeTypeNum
desc: |
Specifies the default native type for the data. It will be one of the
values from the enumeration [`dpiNativeTypeNum`], or 0
if the type is not supported by ODPI-C.
- name: ociTypeCode
type: uint16_t
desc: |
Specifies the OCI type code for the data, which can be useful if the type
is not supported by ODPI-C.
- name: dbSizeInBytes
type: uint32_t
desc: |
Specifies the size in bytes (from the database’s perspective) of the data.
This value is only populated for strings and binary data. For all other
data the value is zero.
- name: clientSizeInBytes
type: uint32_t
desc: |
Specifies the size in bytes (from the client’s perspective) of the data.
This value is only populated for strings and binary data. For all other
data the value is zero.
- name: sizeInChars
type: uint32_t
desc: |
Specifies the size in characters of the data. This value is only populated
for string data. For all other data the value is zero.
- name: precision
type: int16_t
desc: |
Specifies the precision of the data. This value is only populated for
numeric and interval data. For all other data the value is zero.
- name: scale
type: int8_t
desc: |
Specifies the scale of the data. This value is only populated for numeric
data. For all other data the value is zero.
- name: fsPrecision
type: uint8_t
desc: |
Specifies the fractional seconds precision of the data. This value is only
populated for timestamp and interval day to second data. For all other
data the value is zero.
- name: objectType
type: dpiObjectType *
desc: |
Specifies a reference to the type of the object. This value is only
populated for named type data. For all other data the value is NULL. This
reference is owned by the object attribute, object type or statement and a
call to [`dpiObjectType_addRef()`] must be made if the reference is
going to be used beyond the lifetime of the owning object.
- name: isJson
type: int
desc: |
Specifies if the data contains JSON. This is set to true when columns are
fetched that are of type `DPI_ORACLE_TYPE_JSON` or if the column fetched
has the check constraint “IS JSON” enabled.
- name: domainSchema
type: const char *
desc: |
Specifies the schema of the [SQL domain](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41)
associated with the column which is being queried, as a byte string in the
encoding used for CHAR data.
- name: domainSchemaLength
type: uint32_t
desc: |
Specifies the length of the [`dpiDataTypeInfo.domainSchema`] member,
in bytes.
- name: domainName
type: const char *
desc: |
Specifies the name of the [SQL domain](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41)
associated with the column which is being queried, as a byte string in the
encoding used for CHAR data.
- name: domainNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiDataTypeInfo.domainName`] member,
in bytes.
- name: numAnnotations
type: uint32_t
desc: |
Specifies the number of annotations associated with the column which is
being fetched. It is the length of [`dpiDataTypeInfo.annotations`].
- name: annotations
type: dpiAnnotation *
desc: |
Specifies an array of structures of type
[`dpiAnnotation`]. The length of the array is specified
in the [`dpiDataTypeInfo.numAnnotations`] member.
- name: isOson
type: int
desc: |
Specifies if the data contains binary encoded OSON. This is set to true
when columns are fetched that have the check constraint “IS JSON FORMAT
OSON” enabled.
- name: vectorDimensions
type: uint32_t
desc: |
Specifies the number of dimensions that a vector column contains. This
value will be 0 if [`dpiDataTypeInfo.oracleTypeNum`] is not
DPI_ORACLE_TYPE_VECTOR or the vector columns uses a flexible number of
dimensions.
- name: vectorFormat
type: uint8_t
desc: |
Specifies the storage format of the vector column. This value will be 0 if
[`dpiDataTypeInfo.oracleTypeNum`] is not DPI_ORACLE_TYPE_VECTOR or
the vector column uses a flexible storage format. If a value is set it will
be one of the values in the eneumeration
[`dpiVectorFormat`].
- name: vectorFlags
type: uint8_t
desc: |
Specifies flags for the vector column. This value will be 0 if
[`dpiDataTypeInfo.oracleTypeNum`] is not DPI_ORACLE_TYPE_VECTOR or
no flags have been set. If flags have been set, they will be one or more of
the values in the enumeration [`dpiVectorFlags`], or’ed
together.
- name: dpiEncodingInfo
kind: struct
desc: |
This structure is used for transferring encoding information from ODPI-C. All of
the information here remains valid as long as a reference is held to the
standalone connection (by calling [`dpiConn_getEncodingInfo()`]) or session
pool (by calling [`dpiPool_getEncodingInfo()`]) from which the information
was taken.
members:
- name: encoding
type: const char *
desc: |
The encoding used for CHAR data, as a null-terminated ASCII string.
- name: maxBytesPerCharacter
type: int32_t
desc: |
The maximum number of bytes required for each character in the encoding
used for CHAR data. This value is used when calculating the size of
buffers required when lengths in characters are provided.
- name: nencoding
type: const char *
desc: |
The encoding used for NCHAR data, as a null-terminated ASCII string.
- name: nmaxBytesPerCharacter
type: int32_t
desc: |
The maximum number of bytes required for each character in the encoding
used for NCHAR data. Since this information is not directly available
from Oracle it is only accurate if the encodings used for CHAR and NCHAR
data are identical or one of ASCII or UTF-8; otherwise a value of 4 is
assumed. This value is used when calculating the size of buffers required
when lengths in characters are provided.
- name: dpiErrorInfo
kind: struct
desc: |
This structure is used for transferring error information from ODPI-C. All of the
strings referenced here may become invalid as soon as the next ODPI-C call is
made.
members:
- name: code
type: int32_t
desc: |
The OCI error code if an OCI error has taken place. If no OCI error has
taken place the value is 0.
- name: offset16
type: uint16_t
desc: |
The 16-bit value of [`dpiErrorInfo.offset`] retained for backwards
compatibility. This member will be removed at some point in the future.
- name: message
type: const char *
desc: |
The error message as a byte string in the encoding specified by the
[`dpiErrorInfo.encoding`] member.
- name: messageLength
type: uint32_t
desc: |
The length of the [`dpiErrorInfo.message`] member, in bytes.
- name: encoding
type: const char *
desc: |
The encoding in which the error message is encoded as a null-terminated
string. For OCI errors this is the CHAR encoding used when the connection
was created. For ODPI-C specific errors this is UTF-8.
- name: fnName
type: const char *
desc: |
The public ODPI-C function name which was called in which the error took
place. This is a null-terminated ASCII string.
- name: action
type: const char *
desc: |
The internal action that was being performed when the error took place.
This is a null-terminated ASCII string.
- name: sqlState
type: const char *
desc: |
The SQLSTATE code associated with the error. This is a 5 character
null-terminated string.
- name: isRecoverable
type: int
desc: |
A boolean value indicating if the error is recoverable. This member always
has a value of 0 unless both client and server are at release 12.1 or
higher.
- name: isWarning
type: int
desc: |
A boolean value indicating if the error information is for a warning
returned by Oracle that does not prevent the requested operation from
proceeding. Examples include connecting to the database with a password
that is about to expire (within the grace period) and creating a stored
procedure with compilation errors.
- name: offset
type: uint32_t
desc: |
The parse error offset (in bytes) when executing a statement or the row
offset when performing bulk operations or fetching batch error information.
If neither of these cases are true, the value is 0.
- name: dpiIntervalDS
kind: struct
desc: |
This structure is used for passing interval (days to seconds) data to and from
the database in the structure [`dpiData`].
members:
- name: days
type: int32_t
desc: |
Specifies the number of days in the interval.
- name: hours
type: int32_t
desc: |
Specifies the number of hours in the interval.
- name: minutes
type: int32_t
desc: |
Specifies the number of minutes in the interval.
- name: seconds
type: int32_t
desc: |
Specifies the number of seconds in the interval.
- name: fseconds
type: int32_t
desc: |
Specifies the number of fractional seconds in the interval (in
nanoseconds).
- name: dpiIntervalYM
kind: struct
desc: |
This structure is used for passing interval (years to months) data to and from
the database in the structure [`dpiData`].
members:
- name: years
type: int32_t
desc: |
Specifies the number of years in the interval.
- name: months
type: int32_t
desc: |
Specifies the number of months in the interval.
- name: dpiJsonArray
kind: struct
desc: |
This structure is used for passing JSON objects to and from the database.
members:
- name: numElements
type: uint32_t
desc: |
Specifies the number of elements that are found in the JSON array. This
also identifies the number of elements in each of the remaining arrays.
- name: elements
type: dpiJsonNode *
desc: |
Specifies an array of JSON nodes that are the values of the elements found
in the JSON array. Each of these is a structure of type
[`dpiJsonNode`].
- name: elementValues
type: dpiDataBuffer *
desc: |
Specifies an array of buffers that contain the data for the values of the
elements found in the JSON array. This member should not be used directly.
Instead, the [`dpiJsonNode.value`] member of the corresponding node
in the member [`dpiJsonArray.elements`] should be used.
- name: dpiJsonNode
kind: struct
desc: |
This structure is used for passing JSON node data to and from the database in
the structure [`dpiData`]. Nodes can consist of scalar values,
objects, or arrays.
members:
- name: oracleTypeNum
type: dpiOracleTypeNum
desc: |
The Oracle type of the data that is stored in the node. It will be one of
the values from the enumeration [`dpiOracleTypeNum`].
- name: nativeTypeNum
type: dpiNativeTypeNum
desc: |
The native type of the data that is stored in the node. It will be one of
the values from the enumeration [`dpiNativeTypeNum`].
- name: value
type: dpiDataBuffer *
desc: |
The value that is stored in the node. It is a union of type
[`dpiDataBuffer`].
- name: dpiJsonObject
kind: struct
desc: |
This structure is used for passing JSON objects to and from the database.
members:
- name: numFields
type: uint32_t
desc: |
Specifies the number of fields that are found in the JSON object. This also
identifies the number of elements in each of the remaining arrays.
- name: fieldNames
type: char **
desc: |
Specifies an array of field names that are found in the JSON object. Each
element is a byte string encoded in UTF-8. The length of each byte string
is found in the [`dpiJsonObject.fieldNameLengths`] member.
- name: fieldNameLengths
type: uint32_t *
desc: |
Specifies an array of lengths for the names of the fields found in the JSON
object.
- name: fields
type: dpiJsonNode *
desc: |
Specifies an array of JSON nodes that are the values of the fields found in
the JSON object. Each of these is a structure of type
[`dpiJsonNode`].
- name: fieldValues
type: dpiDataBuffer *
desc: |
Specifies an array of buffers that contain the data for the values of the
fields found in the JSON object. This member should not be used directly.
Instead, the [`dpiJsonNode.value`] member of the corresponding node
in the member [`dpiJsonObject.fields`] should be used.
- name: dpiMsgRecipient
kind: struct
desc: |
This structure is used to set recipients for an AQ message.
A list of recipient names can be associated with a message at the time
a message is enqueued. This allows a limited set of recipients to
dequeue each message. The recipient list associated with the message
overrides the queue subscriber list, if there is one. The recipient
names need not be in the subscriber list but can be, if desired.
To dequeue a message, the consumername attribute can be set to one of
the recipient names. The original message recipient list is not
available on dequeued messages. All recipients have to dequeue a
message before it gets removed from the queue.
Subscribing to a queue is like subscribing to a magazine: each
subscriber can dequeue all the messages placed into a specific queue,
just as each magazine subscriber has access to all its articles. Being
a recipient, however, is like getting a letter: each recipient is a
designated target of a particular message.
members:
- name: name
type: const char *
desc: |
Specifies the name of the message recipient, in the encoding used for
CHAR data.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiMsgRecipient.name`] member, in
bytes.
- name: dpiObjectAttrInfo
kind: struct
desc: |
This structure is used for passing information about an object type from ODPI-C.
It is used by the function [`dpiObjectAttr_getInfo()`].
members:
- name: name
type: const char *
desc: |
Specifies the name of the attribute, as a byte string in the encoding used
for CHAR data.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiObjectAttrInfo.name`] member, in
bytes.
- name: typeInfo
type: dpiDataTypeInfo
desc: |
Specifies the type of data of the attribute. It is a structure of type
[`dpiDataTypeInfo`].
- name: dpiObjectTypeInfo
kind: struct
desc: |
This structure is used for passing information about an object type from ODPI-C.
It is used by the function [`dpiObjectType_getInfo()`].
members:
- name: schema
type: const char *
desc: |
Specifies the schema which owns the object type, as a byte string in the
encoding used for CHAR data.
- name: schemaLength
type: uint32_t
desc: |
Specifies the length of the [`dpiObjectTypeInfo.schema`] member, in
bytes.
- name: name
type: const char *
desc: |
Specifies the name of the object type, as a byte string in the encoding
used for CHAR data.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiObjectTypeInfo.name`] member, in
bytes.
- name: isCollection
type: int
desc: |
Specifies if the object type is a collection (1) or not (0).
- name: elementTypeInfo
type: dpiDataTypeInfo
desc: |
Specifies the type of data of the elements in the collection. It is a
structure of type [`dpiDataTypeInfo`] which is only
valid if the object type is a collection.
- name: numAttributes
type: uint16_t
desc: |
Specifies the number of attributes that the object type has.
- name: packageName
type: const char *
desc: |
Specifies the name of the name of the package for a PL/SQL type, as a byte
string in the encoding used for CHAR data. If the type is not a PL/SQL
type, this value is NULL.
- name: packageNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiObjectTypeInfo.packageName`] member,
in bytes.
- name: dpiPoolCreateParams
kind: struct
desc: |
This structure is used for creating session pools, which can in turn be used to
create connections that are acquired from that session pool. All members are
initialized to default values using the
[`dpiContext_initPoolCreateParams()`] function.
members:
- name: minSessions
type: uint32_t
desc: |
Specifies the minimum number of sessions to be created by the session pool.
This value is ignored if the [`dpiPoolCreateParams.homogeneous`]
member has a value of 0. The default value is 1.
- name: maxSessions
type: uint32_t
desc: |
Specifies the maximum number of sessions that can be created by the session
pool. Values of 1 and higher are acceptable. The default value is 1.
- name: sessionIncrement
type: uint32_t
desc: |
Specifies the number of sessions that will be created by the session pool
when more sessions are required and the number of sessions is less than
the maximum allowed. This value is ignored if the
[`dpiPoolCreateParams.homogeneous`] member has a value of 0. This
value added to the [`dpiPoolCreateParams.minSessions`] member value
must not exceed the [`dpiPoolCreateParams.maxSessions`] member value.
The default value is 0.
- name: pingInterval
type: int
desc: |
Specifies the number of seconds since a connection has last been used
before a ping will be performed to verify that the connection is still
valid. A negative value disables this check. The default value is 60.
- name: pingTimeout
type: int
desc: |
Specifies the number of milliseconds to wait when performing a ping to
verify the connection is still valid before the connection is considered
invalid and is dropped. The default value is 5000 (5 seconds).
- name: homogeneous
type: int
desc: |
Specifies whether the pool is homogeneous or not. In a homogeneous pool all
connections use the same credentials whereas in a heterogeneous pool other
credentials are permitted. The default value is 1.
- name: externalAuth
type: int
desc: |
Specifies whether external authentication should be used to create the
sessions in the pool. If this value is 0, the user name and password values
must be specified in the call to [`dpiPool_create()`]; otherwise, the
user name and password values must be zero length or NULL. The default
value is 0. External authentication cannot be used with homogeneous pools.
- name: getMode
type: dpiPoolGetMode
desc: |
Specifies the mode to use when sessions are acquired from the pool. It is
expected to be one of the values from the enumeration
[`dpiPoolGetMode`]. The default value is
DPI_MODE_POOL_GET_NOWAIT. This value can be set after the pool has been
created using the function [`dpiPool_setGetMode()`] and acquired using
the function [`dpiPool_getGetMode()`].
- name: outPoolName
type: const char *
desc: |
This member is populated upon successful creation of a pool using the
function [`dpiPool_create()`]. It is a byte string in the encoding
used for CHAR data. Any value specified prior to creating the session pool
is ignored.
- name: outPoolNameLength
type: uint32_t
desc: |
This member is populated upon successful creation of a pool using the
function [`dpiPool_create()`]. It is the length of the
[`dpiPoolCreateParams.outPoolName`] member, in bytes. Any value
specified prior to creating the session pool is ignored.
- name: timeout
type: uint32_t
desc: |
Specifies the length of time (in seconds) after which idle sessions in the
pool are terminated. Note that termination only occurs when the pool is
accessed. The default value is 0 which means that no idle sessions are
terminated. This value can be set after the pool has been created using the
function [`dpiPool_setTimeout()`] and acquired using the function
[`dpiPool_getTimeout()`].
- name: waitTimeout
type: uint32_t
desc: |
Specifies the length of time (in milliseconds) that the caller should wait
for a session to become available in the pool before returning with an
error. This value is only used if the
[`dpiPoolCreateParams.getMode`] member is set to the value
DPI_MODE_POOL_GET_TIMEDWAIT. The default value is 0. This value can be set
after the pool has been created using the function
[`dpiPool_setWaitTimeout()`] and acquired using the function
[`dpiPool_getWaitTimeout()`].
- name: maxLifetimeSession
type: uint32_t
desc: |
Specifies the maximum length of time (in seconds) a pooled session may
exist. Sessions in use will not be closed. They become candidates for
termination only when they are released back to the pool and have existed
for longer than maxLifetimeSession seconds. Session termination only occurs
when the pool is accessed. The default value is 0 which means that there is
no maximum length of time that a pooled session may exist. This value can
be set after the pool has been created using the function
[`dpiPool_setMaxLifetimeSession()`] and acquired using the function
[`dpiPool_getMaxLifetimeSession()`].
- name: plsqlFixupCallback
type: const char *
desc: |
Specifies the name of a PL/SQL procedure in the format
*schema.package.callback_proc* which will be called when a session is
checked out from the pool and the requested tag doesn’t match the actual
tag assigned to the session. The procedure accepts the desired
and actual tags as parameters and it is the responsibility of the procedure
to ensure that the session matches the desired state upon completion. See
the [OCI documentation](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B853A020-752F-494A-8D88-D0396EF57177) for more
information. The value is expected to be a byte string in the encoding used
for CHAR data. This functionality is only available when Oracle Client
is at version 12.2 and higher.
- name: plsqlFixupCallbackLength
type: uint32_t
desc: |
Specifies the length of the PL/SQL fixup callback, in bytes.
- name: maxSessionsPerShard
type: uint32_t
desc: |
Specifies the maximum number of sessions that can be created by the session
pool for each shard in a sharded database. Set this attribute to a value
other than zero to ensure that the pool is balanced towards each shard. A
value of zero will not set any maximum number of sessions for each shard.
If the Oracle client library version is less than 18.3, this value is
ignored.
- name: accessTokenCallback
type: dpiAccessTokenCallback
desc: |
The callback function which will get called by the connection pool if the
pool needs to expand and create new connections but the current
authentication token has expired.
The function should get a new authentication token and then set
[`dpiAccessToken.token`] and [`dpiAccessToken.privateKey`]
in the accessToken argument. The authentication token can be generated by
invoking the Oracle Cloud Infrastructure (OCI) Command Line Interface
(CLI).
The function should return DPI_SUCCESS for success and DPI_FAILURE
for failure. Returning DPI_FAILURE will cause the connection to fail
and return ORA-01017 to the application.
The callback accepts the following arguments:
- name: accessTokenCallbackContext
type: void *
desc: |
Specifies the value that will be used as the first argument to the callback
specified in the [`dpiPoolCreateParams.accessTokenCallback`]
member. The default value is NULL.
- name: dpiQueryInfo
kind: struct
desc: |
This structure is used for passing query metadata from ODPI-C. It is populated
by the function [`dpiStmt_getQueryInfo()`]. All values remain valid as long
as a reference is held to the statement and the statement is not re-executed or
closed.
members:
- name: name
type: const char *
desc: |
Specifies the name of the column which is being queried, as a byte string
in the encoding used for CHAR data.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiQueryInfo.name`] member, in bytes.
- name: typeInfo
type: dpiDataTypeInfo
desc: |
Specifies the type of data of the column that is being queried. It is a
structure of type [`dpiDataTypeInfo`].
- name: nullOk
type: int
desc: |
Specifies if the data that is being queried may return null values (1) or
not (0).
- name: dpiShardingKeyColumn
kind: struct
desc: |
This structure is used for passing sharding key column values to the database.
It is part of the structure [`dpiConnCreateParams`].
members:
- name: oracleTypeNum
type: dpiOracleTypeNum
desc: |
Specifies the Oracle type of the column which makes up the sharding key. It
is expected to be one of the values from the enumeration
[`dpiOracleTypeNum`] but currently only the value
DPI_ORACLE_TYPE_VARCHAR is supported.
- name: nativeTypeNum
type: dpiNativeTypeNum
desc: |
Specifies the native type of the column which makes up the sharding key. It
is expected to be one of the values from the enumeration
[`dpiNativeTypeNum`] but currently only the value
DPI_NATIVE_TYPE_BYTES is supported.
- name: value
type: dpiDataBuffer
desc: |
Specifies the value of the column which makes up the sharding key. It is a
union of type [`dpiDataBuffer`] and the member of the
union that is set must correspond to the value of the member
[`dpiShardingKeyColumn.nativeTypeNum`].
- name: dpiSodaOperOptions
kind: struct
desc: |
This structure is used for passing search criteria to a number of SODA
operations. It is initialized using the function
[`dpiContext_initSodaOperOptions()`] and used by the functions
[`dpiSodaColl_find()`], [`dpiSodaColl_findOne()`],
[`dpiSodaColl_getDocCount()`], [`dpiSodaColl_remove()`]
and [`dpiSodaColl_replaceOne()`].
members:
- name: numKeys
type: uint32_t
desc: |
Specifies the number of elements in the members
[`dpiSodaOperOptions.keys`] and
[`dpiSodaOperOptions.keyLengths`].
- name: keys
type: const char **
desc: |
Specifies an array of key values which documents in the collection must
have in order to be processed by the operation. The length of this array
is defined by the member [`dpiSodaOperOptions.numKeys`].
- name: keyLengths
type: uint32_t *
desc: |
Specifies an array of key length values. Each element corresponds to the
length of the key (in bytes) found in the member
[`dpiSodaOperOptions.keys`] at the same element index. The length of
this array is defined by the member [`dpiSodaOperOptions.numKeys`].
- name: key
type: const char *
desc: |
Specifies the key which the document must have in order to be processed by
the operation.
- name: keyLength
type: uint32_t
desc: |
Specifies the length of the member [`dpiSodaOperOptions.key`], in
bytes.
- name: version
type: const char *
desc: |
Specifies the document version that documents must have in order to be
processed by the operation. This is typically used in conjunction with
[`dpiSodaOperOptions.key`] and allows for opportunistic locking,
so that operations do not affect a document that someone else has already
modified.
- name: versionLength
type: uint32_t
desc: |
Specifies the length of the member [`dpiSodaOperOptions.version`],
in bytes.
- name: filter
type: const char *
desc: |
Specifies a filter value which limits the documents processed by the
operation. See [Overview of SODA Filter Specifications (QBEs)](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-CB09C4E3-BBB1-40DC-88A8-8417821B0FBE).
- name: filterLength
type: uint32_t
desc: |
Specifies the length of the member [`dpiSodaOperOptions.filter`],
in bytes.
- name: skip
type: uint32_t
desc: |
Specifies the number of documents to skip before processing documents in
the collection. A value of 0 will result in no documents being skipped.
- name: limit
type: uint32_t
desc: |
Specifies the maximum number of documents to process in the collection. A
value of 0 means no limit is enforced.
- name: fetchArraySize
type: uint32_t
desc: |
Specifies the number of documents that will be fetched at one time from a
SODA collection. Increasing this value reduces the number of round-trips to
the database but increases the amount of memory allocated. A value of 0
means that the default value (100) is used. This member is only supported
in Oracle Client 19.5 and higher.
- name: hint
type: const char *
desc: |
Specifies a hint that will be passed through to the SODA operation. These
hints are the same as the hints used for normal SQL operations but without
the enclosing comment characters. This member is only supported in Oracle
Client 21.3 and higher (also available in Oracle Client 19 from 19.11).
- name: hintLength
type: uint32_t
desc: |
Specifies the length of the member [`dpiSodaOperOptions.hint`],
in bytes. This member is only supported in Oracle Client 21.3 and higher
(also available in Oracle Client 19 from 19.11).
- name: lock
type: int
desc: |
Specifies whether the documents fetched from the collection should be
locked (equivalent to SQL “select for update”). The next commit or
rollback on the connection made after the operation is performed will
“unlock” the documents. Ensure that the flag
`DPI_SODA_FLAGS_ATOMIC_COMMIT` is not used for the operation as otherwise
the lock will be removed immediately.
This member should only be used with read operations (other than
[`dpiSodaColl_getDocCount()`]) and should not be used in conjunction
with the [`dpiSodaOperOptions.skip`] and
[`dpiSodaOperOptions.limit`] members.
If this member is specified in conjunction with a write operation the value
is ignored.
This member is only supported in Oracle Client 21.3 and higher (also
available in Oracle Client 19 from 19.11).
- name: dpiStmtInfo
kind: struct
desc: |
This structure is used for passing information about a statement from ODPI-C. It
is used by the function [`dpiStmt_getInfo()`].
members:
- name: isQuery
type: int
desc: |
Specifies if the statement refers to a query (1) or not (0).
- name: isPLSQL
type: int
desc: |
Specifies if the statement refers to a PL/SQL block (1) or not (0).
- name: isDDL
type: int
desc: |
Specifies if the statement refers to DDL (data definition language) such
as creating a table (1) or not (0).
- name: isDML
type: int
desc: |
Specifies if the statement refers to DML (data manipulation language) such
as inserting, updating and deleting (1) or not (0).
- name: statementType
type: dpiStatementType
desc: |
Specifies the type of statement that has been prepared. The members
[`dpiStmtInfo.isQuery`], [`dpiStmtInfo.isPLSQL`],
[`dpiStmtInfo.isDDL`] and [`dpiStmtInfo.isDML`] are all
categorizations of this value. It will be one of the values from the
enumeration [`dpiStatementType`].
- name: isReturning
type: int
desc: |
Specifies if the statement has a returning clause in it (1) or not (0).
- name: dpiStringList
kind: struct
desc: |
This structure is used for receiving a list of strings from such functions as
[`dpiSodaDb_getCollectionNames()`] and [`dpiSodaColl_listIndexes()`].
The memory referenced by this structure should be freed by the function
[`dpiContext_freeStringList()`] and should not be manipulated directly.
members:
- name: numStrings
type: uint32_t
desc: |
Specifies the number of elements in the strings and stringLengths arrays.
- name: strings
type: const char **
desc: |
Specifies an array of pointers to strings. The length of this array is
specified by the numStrings attribute.
- name: stringLengths
type: uint32_t *
desc: |
Specifies an array of lengths. Each element in this array is the length of
the string found in the corresponding element in the strings array, in
bytes. The length of this array is specified by the numStrings attribute.
- name: dpiSubscrCreateParams
kind: struct
desc: |
This structure is used for creating subscriptions to messages sent for object
change notification, query change notification or advanced queuing. All members
are initialized to default values using the
[`dpiContext_initSubscrCreateParams()`] function.
members:
- name: subscrNamespace
type: dpiSubscrNamespace
desc: |
Specifies the namespace in which the subscription is created. It is
expected to be one of the values from the enumeration
[`dpiSubscrNamespace`]. The default value is
DPI_SUBSCR_NAMESPACE_DBCHANGE.
- name: protocol
type: dpiSubscrProtocol
desc: |
Specifies the protocol used for sending notifications for the subscription.
It is expected to be one of the values from the enumeration
[`dpiSubscrProtocol`]. The default value is
DPI_SUBSCR_PROTO_CALLBACK.
- name: qos
type: dpiSubscrQOS
desc: |
Specifies the quality of service flags to use with the subscription. It is
expected to be one or more of the values from the enumeration
[`dpiSubscrQOS`], OR’ed together. The default value is to
have no flags set.
- name: operations
type: dpiOpCode
desc: |
Specifies which operations on the registered tables or queries should
result in notifications. It is expected to be one or more of the values
from the enumeration [`dpiOpCode`], OR’ed together. The
default value is DPI_OPCODE_ALL_OPS.
- name: portNumber
type: uint32_t
desc: |
Specifies the port number on which to receive notifications. The default
value is 0, which means that a port number will be selected by the Oracle
client.
- name: timeout
type: uint32_t
desc: |
Specifies the length of time, in seconds, before the subscription is
unregistered. If the value is 0, the subscription remains active until
explicitly unregistered. The default value is 0.
- name: name
type: const char *
desc: |
Specifies the name of the subscription, as a byte string in the encoding
used for CHAR data. This name must be consistent with the namespace
identified in the [`dpiSubscrCreateParams.subscrNamespace`] member.
The default value is NULL.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrCreateParams.name`] member, in
bytes. The default value is 0.
- name: callback
type: dpiSubscrCallback
desc: |
Specifies the callback that will be called when a notification is sent to
the subscription, if the [`dpiSubscrCreateParams.protocol`] member
is set to DPI_SUBSCR_PROTO_CALLBACK. The callback accepts the following
arguments:
The default value is NULL. If a callback is specified and a notification is
sent, this will be performed on a separate thread. If database operations
are going to take place, ensure that the create mode
DPI_MODE_CREATE_THREADED is set in the structure
[`dpiCommonCreateParams`] when creating the
session pool or standalone connection that will be used in this callback.
- name: callbackContext
type: void *
desc: |
Specifies the value that will be used as the first argument to the callback
specified in the [`dpiSubscrCreateParams.callback`] member. The
default value is NULL.
- name: recipientName
type: const char *
desc: |
Specifies the name of the recipient to which notifications are sent when
the [`dpiSubscrCreateParams.protocol`] member is not set to
DPI_SUBSCR_PROTO_CALLBACK. The value is expected to be a byte string in the
encoding used for CHAR data. The default value is NULL.
- name: recipientNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrCreateParams.recipientName`]
member, in bytes. The default value is 0.
- name: ipAddress
type: const char *
desc: |
Specifies the IP address on which the subscription listens to receive
notifications. The IP address can be an IPv4 address in dotted decimal
format such as 192.1.2.34 or an IPv6 address in hexadecimal format such as
2001:0db8:0000:0000:0217:f2ff:fe4b:4ced. The default value is NULL which
means that an IP address will be selected by the Oracle client.
- name: ipAddressLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrCreateParams.ipAddress`]
member, in bytes. The default value is 0.
- name: groupingClass
type: uint8_t
desc: |
Specifies the grouping class to use when grouping events. It should be one
of the values from the enumeration
[`dpiSubscrGroupingClass`]. The default value is
0. If this value is 0, the groupingValue and groupingType attributes are
ignored.
- name: groupingValue
type: uint32_t
desc: |
Specifies the value to be used in grouping. The meaning of this value
depends on the value of the groupingClass attribute. For time based
grouping this value refers to the number of seconds during which events
will be grouped together. The default value is 0.
- name: groupingType
type: uint8_t
desc: |
Specifies the type of grouping to use when grouping events. It should be
one of the values from the enumeration
[`dpiSubscrGroupingType`]. The default value is
DPI_SUBSCR_GROUPING_TYPE_SUMMARY.
- name: outRegId
type: uint64_t
desc: |
Specifies the registration id of the subscription that corresponds to the
REG_ID column in the USER_SUBSCR_REGISTRATIONS and DBA_SUBSCR_REGISTRATIONS
views in the database. It will be populated for CQN registrations after a
successful call to [`dpiConn_subscribe()`].
- name: clientInitiated
type: int
desc: |
Specifies whether a client initiated connection should be created (1) or
a server initiated connection should be created (0). The default value is
0. This feature is only available when Oracle Client 19.4 and Oracle
Database 19.4 or higher are being used.
- name: dpiSubscrMessage
kind: struct
desc: |
This structure is used for passing messages sent by notifications to
subscriptions. It is the second parameter to the callback method specified in
the [`dpiSubscrCreateParams`] structure.
members:
- name: eventType
type: dpiEventType
desc: |
Specifies the type of event that took place which generated the
notification. It will be one of the values from the enumeration
[`dpiEventType`].
- name: dbName
type: const char *
desc: |
Specifies the name of the database which generated the notification, as a
byte string in the encoding used for CHAR data. This value is not
populated when the [`dpiSubscrMessage.eventType`] member is set to
the values DPI_EVENT_AQ or DPI_EVENT_DEREG.
- name: dbNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessage.dbName`] member, in
bytes.
- name: tables
type: dpiSubscrMessageTable *
desc: |
Specifies a pointer to an array of
[`dpiSubscrMessageTable`] structures representing
the list of tables that were modified and generated this notification. This
value is only populated when the value of the
[`dpiSubscrMessage.eventType`] member is set to DPI_EVENT_OBJCHANGE.
- name: numTables
type: uint32_t
desc: |
Specifies the number of structures available in the
[`dpiSubscrMessage.tables`] member.
- name: queries
type: dpiSubscrMessageQuery *
desc: |
Specifies a pointer to an array of
[`dpiSubscrMessageQuery`] structures representing
the list of queries that were modified and generated this notification.
This value is only populated when the value of the
[`dpiSubscrMessage.eventType`] member is set to
DPI_EVENT_QUERYCHANGE.
- name: numQueries
type: uint32_t
desc: |
Specifies the number of structures available in the
[`dpiSubscrMessage.queries`] member.
- name: errorInfo
type: dpiErrorInfo *
desc: |
Specifies a pointer to a [`dpiErrorInfo`] structure. This
value will be NULL if no error has taken place. If this value is not NULL
the other members in this structure will not be populated.
- name: txId
type: const void *
desc: |
Specifies the id of the transaction which generated the notification, as a
series of bytes. This value is not populated when the
[`dpiSubscrMessage.eventType`] member is set to the values
DPI_EVENT_AQ or DPI_EVENT_DEREG.
- name: txIdLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessage.txId`] member, in
bytes.
- name: registered
type: int
desc: |
Specifies whether the subscription is registered with the database (1) or
not (0). The subscription is automatically deregistered with the database
when the subscription timeout value is reached or when the first
notification is sent (when the quality of service flag
DPI_SUBSCR_QOS_DEREG_NFY is used).
- name: queueName
type: const char *
desc: |
Specifies the name of the queue which has messages available to dequeue, as
a byte string in the encoding used for CHAR data. This value is only
populated when the [`dpiSubscrMessage.eventType`] member is set to
the value DPI_EVENT_AQ.
- name: queueNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessage.queueName`] member,
in bytes.
- name: consumerName
type: const char *
desc: |
Specifies the consumer name of the queue which has messages available to
dequeue, as a byte string in the encoding used for CHAR data. This value is
only populated when the [`dpiSubscrMessage.eventType`] member is set
to the value DPI_EVENT_AQ. It is also only populated if the queue that has
messages to dequeue is a multi-consumer queue.
- name: consumerNameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessage.consumerName`]
member, in bytes.
- name: aqMsgId
type: const void *
desc: |
Specifies message id of the message which is available to dequeue, as a
series of bytes. This value is only populated when the
[`dpiSubscrMessage.eventType`] member is set to the value
DPI_EVENT_AQ.
- name: aqMsgIdLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessage.aqMsgId`]
member, in bytes.
- name: dpiSubscrMessageQuery
kind: struct
desc: |
This structure is used for passing information on query change notification
events and is part of the [`dpiSubscrMessage`] structure.
members:
- name: id
type: uint64_t
desc: |
Specifies the id of the query that was registered as part of the
subscription that generated this notification.
- name: operation
type: dpiOpCode
desc: |
Specifies the operations that took place on the registered query. It will
be one or more of the values from the enumeration
[`dpiOpCode`], OR’ed together.
- name: tables
type: dpiSubscrMessageTable *
desc: |
Specifies a pointer to an array of
[`dpiSubscrMessageTable`] structures representing
the list of tables that were modified by the event which generated this
notification.
- name: numTables
type: uint32_t
desc: |
Specifies the number of structures available in the
[`dpiSubscrMessageQuery.tables`] member.
- name: dpiSubscrMessageRow
kind: struct
desc: |
This structure is used for passing information on the rows that were changed
and resulted in the notification message of which this structure is a part.
members:
- name: operation
type: dpiOpCode
desc: |
Specifies the operations that took place on the registered query. It will
be one or more of the values from the enumeration
[`dpiOpCode`], OR’ed together.
- name: rowid
type: const char *
desc: |
Specifies the rowid of the row that was changed, in the encoding used for
CHAR data.
- name: rowidLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessageRow.rowid`] member, in
bytes.
- name: dpiSubscrMessageTable
kind: struct
desc: |
This structure is used for passing information on the tables that were changed
and resulted in the notification message of which this structure is a part.
members:
- name: operation
type: dpiOpCode
desc: |
Specifies the operations that took place on the modified table. It will
be one or more of the values from the enumeration
[`dpiOpCode`], OR’ed together.
- name: name
type: const char *
desc: |
Specifies the name of the table that was changed, in the encoding used for
CHAR data.
- name: nameLength
type: uint32_t
desc: |
Specifies the length of the [`dpiSubscrMessageRow.name`] member, in
bytes.
- name: rows
type: dpiSubscrMessageRow *
desc: |
Specifies a pointer to an array of
[`dpiSubscrMessageRow`] structures representing the
list of rows that were modified by the event which generated this
notification.
- name: numRows
type: uint32_t
desc: |
Specifies the number of structures available in the
[`dpiSubscrMessageTable.rows`] member.
- name: dpiTimestamp
kind: struct
desc: |
This structure is used for passing timestamp data to and from the database in
the structure [`dpiData`].
members:
- name: year
type: int16_t
desc: |
Specifies the year for the timestamp.
- name: month
type: uint8_t
desc: |
Specifies the month for the timestamp. This should be between 1 and 12.
- name: day
type: uint8_t
desc: |
Specifies the day for the timestamp. This should be between 1 and 31.
- name: hour
type: uint8_t
desc: |
Specifies the hour for the timestamp. This should be between 0 and 23.
- name: minute
type: uint8_t
desc: |
Specifies the minute for the timestamp. This should be between 0 and 59.
- name: second
type: uint8_t
desc: |
Specifies the second for the timestamp. This should be between 0 and 59.
- name: fsecond
type: uint32_t
desc: |
Specifies the fractional seconds for the timestamp, in nanoseconds.
- name: tzHourOffset
type: int8_t
desc: |
Specifies the hours offset from UTC. This value is only used for timestamp
with time zone and timestamp with local time zone columns.
- name: tzMinuteOffset
type: int8_t
desc: |
Specifies the minutes offset from UTC. This value is only used for
timestamp with time zone and timestamp with local time zone columns. Note
that this value will be negative in the western hemisphere. For example,
when the timezone is -03:30, tzHourOffset will be -3 and tzMinuteOffset
will be -30.
- name: dpiVectorInfo
kind: struct
desc: |
This structure is used for providing or receiving information about a vector.
members:
- name: format
type: uint8_t
desc: |
Specifies the storage format for the vector. It should be one of the values
from the enumeration [`dpiVectorFormat`].
- name: numDimensions
type: uint32_t
desc: |
Specifies the number of dimensions the vector contains.
- name: dimensionSize
type: uint8_t
desc: |
Specifies the size (in bytes) of each dimension of the vector. This value
does not need to be specified on input but is populated on output as a
convenience.
- name: dimensions
type: dpiVectorDimensionBuffer
desc: |
Specifies the buffer for the dimensions. On input the buffer must remain
valid for the duration of the call into ODPI-C. On output the buffer will
remain valid as long as the vector object remains valid and the contents of
the vector are not changed. See the
[`dpiVectorDimensionBuffer`] union for more
information.
For dense vectors, the length of this array is defined by the
[`dpiVectorInfo.numDimensions`] member. For sparse vectors, the
length of this array is defined by the
[`dpiVectorInfo.numSparseValues`] member.
- name: numSparseValues
type: uint32_t
desc: |
Specifies the number of values that a sparse vector contains that are
non-zero. If this value is 0, the vector is considered a dense vector.
- name: sparseIndices
type: uint32_t *
desc: |
Specifies an array of sparse vector indices. Each element in this array is
the index of a non-zero value in the vector. The length of this array is
defined by the [`dpiVectorInfo.numSparseValues`] member. If the
vector is not a sparse vector, this value will be NULL.
- name: dpiVersionInfo
kind: struct
desc: |
This structure is used for returning Oracle version information about the
Oracle Client ([`dpiContext_getClientVersion()`]) and Oracle Database
([`dpiConn_getServerVersion()`]).
members:
- name: versionNum
type: int
desc: |
Specifies the major version of the Oracle Client or Database.
- name: releaseNum
type: int
desc: |
Specifies the release version of the Oracle Client or Database.
- name: updateNum
type: int
desc: |
Specifies the update version of the Oracle Client or Database.
- name: portReleaseNum
type: int
desc: |
Specifies the port specific release version of the Oracle Client or
Database.
- name: portUpdateNum
type: int
desc: |
Specifies the port specific update version of the Oracle Client or
Database.
- name: fullVersionNum
type: uint32_t
desc: |
Specifies the full version (all five components) as a number that is
suitable for comparison with the result of the macro
DPI_ORACLE_VERSION_TO_NUMBER.
- name: dpiXid
kind: struct
desc: |
This structure is used for identifying a TPC (two-phase commit) transaction. It
is used by the TPC functions [`dpiConn_tpcBegin()`],
[`dpiConn_tpcCommit()`], [`dpiConn_tpcEnd()`],
[`dpiConn_tpcForget()`], [`dpiConn_tpcPrepare()`] and
[`dpiConn_tpcRollback()`].
members:
- name: formatId
type: long
desc: |
An integer identifying the format the transaction id is expected to take.
A value of -1 implies that the XID value is NULL.
- name: globalTransactionId
type: const char *
desc: |
Specifies the global transaction identifier of the XID.
- name: globalTransactionIdLength
type: uint32_t
desc: |
Specifies the length of the [`dpiXid.globalTransactionId`] member, in
bytes. The maximum supported length is 64 bytes.
- name: branchQualifier
type: const char *
desc: |
Specifies the branch qualifier of the XID.
- name: branchQualifierLength
type: uint32_t
desc: |
Specifies the length of the [`dpiXid.branchQualifier`] member, in
bytes. The maximum supported length is 64 bytes.
- name: dpiDataBuffer
kind: union
desc: |
This union is used for passing data to and from the database without requiring
casts.
members:
- name: asBoolean
type: int
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_BOOLEAN. The value should be either 1 (true) or 0 (false).
- name: asUint8
type: uint8_t
desc: |
Only used for getting/setting OCI attributes of 1 byte in length.
- name: asUint16
type: uint16_t
desc: |
Only used for getting/setting OCI attributes of 2 bytes in length.
- name: asUint32
type: uint32_t
desc: |
Only used for getting/setting OCI attributes of 4 bytes in length.
- name: asInt64
type: int64_t
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_INT64.
- name: asUint64
type: uint64_t
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_UINT64.
- name: asFloat
type: float
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_FLOAT.
- name: asDouble
type: double
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_DOUBLE.
- name: asString
type: char *
desc: |
Only used for getting/setting OCI attributes of type string.
- name: asRaw
type: void *
desc: |
Raw pointer used for getting/setting all OCI attributes.
- name: asBytes
type: dpiBytes
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_BYTES. This is a structure of type
[`dpiBytes`].
- name: asTimestamp
type: dpiTimestamp
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_TIMESTAMP. This is a structure of type
[`dpiTimestamp`].
- name: asIntervalDS
type: dpiIntervalDS
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_INTERVAL_DS. This is a structure of type
[`dpiIntervalDS`].
- name: asIntervalYM
type: dpiIntervalYM
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_INTERVAL_YM. This is a structure of type
[`dpiIntervalYM`].
- name: asJson
type: dpiJson *
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_JSON. This is a reference to a JSON value which can be used
for reading and writing the data that belongs to it.
- name: asJsonObject
type: dpiJsonObject
desc: |
Value this is used when the native type that is being used is
DPI_NATIVE_TYPE_JSON_OBJECT. This is a structure of type
[`dpiJsonObject`].
- name: asJsonArray
type: dpiJsonArray
desc: |
Value this is used when the native type that is being used is
DPI_NATIVE_TYPE_JSON_ARRAY. This is a structure of type
[`dpiJsonArray`].
- name: asLOB
type: dpiLob *
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_LOB. This is a reference to a LOB (large object) which can
be used for reading and writing the data that belongs to it.
- name: asObject
type: dpiObject *
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_OBJECT. This is a reference to an object which can be used
for reading and writing its attributes or element values.
- name: asStmt
type: dpiStmt *
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_STMT. This is a reference to a statement which can be used
to query data from the database.
- name: asRowid
type: dpiRowid *
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_ROWID. This is a reference to a rowid which is used to
uniquely identify a row in a table in the database.
- name: asVector
type: dpiVector *
desc: |
Value that is used when the native type that is being used is
DPI_NATIVE_TYPE_VECTOR. This is a reference to a vector value which can be
used for reading and writing the data that belongs to it.
- name: dpiVectorDimensionBuffer
kind: union
desc: |
This union is used for passing vector dimensions to and from the database
without requiring casts.
members:
- name: asPtr
type: void *
desc: |
Raw pointer to dimension buffer.
- name: asInt8
type: int8_t *
desc: |
Pointer to dimension buffer when vector format is VECTOR_FORMAT_INT8.
- name: asFloat
type: float *
desc: |
Pointer to dimension buffer when vector format is VECTOR_FORMAT_FLOAT32.
- name: asDouble
type: double *
desc: |
Pointer to dimension buffer when vector format is VECTOR_FORMAT_FLOAT64.