This preface contains:
Changes in Oracle Database 12c Release 2 (12.2)
The following features are new in this release:
Oracle Sharding interfaces — support interfaces for the database sharding feature during connection initiation for a standalone connection, for getting a connection from an OCI Session pool, and support interfaces for custom connection pools:
New sharding key and super sharding key descriptor type
OCIShardingKey with an OCI descriptor named
OCI_DTYPE_SHARDING_KEY. This descriptor type is used for forming the sharding key as well as the super sharding key. This descriptor type is a new addition to the
type parameter for the
OCIDescriptorAlloc() call for allocating the sharding key and super sharding key descriptors.
OCIShardingKeyColumnAdd() call to add sharding key columns to an
OCIShardingKey to form a compound sharding key or compound super sharding key.
OCIShardingKeyReset() call allows an application to reset an
OCIShardingKey and reuse an allocated descriptor for creating a new sharding key or super sharing key.
OCI_ATTR_SHARDING_KEY — For standalone connections and OCI Session pools, this attribute is set on the OCIAuth handle before performing
OCISessionGet() call. For custom pools, this attribute associates a sharding key to a given connection (
OCI_ATTR_SUPER_SHARDING_KEY — For standalone connections and OCI Session pools, this attribute is set on the OCIAuth handle before performing
OCISessionGet() call. For custom pools, this attribute associates a super sharding key to a given connection (
OCI_ATTR_SHARDING_KEY_B64 — For diagnostic purposes, this attribute to get the base 64 representation of a sharding key or super sharding key value. This attribute on the
OCI_DTYPE_SHARDING_KEY descriptor allows the
OCIAttrGet() call to take the
OCIShardingKey descriptor type as input and return the base64 representation of the sharding key or super sharding key.
For standalone connections and OCI session pools:
OCISessionGet() call takes an OCIAuth handle as input on which various properties are set, including the
OCIShardingKey descriptor type that is used to form the sharding key and the super sharding key. With these properties set, the
OCISessionGet() call gets a new session or a suitable existing session (if available, in case of OCI Session pool) to the specific shard containing the data corresponding to the sharding key and super sharding key values provided.
For use with custom pools, to return connections to specific shards, both the shard name must be determined to which the shard connection has been made and the shard name to sharding key or super sharding key to shard name mapping also must be determined to enable the lookup for a matching connection. The following new features enable this functionality:
OCI_ATTR_INSTNAME is used on a service context to return the shard instance name for a given connection using the
OCIShardInstancesGet() call that returns the list of instances for a given sharding key, super sharding key, and connection string.
OCI_SESSGET_CUSTOM_POOL for use with custom pools to allow explicit caching of its shard topology information when connecting to a new shard instance.
See About the OCI Interface for Using Shards, About Specifying a Sharding Key and Super Sharding Key for Getting a Connection from an OCI Session Pool, About Specifying a Sharding Key and Super Sharding Key for Getting a Connection from a Custom Pool, and OCI Descriptors for more information.
See the topic about developing applications for Oracle Sharding in Oracle Database Administrator’s Guide for more information.
Support for describing collations of result columns:
New statement handle attribute
OCI_ATTR_COLLATION_ID — Returns the collations from the describe information of a statement.
See Column Attributes for more information.
Improvements to OCI Session Pooling
Support for multi-property tags with OCI Session Pool and DRCP:
taginfo parameter has been extended to allow a tag to have multiple string properties. Such a tag with multiple string properties that are separated by the semi-colon (;) character is known as a multi-property tag. The ordering of the properties in the multi-property tag is significant for finding a matching session in the pool. A multi-property tag must be used in conjunction with the
retTagInfo parameter returned by
OCISessionGet() can also return a multi-property tag corresponding to the returned session, and needs to be interpreted in conjunction with the
A session can be tagged with a multi-property tag by invoking
OCI_SESSRLS_MULTIPROPERTY_TAG mode) by setting the tag parameter to be a multi-property tag.
This functionality also works with DRCP. See Database Resident Connection Pooling for more information.
A new mode
OCI_SPOOL_ATTRVAL_TIMEDWAIT has been added to OCI Session Pool handle that can be used to time out the
OCISessionGet() call waiting to get a free session. The time out value can be specified by the
See Session Pool Handle Attributes for more information.
Improvements to OCI Session Pooling involving dead connection detection, cleanup, and idle session re-establishment. This improves reliability, giving applications more certainty that
OCISessionGet() can return a usable session after an underlying network outage or database node failure.
Support for Application Continuity in an HA infrastructure includes:
Support for OCI Session pool for applications that use a pool.
TRANSACTION. This value supports replay of an inflight transaction upon receipt of a recoverable error.
For hiding planned maintenance:
New OCI Transparent Application Failover (TAF) error codes. See
ORA-25419 in Oracle Database Error Messages Reference for more information.
For hiding unplanned outages:
OCI Session pool support.
A new session pool handle attribute:
OCI_ATTR_FOCBK — Use this attribute with
OCIAttrSet() to define a TAF callback and the context to be associated with each session in the OCI Session pool; or, use this attribute with
OCIAttrGet() to populate the
OCIFocbkStruct with the TAF callback and the context defined for the session pool.
A new API,
OCIRequestDisableReply() — Triggers OCI to stop recording calls until the end of an application request (the end of a request is marked by
OCISessionRelease()). Use this call when Application Continuity for OCI is enabled but the application is entering a section of code that is not replayable.
A new TAF callback function,
TAFcbk_fn — Register a callback function so that if failover occurs, the callback function can be invoked several times while reestablishing the user’s session. The first call to allow the application to inform the user of an upcoming delay while failover is in progress and a second call to inform the user that the connection is reestablished and usable, or if failover is unsuccessful to inform the user that failover cannot occur. If the connection is reestablished and usable, the client may want to replay
ALTER SESSION commands and inform the user failover has happened, and so forth.
New Authentication Information Handle attribute
OCI_ATTR_FIXUP_CALLBACK — Specifies on the authentication handle attribute the callback passed to
OCISessionGet() for applications not using an OCISessionPool or using custom pools. For applications using OCISessionPool, this attribute must be set on the authentication handle, which in turn must be set on the session pool handle with attribute
OCI_ATTR_SPOOL_AUTH set to attribute
See OCI and Application Continuity, User Session Handle Attributes, Session Pool Handle Attributes, Authentication Information Handle Attributes, PL/SQL Callback for Session State Fix Up, OCIRequestDisableReplay(), and Transparent Application Failover Callback Structure and Parameters for more information.
Support for identifiers up to 128 bytes:
Names can now be up to 128 bytes in length. Previously the limit was 30 bytes. For example, these names include attribute names, directory alias names, and identifier names, such as for handle attributes that hold identifier names for OCIDirPath (direct path loading functions) among many other names.
Older OCI clients that only support 30–byte identifier names will continue to work with Release 2 (12.2) OCI APIs.
With the identifier length increased, OCI applications using deprecated V7 API
odessp() and deprecated UPI API
upidpr() may need to be changed. See the Note in About Upgrading of Existing OCI Release 7 Applications for more information.
Enhancements to OCI calls for Multitenant Container Databases (CDB):
Client result cache works with connections to Pluggable Databases.
Enhancements to OCI calls for ALTER SESSION SET CONTAINER:
The client must be at the same version as the server to perform these operations; otherwise, a lower version client will get an error:
ALTER SESSION SET CONTAINER statement supports applications that use
TIMESTAMP WITH TIMEZONE or
TIMESTAMP WITH LOCAL TIMEZONE data types in OCI. This allows an application to switch between pluggable databases having different database time zone settings or different database time zone file version settings.
ALTER SESSION SET CONTAINER statement can be used to switch an OCI connection between any two pluggable databases whose character sets are different.
The OTT parameter
USERID now accepts a max length up to 243 bytes for the
db_name combination, which is appended and used as a key in the
OCIContextGetValue() call. For Oracle Database 12c Release 1 (12.1), the max length was 64 bytes.
See the USERID OTT parameter for more information.
For the functions
OCIContextClearValue() the maximum length of the
keylen parameter was increased from 64 bytes to 255 bytes.
<wallet_location> element has been added under the
ons section for Oracle Notification Service (ONS) parameters of the
oraaccess.xml client configuration file.
See About Specifying Defaults for Connection Parameters for more information.
Support to convert from version 1 to version 2 SCN in XStream for new and changed functions:
This support includes new functions:
OCILCRGetLCRIDVersion(); and changes to functions:
OCILCRSCNsFromPosition() — to support both version 1 and version 2 and
OCILCRScnToPosition() — raises an error if the SCN value is larger than the maximum for version 1.
See the topic about logical change records in Oracle Database XStream Guide for more information.
XStream function support for replication of application containers and application common objects in federation PDBs
OCILCRHeaderGet(), a new LCR flag:
OCI_LCR_APPCON_REPLAY — indicates the logical change record (LCR) is replayed from the application container sync statement.
OCIXStreamOutAttach(), new mode flags:
OCIXSTREAM_OUT_ATTACH_APP_CONTAINER — the application is capturing application container statements (
ALTER PLUGGABLE DATABASE APPLICATION ) LCRs.
OCIXSTREAM_OUT_ATTACH_EXTENDED_TXID — the application is making a request for extended transaction ID format.
Distributed LOBs support in OCI:
Queries that select a LOB locator from a remote table are supported. DML operations on a remote table using a DBLink are supported.
Any tables mentioned in the
WHERE clause in queries and DML should be collocated. If remote locators are used as bind variables in the
WHERE clauses, they should be collocated. By tables or locators being collocated, it means that they use the same database link.
OCI LOB API supports distributed operations using remote LOB locators (
BLOB) but not for
All LOB APIs that take in two locators must have both LOBs collocated at one database.
New LOB locator attribute:
OCI_ATTR_LOB_REMOTE can be used to find out whether a LOB locator belongs to local database table or remote database table. As a Boolean data type, the returned value
TRUE indicates the LOB locator is from a remote database table.
The following LOB functions throw an error when a remote locator is passed: OCILobAssign(), OCILobLocatorAssign(), OCILobEnableBuffering(), OCILobDisableBuffering(), OCILobFlushBuffer(), OCILobArrayRead(), OCILobArrayWrite(), and OCILobLoadFromFile2().
See the chapter about using distributed LOBs and working with remote LOBs in Oracle Database SecureFiles and Large Objects Developer's Guide for more information.
Support for Hybrid Columnar Compression (HCC) with conventional DML operations:
HCC can be used during array inserts with OCI. HCC conventional array inserts are only supported for HCC tables on ASSM tablespaces.
See OCI Array Interface for more information.
See Oracle Database Administrator’s Guide for information about how to configure HCC.
Restriction on OCI calls that use the
ALTER SESSION SWITCH CONTAINER SWITCH SERVICE statement.
See Restrictions on OCI Calls with ALTER SESSION SWITCH CONTAINER SWITCH SERVICE for more information.
Support for validating the format or internal representation of Oracle
DATE data when loading stream data:
When a stream is parsed on the server using
OCIDirPathLoadStream(), you can use the direct path context handle attribute
OCI_ATTR_DIRPATH_FLAGS with the
OCI_DIRPATH_FLAGS_VLDT flag set to validate the internal representation of dates and numbers. However, this is an expensive operation, so the default is to not set this flag.
See About Validating Format for Oracle NUMBER and DATE Data and Direct Path Context Handle (OCIDirPathCtx) Attributes for more information.
Support for establishing an administrative session for an expired user account at logon before changing the password. The mode parameter for
OCIPasswordChange() can in addition to the
OCI_AUTH value accept any one the following additional mode flags that corresponds to its administrative session:
See OCIPasswordChange() for more information.
A change in the linear snapshot size from 24 bytes to 34 bytes requires the reconstruction of the collection image form:
When an older client or server accesses a Release 12.2 or higher database involving any access to collections, the collection image form that contains the linear snapshot must be converted when sending or receiving to older clients or server. This conversion results in the performance degradation. Oracle recommends that you use a 12.2 version of the client or server to avoid this conversion.
See OCI Object Overview for more information.
Instant Client can now use the
ORA_TZFILE environment variable to read the time zone file from the file system. Previously, specifying the
ORA_TZFILE environment variable would read the time zone file that was bundled in the data shared library and ignore the time zone file from the file system.
Two new service context handle attributes,
OCI_ATTR_MAX_NCHARSET_RATIO can be used to obtain the maximum character set expansion ratio from server to client character set or national character set respectively. This lets you more efficiently allocate optimal memory of buffers before conversion so that when data is returned from the database, sufficient space can be allocated to hold it. This is useful in scenarios where there are different character sets or national character sets between server and client.
A new authentication mode
OCI_SYSRAC for SYSRAC access can be used in the
mode parameter for
OCISessionBegin(). In this mode, you are authenticated for SYSRAC access. In addition, the authentication modes
OCI_SYSBKP for SYSBACKUP access,
OCI_SYSDGD for SYSDG access, and
OCI_SYSKMT for SYSKM access though implemented in Oracle 12c Release 1 (12.1) were not documented until recently in that release. These modes are also now documented in this current release.
A new statement handle attribute
OCI_ATTR_SQL_ID that gets the
SQL_ID for a specific SQL statement from the server and makes it available on the client.
See Statement Handle Attributes for more information.
OCI_ATTR_DIRPATH_DEF_EXP_CACHE_SIZE — Specifies the number of default expressions that are evaluated at a time. The default is 100. For default expressions that must be evaluated for every row, increasing this value may improve performance.
OCI_ATTR_DIRPATH_DEFAULTS — Specifies how the direct path API handles default expressions for columns that are not explicitly being loaded.
See Direct Path Context Handle (OCIDirPathCtx) Attributes for more information.
The following deprecated features will not be supported in future releases:
OCI release 7.3 API
See About Upgrading of Existing OCI Release 7 Applications for more information.
LOB Buffering subsystem APIs
In place of using these LOB buffering functions, use the LOB prefetch feature described in Prefetching of LOB Data, Length, and Chunk Size.
Statement function APIs
The following function is deprecated beginning with Oracle 12c Release 2 (12.2):
OCIStmtPrepare2() call to support the use of Application Continuity in an HA infrastructure. Applications that use
OCIStmtPrepare() return the following error:
Error - ORA-25412: transaction replay disabled by call to OCIStmtPrepare.