ODPI-C Function Round-Trips

The following table identifies if round-trips to the database are required when calling each of the functions that ODPI-C supports. A round-trip is defined as the trip from the Oracle Client libraries (used by ODPI-C) to the database and back.

Function

Round-Trips?

Notes

dpiConn_addRef()

No

dpiConn_beginDistribTrans()

Yes

dpiConn_breakExecution()

Yes

dpiConn_changePassword()

Yes

dpiConn_close()

Maybe

If the connection was acquired from a pool, a round-trip is only required if the parameter mode is set to the value DPI_MODE_CONN_CLOSE_DROP. For standalone connections, a round-trip is always required. If there is an open transaction, a round-trip is also required to perform the implicit rollback that takes place.

dpiConn_commit()

Yes

dpiConn_create()

Maybe

If a standalone connection is being created, one round-trip is required. If a connection is being acquired from a pool, no round-trips are required if an unused connection is available in the pool; otherwise, a round trip is required for each connection that is added to the pool (see dpiPoolCreateParams.sessionIncrement).

dpiConn_deqObject()

Yes

dpiConn_enqObject()

Yes

dpiConn_getCallTimeout()

No

dpiConn_getCurrentSchema()

No

dpiConn_getEdition()

No

dpiConn_getEncodingInfo()

No

dpiConn_getExternalName()

No

dpiConn_getHandle()

No

dpiConn_getInternalName()

No

dpiConn_getIsHealthy()

No

dpiConn_getLTXID()

No

dpiConn_getObjectType()

Maybe

If the type information is already available in the Oracle Client object cache, only one round trip is required; otherwise, two round-trips are required unless the type contains embedded types or is a collection. In that case additional round-trips are required to fetch the additional type information.

dpiConn_getOciAttr()

No

dpiConn_getServerVersion()

Maybe

The first call when requesting the release string always requires a round-trip. If the release string is not requested and Oracle Client 20.3 or higher is being used, no round-trip is required. Similarly for earlier versions, if the release string is not requested and a pooled connection is used that previously had a call to this function made, no round-trip is required; otherwise, a round-trip is required. Subsequent calls with any client version do not require a round-trip.

dpiConn_getSodaDb()

Maybe

An internal call to check the server version is made. The notes on the function dpiConn_getServerVersion() apply.

dpiConn_getStmtCacheSize()

No

dpiConn_newDeqOptions()

No

dpiConn_newEnqOptions()

No

dpiConn_newMsgProps()

No

dpiConn_newQueue()

No

dpiConn_newTempLob()

Yes

dpiConn_newVar()

No

dpiConn_ping()

Yes

dpiConn_prepareDistribTrans()

Yes

dpiConn_prepareStmt()

No

dpiConn_release()

Maybe

If the number of references exceeds 1 or the connection has already been closed by a call to dpiConn_close() then no round-trips are required; otherwise, the connection is closed at this point and the notes on the function dpiConn_close() apply.

dpiConn_rollback()

Yes

dpiConn_setAction()

No

dpiConn_setCallTimeout()

No

dpiConn_setClientIdentifier()

No

dpiConn_setClientInfo()

No

dpiConn_setCurrentSchema()

No

dpiConn_setDbOp()

No

dpiConn_setEcontextId()

No

dpiConn_setExternalName()

No

dpiConn_setInternalName()

No

dpiConn_setModule()

No

dpiConn_setOciAttr()

No

dpiConn_setStmtCacheSize()

No

dpiConn_shutdownDatabase()

Yes

dpiConn_startupDatabase()

Yes

dpiConn_startupDatabaseWithPfile()

Yes

dpiConn_subscribe()

Yes

dpiConn_tpcBegin()

Yes

dpiConn_tpcCommit()

Yes

dpiConn_tpcEnd()

Yes

dpiConn_tpcForget()

Yes

dpiConn_tpcPrepare()

Yes

dpiConn_tpcRollback()

Yes

dpiConn_unsubscribe()

Yes

dpiContext_createWithParams()

No

dpiContext_destroy()

No

dpiContext_getClientVersion()

No

dpiContext_getError()

No

dpiContext_initCommonCreateParams()

No

dpiContext_initConnCreateParams()

No

dpiContext_initPoolCreateParams()

No

dpiContext_initSodaOperOptions()

No

dpiContext_initSubscrCreateParams()

No

dpiData_getBool()

No

dpiData_getBytes()

No

dpiData_getDouble()

No

dpiData_getFloat()

No

dpiData_getInt64()

No

dpiData_getIntervalDS()

No

dpiData_getIntervalYM()

No

dpiData_getIsNull()

No

dpiData_getJson()

No

dpiData_getJsonArray()

No

dpiData_getJsonObject()

No

dpiData_getLOB()

No

dpiData_getObject()

No

dpiData_getStmt()

No

dpiData_getTimestamp()

No

dpiData_getUint64()

No

dpiData_setBool()

No

dpiData_setBytes()

No

dpiData_setDouble()

No

dpiData_setFloat()

No

dpiData_setInt64()

No

dpiData_setIntervalDS()

No

dpiData_setIntervalYM()

No

dpiData_setLOB()

No

dpiData_setNull()

No

dpiData_setObject()

No

dpiData_setStmt()

No

dpiData_setTimestamp()

No

dpiData_setUint64()

No

dpiDeqOptions_addRef()

No

dpiDeqOptions_getCondition()

No

dpiDeqOptions_getConsumerName()

No

dpiDeqOptions_getCorrelation()

No

dpiDeqOptions_getMode()

No

dpiDeqOptions_getMsgId()

No

dpiDeqOptions_getNavigation()

No

dpiDeqOptions_getTransformation()

No

dpiDeqOptions_getVisibility()

No

dpiDeqOptions_getWait()

No

dpiDeqOptions_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiDeqOptions_setCondition()

No

dpiDeqOptions_setConsumerName()

No

dpiDeqOptions_setCorrelation()

No

dpiDeqOptions_setDeliveryMode()

No

dpiDeqOptions_setMode()

No

dpiDeqOptions_setMsgId()

No

dpiDeqOptions_setNavigation()

No

dpiDeqOptions_setTransformation()

No

dpiDeqOptions_setVisibility()

No

dpiDeqOptions_setWait()

No

dpiEnqOptions_addRef()

No

dpiEnqOptions_getTransformation()

No

dpiEnqOptions_getVisibility()

No

dpiEnqOptions_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiEnqOptions_setDeliveryMode()

No

dpiEnqOptions_setTransformation()

No

dpiEnqOptions_setVisibility()

No

dpiJson_addRef()

No

dpiJson_getValue()

Maybe

A round trip is needed if the JSON data has not yet been fetched from the server.

dpiJson_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiJson_setFromText()

No

dpiJson_setValue()

No

dpiLob_addRef()

No

dpiLob_close()

Maybe

If the LOB is a temporary LOB, one round-trip is required to free the temporary LOB; otherwise, no round-trips are required.

dpiLob_closeResource()

Yes

dpiLob_copy()

Yes

dpiLob_getBufferSize()

No

dpiLob_getChunkSize()

Yes

dpiLob_getDirectoryAndFileName()

No

dpiLob_getFileExists()

Yes

dpiLob_getIsResourceOpen()

Yes

dpiLob_getSize()

Yes

dpiLob_getType()

No

dpiLob_openResource()

Yes

dpiLob_readBytes()

Yes

dpiLob_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiLob_setDirectoryAndFileName()

No

dpiLob_setFromBytes()

Yes

dpiLob_trim()

Yes

dpiLob_writeBytes()

Yes

dpiMsgProps_addRef()

No

dpiMsgProps_getCorrelation()

No

dpiMsgProps_getDelay()

No

dpiMsgProps_getDeliveryMode()

No

dpiMsgProps_getEnqTime()

No

dpiMsgProps_getExceptionQ()

No

dpiMsgProps_getExpiration()

No

dpiMsgProps_getMsgId()

No

dpiMsgProps_getNumAttempts()

No

dpiMsgProps_getOriginalMsgId()

No

dpiMsgProps_getPayload()

No

dpiMsgProps_getPriority()

No

dpiMsgProps_getState()

No

dpiMsgProps_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiMsgProps_setCorrelation()

No

dpiMsgProps_setDelay()

No

dpiMsgProps_setExceptionQ()

No

dpiMsgProps_setExpiration()

No

dpiMsgProps_setOriginalMsgId()

No

dpiMsgProps_setPayloadBytes()

No

dpiMsgProps_setPayloadObject()

No

dpiMsgProps_setPriority()

No

dpiMsgProps_setRecipients()

No

dpiObject_addRef()

No

dpiObject_appendElement()

No

dpiObject_copy()

No

dpiObject_deleteElementByIndex()

No

dpiObject_getAttributeValue()

No

dpiObject_getElementExistsByIndex()

No

dpiObject_getElementValueByIndex()

No

dpiObject_getFirstIndex()

No

dpiObject_getLastIndex()

No

dpiObject_getNextIndex()

No

dpiObject_getPrevIndex()

No

dpiObject_getSize()

No

dpiObject_release()

Maybe

No round trips are required unless the last reference is being released, the internal reference to the object type is the last reference being released and the object type’s internal reference to the connection is the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiObject_setAttributeValue()

No

dpiObject_setElementValueByIndex()

No

dpiObject_trim()

No

dpiObjectAttr_addRef()

No

dpiObjectAttr_getInfo()

No

dpiObjectAttr_release()

Maybe

No round trips are required unless the last reference is being released, the internal reference to the object type is the last reference being released and the object type’s internal reference to the connection is the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiObjectType_addRef()

No

dpiObjectType_createObject()

No

dpiObjectType_getAttributes()

No

dpiObjectType_getInfo()

No

dpiObjectType_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiPool_acquireConnection()

Maybe

No round-trips are required if an unused connection is available in the pool; otherwise, a round trip is required for each connection that is added to the pool (see dpiPoolCreateParams.sessionIncrement). A round-trip may also be required if a PL/SQL fixup callback is specified (see dpiPoolCreateParams.plsqlFixupCallback).

dpiPool_addRef()

No

dpiPool_close()

Maybe

One round trip is required for each session in the pool that needs to be closed.

dpiPool_create()

Maybe

One round trip is required for each session that is initially added to the pool (see dpiPoolCreateParams.minSessions).

dpiPool_getBusyCount()

No

dpiPool_getEncodingInfo()

No

dpiPool_getGetMode()

No

dpiPool_getMaxLifetimeSession()

No

dpiPool_getMaxSessionsPerShard()

No

dpiPool_getOpenCount()

No

dpiPool_getPingInterval()

No

dpiPool_getSodaMetadataCache()

No

dpiPool_getStmtCacheSize()

No

dpiPool_getTimeout()

No

dpiPool_getWaitTimeout()

No

dpiPool_reconfigure()

Maybe

If the minimum size of the pool is not being increased, no round-trips are required; otherwise, round-trips are required for each session in the pool that needs to be added to reach the new minimum.

dpiPool_release()

Maybe

If the number of references exceeds 1 or the pool has already been closed by a call to dpiPool_close() then no round-trips are required; otherwise, the pool is closed at this point and the notes on the function dpiPool_close() apply.

dpiPool_setAccessToken()

No

dpiPool_setGetMode()

No

dpiPool_setMaxLifetimeSession()

No

dpiPool_setMaxSessionsPerShard()

No

dpiPool_setPingInterval()

No

dpiPool_setSodaMetadataCache()

No

dpiPool_setStmtCacheSize()

No

dpiPool_setTimeout()

No

dpiPool_setWaitTimeout()

No

dpiQueue_addRef()

No

dpiQueue_deqMany()

Yes

dpiQueue_deqOne()

Yes

dpiQueue_enqMany()

Yes

dpiQueue_enqOne()

Yes

dpiQueue_getDeqOptions()

No

dpiQueue_getEnqOptions()

No

dpiQueue_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiRowid_addRef()

No

dpiRowid_getStringValue()

No

dpiRowid_release()

No

dpiSodaColl_addRef()

No

dpiSodaColl_createIndex()

Yes

dpiSodaColl_drop()

Yes

dpiSodaColl_dropIndex()

Yes

dpiSodaColl_find()

Yes

dpiSodaColl_findOne()

Yes

dpiSodaColl_getDataGuide()

Yes

dpiSodaColl_getDocCount()

Yes

dpiSodaColl_getMetadata()

No

dpiSodaColl_getName()

No

dpiSodaColl_insertMany()

Yes

dpiSodaColl_insertManyWithOptions()

Yes

dpiSodaColl_insertOne()

Yes

dpiSodaColl_insertOneWithOptions()

Yes

dpiSodaColl_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiSodaColl_remove()

Yes

dpiSodaColl_replaceOne()

Yes

dpiSodaColl_save()

Yes

dpiSodaColl_saveWithOptions()

Yes

dpiSodaColl_truncate()

Yes

dpiSodaCollCursor_addRef()

No

dpiSodaCollCursor_close()

No

dpiSodaCollCursor_getNext()

Yes

dpiSodaCollCursor_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiSodaDb_addRef()

No

dpiSodaDb_createCollection()

Maybe

If the SODA metadata cache has been enabled and no metadata has been specified, a round trip is not required after the first time that a collection with a particular name is opened.

dpiSodaDb_createDocument()

No

dpiSodaDb_freeCollectionNames()

No

dpiSodaDb_getCollections()

Yes

dpiSodaDb_getCollectionNames()

Yes

dpiSodaDb_openCollection()

Maybe

If the SODA metadata cache has been enabled, a round trip is not required after the first time that a collection with a particular name is opened.

dpiSodaDb_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiSodaDoc_addRef()

No

dpiSodaDoc_getContent()

No

dpiSodaDoc_getCreatedOn()

No

dpiSodaDoc_getKey()

No

dpiSodaDoc_getLastModified()

No

dpiSodaDoc_getMediaType()

No

dpiSodaDoc_getVersion()

No

dpiSodaDoc_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiSodaDocCursor_addRef()

No

dpiSodaDocCursor_close()

No

dpiSodaDocCursor_getNext()

Yes

dpiSodaDocCursor_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiStmt_addRef()

No

dpiStmt_bindByName()

No

dpiStmt_bindByPos()

No

dpiStmt_bindValueByName()

No

dpiStmt_bindValueByPos()

No

dpiStmt_close()

No

dpiStmt_define()

No

dpiStmt_defineValue()

No

dpiStmt_deleteFromCache()

No

dpiStmt_execute()

Yes

dpiStmt_executeMany()

Yes

dpiStmt_fetch()

Maybe

An internal array of rows corresponding to the value set by a call to dpiStmt_setFetchArraySize() is maintained. A round trip is only required when this array has been exhausted and new rows are required to be fetched from the database.

dpiStmt_fetchRows()

Maybe

An internal array of rows corresponding to the value set by a call to dpiStmt_setFetchArraySize() is maintained. If any rows exist in this array, no round trip is required; otherwise, a round trip is required.

dpiStmt_getBatchErrorCount()

No

dpiStmt_getBatchErrors()

No

dpiStmt_getBindCount()

No

dpiStmt_getBindNames()

No

dpiStmt_getFetchArraySize()

No

dpiStmt_getImplicitResult()

No

dpiStmt_getInfo()

No

dpiStmt_getLastRowid()

No

dpiStmt_getNumQueryColumns()

No

dpiStmt_getOciAttr()

No

dpiStmt_getPrefetchRows()

No

dpiStmt_getQueryInfo()

No

dpiStmt_getQueryValue()

No

dpiStmt_getRowCount()

No

dpiStmt_getRowCounts()

No

dpiStmt_getSubscrQueryId()

No

dpiStmt_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiStmt_scroll()

Yes

dpiStmt_setFetchArraySize()

No

dpiStmt_setOciAttr()

No

dpiStmt_setPrefetchRows()

No

dpiSubscr_addRef()

No

dpiSubscr_prepareStmt()

No

dpiSubscr_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiVar_addRef()

No

dpiVar_copyData()

No

dpiVar_getNumElementsInArray()

No

dpiVar_getReturnedData()

No

dpiVar_getSizeInBytes()

No

dpiVar_release()

Maybe

No round trips are required unless the last reference is being released and the internal reference to the connection is also the last reference to that connection. In that case, the notes on the function dpiConn_release() apply.

dpiVar_setFromBytes()

Maybe

If the variable refers to a LOB, one round-trip is required; otherwise, no round trips are required.

dpiVar_setFromJson()

No

dpiVar_setFromLob()

No

dpiVar_setFromObject()

No

dpiVar_setFromRowid()

No

dpiVar_setFromStmt()

No

dpiVar_setNumElementsInArray()

No