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

• Relational Function Round-trips

• LOB Function Round-trips

• Object and Cache Function Round-trips

• Describe Operation Round-trips

• Datatype Mapping and Manipulation Function Round-trips

• Other Local Functions

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

Other Local Functions

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

Table C-6 Locally Processed Functions  

Local Function Name	Notes
OCIAttrGet()
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