1. Programmer's Guide
  2. Changes in This Release for Oracle Call Interface Programmer's Guide

Changes in This Release for Oracle Call Interface Programmer's Guide

This preface contains:

  • Changes in Oracle Database 12c Release 2 (12.2)

Changes in Oracle Database 12c Release 2 (12.2.0.1)

Changes in Oracle Database 12c release 2 (12.2.0.1).

The following are changes in the Oracle Call Interface (OCI) for release 2 (12.2.0.1):

New Features

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.

    • New OCIShardingKeyColumnAdd() call to add sharding key columns to an OCIShardingKey to form a compound sharding key or compound super sharding key.

    • New OCIShardingKeyReset() call allows an application to reset an OCIShardingKey and reuse an allocated descriptor for creating a new sharding key or super sharing key.

    • New service context handle attributes:

      • 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 (OCISvcCtx).

      • 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 (OCISvcCtx).

      • 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:

      • The 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:

      • The attribute OCI_ATTR_INSTNAME is used on a service context to return the shard instance name for a given connection using the OCIAttrGet() call.

      • New OCIShardInstancesGet() call that returns the list of instances for a given sharding key, super sharding key, and connection string.

      • New OCISessionGet() mode 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 OCIDescriptorAlloc(), OCIShardingKeyColumnAdd(), OCIShardingKeyReset(), Service Context Handle Attributes, OCIAttrGet(), OCIShardInstancesGet(), and OCISessionGet() for more information.

    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:

      OCISessionGet() 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 OCI_SESSGET_MULTIPROPERTY_TAG mode.

      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 found parameter.

      A session can be tagged with a multi-property tag by invoking OCISessionRelease() (with OCI_SESSRLS_RETAG | 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.

      See About Using Tags in Session Pools and OCISessionGet() 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 OCI_ATTR_SPOOL_WAIT_TIMEOUT attribute.

      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.

    • New FAILOVER_TYPE value: TRANSACTION. This value supports replay of an inflight transaction upon receipt of a recoverable error.

    • For hiding planned maintenance:

    • 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 OCI_ATTR_FIXUP_CALLBACK.

    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.

  • Support for Pluggable Databases:

    • 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:

      • The 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.

      • The ALTER SESSION SET CONTAINER statement can be used to switch an OCI connection between any two pluggable databases whose character sets are different.

    See Enhancements on OCI API Calls with Multitenant Container Databases (CDB) in General and OCI Enhancements for ALTER SESSION SET CONTAINER for more information.

  • The OTT parameter USERID now accepts a max length up to 243 bytes for the username and 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 OCIContextSetValue(), OCIContextGetValue(), and OCIContextClearValue() the maximum length of the keylen parameter was increased from 64 bytes to 255 bytes.

    See OCIContextSetValue(), OCIContextGetValue(), and OCIContextClearValue() for more information.

  • The <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: OCILCRScnToPosition2(), OCILCRComparePosition(), OCILCRConvertPosition(), 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 OCILCRScnToPosition2(), OCILCRComparePosition(), OCILCRConvertPosition(), OCILCRGetLCRIDVersion(), OCILCRSCNsFromPosition(), and OCILCRSCNToPosition() for more information.

    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

    This support includes changes to the following functions:

    • 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.

    See OCILCRHeaderGet() and OCIXStreamOutAttach() for more information.

  • 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 FROM or 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 (CLOB, BLOB) but not for BFILE locators.

    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 LOB Functions, About Using OCI Functions for LOBs, and LOB Locator Attributes for more information.

    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 NUMBER and 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: OCI_CPW_SYSDBA, OCI_CPW_SYSOPER, OCI_CPW_SYSASM, OCI_CPW_SYSBKP, OCI_CPW_SYSDGD, and OCI_CPW_SYSKMT.

    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_CHARSET_RATIO and 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.

    See About Choosing a Character Set and Service Context Handle Attributes for more informati

  • 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.

    See OCI Authentication Management and OCISessionBegin() for more information.

  • 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.

  • Two new direct path context handle (OCIDirPathCtx) attributes:

    • 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.

Deprecated Features

The following deprecated features will not be supported in future releases: