E
OCI Function Server Roundtrips

This appendix provides information about server roundtrips 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

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

LOB Function Roundtrips

Table E-1 lists the server roundtrips incurred by the OCILob*() calls. Information about the read and write calls is listed after the table.

Table E-1 ***Server Roundtrips for OCILob*() Calls***

Function	# of Server Roundtrips
OCILobAppend()	1
OCILobAssign()	0
OCILobCharSetForm()	0
OCILobCharSetId()	0
OCILobCopy()	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
OCILobGetLength()	1
OCILobIsEqual()	0
OCILobLoadFromFile()	1
OCILobLocatorIsInit()	0
OCILobTrim()	1

OCILobRead()

The number of roundtrips required depends on how the call is used:

In polling mode without callbacks, 1 roundtrip required per OCILobRead() call.
In polling mode with callbacks, 1 roundtrip is required, and then the callback function is called until all data is read.
If data is read in one piece using the input buffer, 1 roundtrip is required.

OCILobWrite()

The number of roundtrips required depends on how the call is used:

In polling mode without callbacks, 1 roundtrip required per OCILobWrite() call.
In polling mode with callbacks, 1 roundtrip is required, and then the callback function is called until all data is written.
If data is written in one piece using the input buffer, 1 roundtrip is required.

Object and Cache Function Roundtrips

Table E-2 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 E-2 Server Roundtrips for Object and Cache Functions

Function	# of Server Roundtrips
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 Roundtrips

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

Table E-3 Server Roundtrips for Describe Operations

Function	# of Server Roundtrips
OCIDescribeAny()	1 roundtrip to get the REF of the type descriptor object
OCIAttrGet()	2 roundtrips to describe a type if the type objects are not in the object cache 1 roundtrip for each collection element, or each type attribute, method, or method argument descriptor. 1 more roundtrip 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.
OCIAttrGet()
OCIParamGet()	0

Datatype Mapping and Manipulation Function Roundtrips

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

Table E-4 Server Roundtrips for Datatype Manipulation Functions

Function	# of Server Roundtrips
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

Other Local Functions

The following functions are local and do not require a server roundtrip:

Table E-5 Locally Processed Functions

Local Function Name	Notes
OCIAttrGet()
OCIAttrSet()
OCIBindByName()
OCIBindByPos()
OCIBindDynamic()
OCIBindObject()
OCIBindArrayOfStruct()
OCIDefineByPos()
OCIDefineDynamic()
OCIDefineArrayOfStruct()
OCIDefineObject()
OCIDescriptorAlloc()
OCIDescriptorFree()
OCIEnvInit()
OCIErrorGet()
OCIHandleAlloc()
OCIHandleFree()
OCILdaToSvcCtx()
OCISvcCtxToLda()
OCIStmtGetBindInfo()
OCIStmtPrepare()
OCIStmtGetBindInfo()
OCIStmtPrepare()
OCIStmtFetch()	may be local if retrieving pre-fetched rows

EOCI Function Server Roundtrips