More OCI Relational Functions, 9 of 106

OCIStmtSetPieceInfo()

Purpose

Sets piece information for a piecewise operation.

Syntax

sword OCIStmtSetPieceInfo ( dvoid             *hndlp,
                            ub4               type,
                            OCIError          *errhp,
                            CONST dvoid       *bufp,
                            ub4               *alenp, 
                            ub1               piece,
                            CONST dvoid       *indp, 
                            ub2               *rcodep );

Parameters

hndlp (IN/OUT)

The bind/define handle.

type (IN)

Type of the handle.

errhp (OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

bufp (IN/OUT)

A pointer to a storage containing the data value or the piece when it is an IN bind variable, otherwise bufp is a pointer to storage for getting a piece or a value for OUT binds and define variables. For named data types or REFs, a pointer to the object or REF is returned.

alenp (IN/OUT)

The length of the piece or the value.

piece (IN)

The piece parameter. Valid values:

OCI_ONE_PIECE
OCI_FIRST_PIECE
OCI_NEXT_PIECE
OCI_LAST_PIECE

This parameter is used for IN bind variables only.

indp (IN/OUT)

Indicator. A pointer to a sb2 value or pointer to an indicator structure for named data types (SQLT_NTY) and REFs (SQLT_REF), that is, *indp is either an sb2 or a dvoid * depending upon the data type.

rcodep (IN/OUT)

Return code.

Comments

When an execute call returns OCI_NEED_DATA to get a dynamic IN/OUT bind value or piece, OCIStmtSetPieceInfo() sets the piece information: the buffer, the length, which piece is currently being processed, the indicator, and the return code for this column.

See Also:

For more information about using OCIStmtSetPieceInfo() see the section "Runtime Data Allocation and Piecewise Operations"

Related Functions

OCIAttrGet(), OCIAttrSet(), OCIStmtExecute(), OCIStmtFetch(), OCIStmtGetPieceInfo()

LOB Functions

This section describes the LOB functions.

Table 16-2 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.