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