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

No relevant notes

dpiConn_breakExecution()

Yes

No relevant notes

dpiConn_changePassword()

Yes

No relevant notes

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

No relevant notes

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

No relevant notes

dpiConn_enqObject()

Yes

No relevant notes

dpiConn_getCallTimeout()

No

No relevant notes

dpiConn_getCurrentSchema()

No

No relevant notes

dpiConn_getDbDomain()

No

No relevant notes

dpiConn_getDbName()

No

No relevant notes

dpiConn_getEdition()

No

No relevant notes

dpiConn_getEncodingInfo()

No

No relevant notes

dpiConn_getExternalName()

No

No relevant notes

dpiConn_getHandle()

No

No relevant notes

dpiConn_getInstanceName()

No

No relevant notes

dpiConn_getInternalName()

No

No relevant notes

dpiConn_getIsHealthy()

No

No relevant notes

dpiConn_getLTXID()

No

No relevant notes

dpiConn_getMaxOpenCursors()

No

No relevant notes

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

No relevant notes

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_getServiceName()

No

No relevant notes

dpiConn_getSodaDb()

Maybe

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

dpiConn_getStmtCacheSize()

No

No relevant notes

dpiConn_getTransactionInProgress()

No

No relevant notes

dpiConn_newDeqOptions()

No

No relevant notes

dpiConn_newEnqOptions()

No

No relevant notes

dpiConn_newJson()

No

No relevant notes

dpiConn_newJsonQueue()

No

No relevant notes

dpiConn_newMsgProps()

No

No relevant notes

dpiConn_newQueue()

No

No relevant notes

dpiConn_newTempLob()

Yes

No relevant notes

dpiConn_newVar()

No

No relevant notes

dpiConn_ping()

Yes

No relevant notes

dpiConn_prepareStmt()

No

No relevant notes

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

No relevant notes

dpiConn_setAction()

No

No relevant notes

dpiConn_setCallTimeout()

No

No relevant notes

dpiConn_setClientIdentifier()

No

No relevant notes

dpiConn_setClientInfo()

No

No relevant notes

dpiConn_setCurrentSchema()

No

No relevant notes

dpiConn_setDbOp()

No

No relevant notes

dpiConn_setEcontextId()

No

No relevant notes

dpiConn_setExternalName()

No

No relevant notes

dpiConn_setInternalName()

No

No relevant notes

dpiConn_setModule()

No

No relevant notes

dpiConn_setOciAttr()

No

No relevant notes

dpiConn_setStmtCacheSize()

No

No relevant notes

dpiConn_shutdownDatabase()

Yes

No relevant notes

dpiConn_startupDatabase()

Yes

No relevant notes

dpiConn_startupDatabaseWithPfile()

Yes

No relevant notes

dpiConn_subscribe()

Yes

No relevant notes

dpiConn_tpcBegin()

Yes

No relevant notes

dpiConn_tpcCommit()

Yes

No relevant notes

dpiConn_tpcEnd()

Yes

No relevant notes

dpiConn_tpcForget()

Yes

No relevant notes

dpiConn_tpcPrepare()

Yes

No relevant notes

dpiConn_tpcRollback()

Yes

No relevant notes

dpiConn_unsubscribe()

Yes

No relevant notes

dpiContext_createWithParams()

No

No relevant notes

dpiContext_destroy()

No

No relevant notes

dpiContext_freeStringList()

No

No relevant notes

dpiContext_getClientVersion()

No

No relevant notes

dpiContext_getError()

No

No relevant notes

dpiContext_initCommonCreateParams()

No

No relevant notes

dpiContext_initConnCreateParams()

No

No relevant notes

dpiContext_initPoolCreateParams()

No

No relevant notes

dpiContext_initSodaOperOptions()

No

No relevant notes

dpiContext_initSubscrCreateParams()

No

No relevant notes

dpiData_getBool()

No

No relevant notes

dpiData_getBytes()

No

No relevant notes

dpiData_getDouble()

No

No relevant notes

dpiData_getFloat()

No

No relevant notes

dpiData_getInt64()

No

No relevant notes

dpiData_getIntervalDS()

No

No relevant notes

dpiData_getIntervalYM()

No

No relevant notes

dpiData_getIsNull()

No

No relevant notes

dpiData_getJson()

No

No relevant notes

dpiData_getJsonArray()

No

No relevant notes

dpiData_getJsonObject()

No

No relevant notes

dpiData_getLOB()

No

No relevant notes

dpiData_getObject()

No

No relevant notes

dpiData_getStmt()

No

No relevant notes

dpiData_getTimestamp()

No

No relevant notes

dpiData_getUint64()

No

No relevant notes

dpiData_setBool()

No

No relevant notes

dpiData_setBytes()

No

No relevant notes

dpiData_setDouble()

No

No relevant notes

dpiData_setFloat()

No

No relevant notes

dpiData_setInt64()

No

No relevant notes

dpiData_setIntervalDS()

No

No relevant notes

dpiData_setIntervalYM()

No

No relevant notes

dpiData_setLOB()

No

No relevant notes

dpiData_setNull()

No

No relevant notes

dpiData_setObject()

No

No relevant notes

dpiData_setStmt()

No

No relevant notes

dpiData_setTimestamp()

No

No relevant notes

dpiData_setUint64()

No

No relevant notes

dpiDeqOptions_addRef()

No

No relevant notes

dpiDeqOptions_getCondition()

No

No relevant notes

dpiDeqOptions_getConsumerName()

No

No relevant notes

dpiDeqOptions_getCorrelation()

No

No relevant notes

dpiDeqOptions_getMode()

No

No relevant notes

dpiDeqOptions_getMsgId()

No

No relevant notes

dpiDeqOptions_getNavigation()

No

No relevant notes

dpiDeqOptions_getTransformation()

No

No relevant notes

dpiDeqOptions_getVisibility()

No

No relevant notes

dpiDeqOptions_getWait()

No

No relevant notes

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

No relevant notes

dpiDeqOptions_setConsumerName()

No

No relevant notes

dpiDeqOptions_setCorrelation()

No

No relevant notes

dpiDeqOptions_setDeliveryMode()

No

No relevant notes

dpiDeqOptions_setMode()

No

No relevant notes

dpiDeqOptions_setMsgId()

No

No relevant notes

dpiDeqOptions_setNavigation()

No

No relevant notes

dpiDeqOptions_setTransformation()

No

No relevant notes

dpiDeqOptions_setVisibility()

No

No relevant notes

dpiDeqOptions_setWait()

No

No relevant notes

dpiEnqOptions_addRef()

No

No relevant notes

dpiEnqOptions_getTransformation()

No

No relevant notes

dpiEnqOptions_getVisibility()

No

No relevant notes

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

No relevant notes

dpiEnqOptions_setTransformation()

No

No relevant notes

dpiEnqOptions_setVisibility()

No

No relevant notes

dpiJson_addRef()

No

No relevant notes

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

No relevant notes

dpiJson_setValue()

No

No relevant notes

dpiLob_addRef()

No

No relevant notes

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

No relevant notes

dpiLob_copy()

Yes

No relevant notes

dpiLob_getBufferSize()

No

No relevant notes

dpiLob_getChunkSize()

Yes

No relevant notes

dpiLob_getDirectoryAndFileName()

No

No relevant notes

dpiLob_getFileExists()

Yes

No relevant notes

dpiLob_getIsResourceOpen()

Yes

No relevant notes

dpiLob_getSize()

Yes

No relevant notes

dpiLob_getType()

No

No relevant notes

dpiLob_openResource()

Yes

No relevant notes

dpiLob_readBytes()

Yes

No relevant notes

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

No relevant notes

dpiLob_setFromBytes()

Yes

No relevant notes

dpiLob_trim()

Yes

No relevant notes

dpiLob_writeBytes()

Yes

No relevant notes

dpiMsgProps_addRef()

No

No relevant notes

dpiMsgProps_getCorrelation()

No

No relevant notes

dpiMsgProps_getDelay()

No

No relevant notes

dpiMsgProps_getDeliveryMode()

No

No relevant notes

dpiMsgProps_getEnqTime()

No

No relevant notes

dpiMsgProps_getExceptionQ()

No

No relevant notes

dpiMsgProps_getExpiration()

No

No relevant notes

dpiMsgProps_getMsgId()

No

No relevant notes

dpiMsgProps_getNumAttempts()

No

No relevant notes

dpiMsgProps_getOriginalMsgId()

No

No relevant notes

dpiMsgProps_getPayload()

No

No relevant notes

dpiMsgProps_getPayloadJson()

No

No relevant notes

dpiMsgProps_getPriority()

No

No relevant notes

dpiMsgProps_getState()

No

No relevant notes

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

No relevant notes

dpiMsgProps_setDelay()

No

No relevant notes

dpiMsgProps_setExceptionQ()

No

No relevant notes

dpiMsgProps_setExpiration()

No

No relevant notes

dpiMsgProps_setOriginalMsgId()

No

No relevant notes

dpiMsgProps_setPayloadBytes()

No

No relevant notes

dpiMsgProps_setPayloadJson()

No

No relevant notes

dpiMsgProps_setPayloadObject()

No

No relevant notes

dpiMsgProps_setPriority()

No

No relevant notes

dpiMsgProps_setRecipients()

No

No relevant notes

dpiObject_addRef()

No

No relevant notes

dpiObject_appendElement()

No

No relevant notes

dpiObject_copy()

No

No relevant notes

dpiObject_deleteElementByIndex()

No

No relevant notes

dpiObject_getAttributeValue()

No

No relevant notes

dpiObject_getElementExistsByIndex()

No

No relevant notes

dpiObject_getElementValueByIndex()

No

No relevant notes

dpiObject_getFirstIndex()

No

No relevant notes

dpiObject_getLastIndex()

No

No relevant notes

dpiObject_getNextIndex()

No

No relevant notes

dpiObject_getPrevIndex()

No

No relevant notes

dpiObject_getSize()

No

No relevant notes

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

No relevant notes

dpiObject_setElementValueByIndex()

No

No relevant notes

dpiObject_trim()

No

No relevant notes

dpiObjectAttr_addRef()

No

No relevant notes

dpiObjectAttr_getInfo()

No

No relevant notes

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

No relevant notes

dpiObjectType_createObject()

No

No relevant notes

dpiObjectType_getAttributes()

No

No relevant notes

dpiObjectType_getInfo()

No

No relevant notes

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

No relevant notes

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

No relevant notes

dpiPool_getEncodingInfo()

No

No relevant notes

dpiPool_getGetMode()

No

No relevant notes

dpiPool_getMaxLifetimeSession()

No

No relevant notes

dpiPool_getMaxSessionsPerShard()

No

No relevant notes

dpiPool_getOpenCount()

No

No relevant notes

dpiPool_getPingInterval()

No

No relevant notes

dpiPool_getSodaMetadataCache()

No

No relevant notes

dpiPool_getStmtCacheSize()

No

No relevant notes

dpiPool_getTimeout()

No

No relevant notes

dpiPool_getWaitTimeout()

No

No relevant notes

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

No relevant notes

dpiPool_setGetMode()

No

No relevant notes

dpiPool_setMaxLifetimeSession()

No

No relevant notes

dpiPool_setMaxSessionsPerShard()

No

No relevant notes

dpiPool_setPingInterval()

No

No relevant notes

dpiPool_setSodaMetadataCache()

No

No relevant notes

dpiPool_setStmtCacheSize()

No

No relevant notes

dpiPool_setTimeout()

No

No relevant notes

dpiPool_setWaitTimeout()

No

No relevant notes

dpiQueue_addRef()

No

No relevant notes

dpiQueue_deqMany()

Yes

No relevant notes

dpiQueue_deqOne()

Yes

No relevant notes

dpiQueue_enqMany()

Yes

No relevant notes

dpiQueue_enqOne()

Yes

No relevant notes

dpiQueue_getDeqOptions()

No

No relevant notes

dpiQueue_getEnqOptions()

No

No relevant notes

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

No relevant notes

dpiRowid_getStringValue()

No

No relevant notes

dpiRowid_release()

No

No relevant notes

dpiSodaColl_addRef()

No

No relevant notes

dpiSodaColl_createIndex()

Yes

No relevant notes

dpiSodaColl_drop()

Yes

No relevant notes

dpiSodaColl_dropIndex()

Yes

No relevant notes

dpiSodaColl_find()

Yes

No relevant notes

dpiSodaColl_findOne()

Yes

No relevant notes

dpiSodaColl_getDataGuide()

Yes

No relevant notes

dpiSodaColl_getDocCount()

Yes

No relevant notes

dpiSodaColl_getMetadata()

No

No relevant notes

dpiSodaColl_getName()

No

No relevant notes

dpiSodaColl_insertMany()

Yes

No relevant notes

dpiSodaColl_insertManyWithOptions()

Yes

No relevant notes

dpiSodaColl_insertOne()

Yes

No relevant notes

dpiSodaColl_insertOneWithOptions()

Yes

No relevant notes

dpiSodaColl_listIndexes()

Yes

No relevant notes

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

No relevant notes

dpiSodaColl_replaceOne()

Yes

No relevant notes

dpiSodaColl_save()

Yes

No relevant notes

dpiSodaColl_saveWithOptions()

Yes

No relevant notes

dpiSodaColl_truncate()

Yes

No relevant notes

dpiSodaCollCursor_addRef()

No

No relevant notes

dpiSodaCollCursor_close()

No

No relevant notes

dpiSodaCollCursor_getNext()

Yes

No relevant notes

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

No relevant notes

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

No relevant notes

dpiSodaDb_createJsonDocument()

No

No relevant notes

dpiSodaDb_getCollections()

Yes

No relevant notes

dpiSodaDb_getCollectionNames()

Yes

No relevant notes

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

No relevant notes

dpiSodaDoc_getContent()

No

No relevant notes

dpiSodaDoc_getCreatedOn()

No

No relevant notes

dpiSodaDoc_getIsJson()

No

No relevant notes

dpiSodaDoc_getJsonContent()

No

No relevant notes

dpiSodaDoc_getKey()

No

No relevant notes

dpiSodaDoc_getLastModified()

No

No relevant notes

dpiSodaDoc_getMediaType()

No

No relevant notes

dpiSodaDoc_getVersion()

No

No relevant notes

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

No relevant notes

dpiSodaDocCursor_close()

No

No relevant notes

dpiSodaDocCursor_getNext()

Yes

No relevant notes

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

No relevant notes

dpiStmt_bindByName()

No

No relevant notes

dpiStmt_bindByPos()

No

No relevant notes

dpiStmt_bindValueByName()

No

No relevant notes

dpiStmt_bindValueByPos()

No

No relevant notes

dpiStmt_close()

No

No relevant notes

dpiStmt_define()

No

No relevant notes

dpiStmt_defineValue()

No

No relevant notes

dpiStmt_deleteFromCache()

No

No relevant notes

dpiStmt_execute()

Yes

No relevant notes

dpiStmt_executeMany()

Yes

No relevant notes

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

No relevant notes

dpiStmt_getBatchErrors()

No

No relevant notes

dpiStmt_getBindCount()

No

No relevant notes

dpiStmt_getBindNames()

No

No relevant notes

dpiStmt_getFetchArraySize()

No

No relevant notes

dpiStmt_getImplicitResult()

No

No relevant notes

dpiStmt_getInfo()

No

No relevant notes

dpiStmt_getLastRowid()

No

No relevant notes

dpiStmt_getNumQueryColumns()

No

No relevant notes

dpiStmt_getOciAttr()

No

No relevant notes

dpiStmt_getPrefetchRows()

No

No relevant notes

dpiStmt_getQueryInfo()

No

No relevant notes

dpiStmt_getQueryValue()

No

No relevant notes

dpiStmt_getRowCount()

No

No relevant notes

dpiStmt_getRowCounts()

No

No relevant notes

dpiStmt_getSubscrQueryId()

No

No relevant notes

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

No relevant notes

dpiStmt_setFetchArraySize()

No

No relevant notes

dpiStmt_setOciAttr()

No

No relevant notes

dpiStmt_setPrefetchRows()

No

No relevant notes

dpiSubscr_addRef()

No

No relevant notes

dpiSubscr_prepareStmt()

No

No relevant notes

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

No relevant notes

dpiVar_copyData()

No

No relevant notes

dpiVar_getNumElementsInArray()

No

No relevant notes

dpiVar_getReturnedData()

No

No relevant notes

dpiVar_getSizeInBytes()

No

No relevant notes

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

No relevant notes

dpiVar_setFromLob()

No

No relevant notes

dpiVar_setFromObject()

No

No relevant notes

dpiVar_setFromRowid()

No

No relevant notes

dpiVar_setFromStmt()

No

No relevant notes

dpiVar_setNumElementsInArray()

No

No relevant notes