16
More OCI Relational Functions

This chapter completes description of the OCI relational functions started in the last chapter. It includes information about calling OCI functions in your application, along with detailed descriptions of each function call. This chapter contains the following sections:

Introduction to the Relational Functions

This chapter completes descriptions of the OCI relational function calls. It continues from the last chapter. The function calls for manipulating objects are described in the next three chapters.

See Also:

For information about return codes and error handling, refer to the section "Error Handling"

Function Syntax

For each function, the following information is listed:

Purpose

A brief description of the action performed by the function.

Syntax

The function declaration.

Parameters

A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has three possible values, as described below.

Mode	Description
IN	A parameter that passes data to the OCI
OUT	A parameter that receives data from the OCI on this call
IN/OUT	A parameter that passes data on the call and receives data on the return from this or a subsequent call.

Comments

More detailed information about the function (if available). This may include restrictions on the use of the function, or other information that might be useful when using the function in an application.

Example

A complete or partial code example demonstrating the use of the function call being described. Not all function descriptions include an example.

Related Functions

A list of related function calls.

Calling OCI Functions

Unlike earlier versions of the OCI, in release 8 you cannot pass -1 for the string length parameter of a null-terminated string.

When you pass string lengths as parameters, do not include the null terminator byte in the length. The OCI does not expect strings to be null-terminated.

Buffer lengths that are OCI parameters are in bytes, except the amount parameters in some LOB calls, which are in characters.

Server Round-trips for LOB Functions

For a table showing the number of server round- trips required for individual OCI LOB functions, refer to Appendix C, "OCI Function Server Round-trips".

LOB Functions

This section describes the LOB functions.

Table 16-1 LOB Functions

Function	Purpose
OCIDurationBegin()	Start user duration for temporary LOB
OCIDurationEnd()	End user duration for temporary LOB
OCILobAppend()	Append one LOB to another
OCILobAssign()	Assign one LOB locator to another
OCILobCharSetForm()	Get character set form from LOB locator
OCILobCharSetId()	Get character set ID from LOB locator
OCILobClose()	Close a previously opened LOB
OCILobCopy()	Copy all or part of one LOB to another
OCILobCreateTemporary()	Create a temporary LOB
OCILobDisableBuffering()	Turn LOB buffering off
OCILobEnableBuffering()	Turn LOB buffering on
OCILobErase()	Erase a portion of a LOB
OCILobFileClose()	Close a previously opened FILE
OCILobFileCloseAll()	Close all previously opened files
OCILobFileExists()	Check if a file exists on the server
OCILobFileGetName()	Get directory alias and file NaMe from the LOB locator
OCILobFileIsOpen()	Check if file on server is open using this locator
OCILobFileOpen()	Open a FILE
OCILobFileSetName()	Set directory alias and file name in the LOB locator
OCILobFlushBuffer()	Flush the LOB buffer
OCILobFreeTemporary()	Free a temporary LOB
OCILobGetChunkSize()	Get the chunk size of a LOB
OCILobGetLength()	Get length of a LOB
OCILobIsEqual()	Compare two LOB locators for Equality
OCILobIsOpen()	Check to see if a LOB is open
OCILobIsTemporary()	Determine if a given LOB is a temporary LOB
OCILobLoadFromFile()	Load a LOB from a FILE
OCILobLocatorAssign()	Assigns one LOB locator to another
OCILobLocatorIsInit()	Check to see if a LOB locator is initialized
OCILobOpen()	Open a LOB
OCILobRead()	Read a portion of a LOB
OCILobTrim()	Truncate a LOB
OCILobWrite()	Write into a LOB
OCILobWriteAppend()	Write data beginning at the end of a LOB

Note the following for parameters in the OCI LOB calls:

For fixed-width client-side character sets, the offset and amount parameters are always in characters for CLOBs and NCLOBs, and in bytes for BLOBs and BFILEs.
For varying-width client-side character sets, these rules generally apply:
- amount (amtp) parameter - When the amount parameter refers to the server-side LOB, the amount is in characters. When the amount parameter refers to the client-side buffer, the amount is in bytes. For more information, see individual LOB calls, such as OCILobGetLength(), OCILobRead(), and OCILobWrite().
- offset (offset) parameter - Regardless of whether the client-side character set is varying-width, the offset parameter is always in characters for CLOBs and NCLOBs and in bytes for BLOBs and BFILEs.
For many of the LOB operations, regardless of the client-side character set, the amount parameter is in characters for CLOBs and NCLOBs. These LOB operations include OCILobCopy(), OCILobErase(), OCILobGetLength(), OCILobLoadFromFile(), and OCILobTrim(). All these operations refer to the amount of LOB data on the server.

A streaming operation means that the LOB is read or written in pieces. Streaming can be implemented using a polling mechanism or by registering a user-defined callback.

16 More OCI Relational Functions