C
OCI Function Server Round-trips

This appendix provides information about server round-trips incurred during various OCI calls. This information can be useful to programmers when determining the most efficient way to accomplish a particular task in an application.

The appendix contains the following sections:

Overview of Server Round-trips

This appendix provides information about server round-trips incurred during various OCI calls. This information can be useful when determining the most efficient way to accomplish a particular task in an application.

Relational Function Round-trips

The number of server round-trips required by OCI relational functions are listed in Table C-1:

Table C-1 Server Round-trips for Relational Operations

Function	# of Server Round-trips
`OCIBreak()`	1
`OCIEnvCreate()`	0
`OCIEnvInit()`	0
`OCIErrorGet()`	0
`OCIInitialize()`	0
`OCILdaToSvcCtx()`	0
`OCILogoff()`	1
`OCILogon()`	1
`OCIPasswordChange()`
`OCIReset()`	0
`OCIServerAttach()`	1
`OCIServerDetach()`	1
`OCIServerVersion()`	1
`OCISessionBegin()`	1
`OCISessionEnd()`	1
`OCISvcCtxToLda()`	0
`OCITerminate()`	1
`OCIStmtExecute()`	1
`OCIStmtFetch()`	0 or 1
`OCIStmtGetPieceInfo()`	1
`OCIStmtPrepare()`	0
`OCIStmtSetPieceInfo()`	0
`OCITransCommit()`	1
`OCITransDetach()`	1
`OCITransForget()`	1
`OCITransPrepare()`	1
`OCItransRollback()`	1
`OCITransStart()`	1
`OCIUserCallbackGet()`	0
`OCIUserCallbackregister()`	0

LOB Function Round-trips

Table C-2 lists the server round-trips incurred by the OCILob*() calls. Information about the read and write calls is listed after the table.

Table C-2 ***Server Round-trips for OCILob*() Calls***

Function	# of Server Round-trips
`OCILobAppend()`	1
`OCILobAssign()`	0
`OCILobCharSetForm()`	0
`OCILobCharSetId()`	0
`OCILobCopy()`	1
`OCILobCreateTemporary()`	1
`OCILobDisableBuffering()`	0
`OCILobEnableBuffering()`	0
`OCILobErase()`	1
`OCILobFileClose()`	1
`OCILobFileCloseAll()`	1
`OCILobFileExists()`	1
`OCILobFileGetName()`	0
`OCILobFileIsOpen()`	1
`OCILobFileOpen()`	1
`OCILobFileSetName()`	0
`OCILobFlushBuffer()`	1 per modified page in the buffer for this LOB
`OCILobFreeTemporary()`	1
`OCILobGetLength()`	1
`OCILobIsEqual()`	0
`OCILobIsTemporary()`	0
`OCILobLoadFromFile()`	1
`OCILobLocatorAssign()`	1 round-trip if the source and/or the destination locator refers to a temporary LOB
`OCILobLocatorIsInit()`	0
`OCILobTrim()`	1
`OCILobOpen()`	1
`OCILobClose()`	1
`OCILobIsOpen()`	1
`OCILobGetChunkSize()`	1

Object and Cache Function Round-trips

Table C-3 lists the number of server round-trips required for the object and cache functions. These values assume the cache is in a warm state, meaning that the type descriptor objects required by the application have been loaded.

Table C-3 Server Round -trips for Object and Cache Functions

Function	# of Server Round-trips
`OCIObjectNew()`	0
`OCIObjectPin()`	1; 0 if the desired object is already in cache
`OCIObjectUnpin()`	0
`OCIObjectPinCountReset()`	0
`OCIObjectLock()`	1
`OCIObjectMarkUpdate()`	0
`OCIObjectUnmark()`	0
`OCIObjectUnmarkByRef()`	0
`OCIObjectFree()`	0
`OCIObjectMarkDelete()`	0
`OCIObjectMarkDeleteByRef()`	0
`OCIObjectFlush()`	1
`OCIObjectRefresh()`	1
`OCIObjectCopy()`	0
`OCIObjectGetTypeRef()`	0
`OCIObjectGetObjectRef()`	0
`OCIObjectGetInd()`	0
`OCIObjectExists()`	0
`OCIObjectIsLocked()`	0
`OCIObjectIsDirty()`	0
`OCIObjectPinTable()`	1
`OCIObjectArrayPin()`	1
`OCICacheFlush()`	1
`OCICacheRefresh()`	1
`OCICacheUnpin()`	0
`OCICacheFree()`	0
`OCICacheUnmark()`	0

Describe Operation Round-trips

The number of server round-trips required by OCIDescribeAny(), OCIAttrGet(), and OCIParamGet() are listed in Table C-4:

Table C-4 Server Round-trips for Describe Operations

Function	# of Server Round-trips
`OCIDescribeAny()`	1 round-trip to get the `REF` of the type descriptor object
`OCIAttrGet()`	2 round-trips to describe a type if the type objects are not in the object cache 1 round-trip for each collection element, or each type attribute, method, or method argument descriptor. 1 more round-trip if using OCI_ATTR_TYPE_NAME, or OCI_ATTR_SCHEMA_NAME on the collection element, type attribute, or method argument. 0 if all the type objects to be described are already in the object cache following the first `OCIAttrGet()` call.

`OCIParamGet()`	0

Datatype Mapping and Manipulation Function Round-trips

The number of round-trips for the datatype mapping and manipulation functions are listed in Table C-5. The asterisks in the table indicate that all functions with a particular prefix incur the same number of server round-trips. For example, OCINumberAdd(), OCINumberPower(), and OCINumberFromText() all incur zero server round-trips.

Table C-5 Server Round-trips for Datatype Manipulation Functions

Function	# of Server Round-trips
`OCINumber*()`	0
`OCIDate*()`	0
`OCIString*()`	0
`OCIRaw*()`	0
`OCIRef*()`	0
`OCIColl*()`	0; 1 if the collection is not loaded in the cache
`OCITable*()`	0; 1 if the nested table is not loaded in the cache
`OCIIter*()`	0; 1 if the collection is not loaded in the cache

Any Type and Data Function Round-trips

The number of server round-trips required by Any Type and Data functions are listed in Table C-6. The functions not listed do not generate any round-trips.

Table C-6 Server Round-trips for Any Type and Data Functions

Function	# of Server Round-trips
`OCIAnyDataAttrGet()`	0; 1 if the type information is not loaded in the cache
`OCIAnyDataAttrSet()`	0; 1 if the type information is not loaded in the cache
`OCIAnyDataCollGetElem()`	0; 1 if the type information is not loaded in the cache

Other Local Functions

The functions listed in Table C-7 are local and do not require a server round-trip:

Table C-7 Locally Processed Functions

Local Function Name	Notes
`OCIAttrGet()`	When describing an object type, this call does make one round-trip to fetch the type descriptor object.
`OCIAttrSet()`
`OCIBindByName()`
`OCIBindByPos()`
`OCIBindDynamic()`
`OCIBindObject()`
`OCIBindArrayOfStruct()`
`OCIDefineByPos()`
`OCIDefineDynamic()`
`OCIDefineArrayOfStruct()`
`OCIDefineObject()`
`OCIDescriptorAlloc()`
`OCIDescriptorFree()`
`OCIEnvInit()`
`OCIEnvCreate()`
`OCIErrorGet()`
`OCIHandleAlloc()`
`OCIHandleFree()`
`OCILdaToSvcCtx()`
`OCISvcCtxToLda()`
`OCIStmtGetBindInfo()`
`OCIStmtPrepare()`
`OCIStmtGetBindInfo()`
`OCIStmtPrepare()`
`OCIStmtFetch()`	may be local if retrieving pre-fetched rows

C OCI Function Server Round-trips