DBMS_LOB

The DBMS_LOB package provides subprograms to operate on BLOBs, CLOBs, and NCLOBs, including temporary LOBs, in TimesTen Classic.

Note:

• TimesTen does not support DBMS_LOB subprograms intended specifically for BFILEs, SecureFiles (including Database File System features), or inserting or deleting data fragments in the middle of a LOB.

• DBMS_LOB procedures and functions are supported for both TimesTen LOBs and passthrough LOBs, which are LOBs in Oracle Database accessed through TimesTen and exposed as TimesTen LOBs. Note, however, that CREATETEMPORARY can only be used to create a temporary LOB in TimesTen. If a temporary passthrough LOB is created using some other mechanism, such as SQL, ISTEMPORARY and FREETEMPORARY can be used on that LOB.

  As with TimesTen local LOBs, a locator for a passthrough LOB does not remain valid past the end of the transaction.

  In addition to copying from one TimesTen LOB to another, COPY can copy from a TimesTen LOB to a passthrough LOB, from a passthrough LOB to a TimesTen LOB, or from one passthrough LOB to another passthrough LOB. An attempt to copy a passthrough LOB to a TimesTen LOB when the passthrough LOB is larger than the TimesTen LOB size limit results in an error. (COPY Procedures in Oracle TimesTen In-Memory Database PL/SQL Packages Reference provides examples for copying LOBs.)

  See Passthrough LOBs.

Table 7-1 describes the supported DBMS_LOB subprograms.

Table 7-1 DBMS_LOB Subprograms

Subprogram	Description
APPEND procedures	Appends the contents of the source LOB to the destination LOB.
CLOSE procedures	Closes a previously opened LOB.
COMPARE functions	Compares two entire LOBs or parts of two LOBs.
CONVERTTOBLOB procedure	Reads character data from a source CLOB or NCLOB instance, converts the character data to the specified character set, writes the converted data to a destination BLOB instance in binary format, and returns the new offsets.
CONVERTTOCLOB procedure	Takes a source BLOB instance, converts the binary data in the source instance to character data using the specified character set, writes the character data to a destination CLOB or NCLOB instance, and returns the new offsets.
COPY procedures	Copies all or part of the source LOB to the destination LOB.
CREATETEMPORARY procedures	Creates a temporary LOB in the temporary data region. Any of the durations supported by Oracle Database is permitted (SESSION, TRANSACTION, or CALL). In TimesTen, however, LOB duration cannot extend past the end of the transaction.
ERASE procedures	Erases all or part of a LOB.
FREETEMPORARY procedures	Frees a temporary LOB in the temporary data region.
GET_STORAGE_LIMIT functions	Returns the storage limit for the LOB type of the specified LOB.
GETCHUNKSIZE functions	In TimesTen, this simply returns the value 32 KB for interoperability. Do not rely on this value for performance tuning.
GETLENGTH functions	Returns the length of the LOB value, in bytes for a BLOB or characters for a CLOB or NCLOB.
INSTR functions	Returns the matching position of the nth occurrence of the pattern in the LOB.
ISOPEN functions	Checks to see if the LOB was already opened using the input locator.
ISTEMPORARY functions	Checks whether the locator is pointing to a temporary LOB.
OPEN procedures	Opens a LOB (persistent or temporary) in the indicated mode, read/write or read-only. Note: Opening a LOB is similar conceptually, but not technically, to opening a file. Opening a LOB is more like a hint regarding resources to be required.
READ procedures	Reads data from the LOB starting at the specified offset.
SUBSTR functions	Returns part of the LOB value starting at the specified offset.
TRIM procedures	Trims the LOB value to the specified shorter length.
WRITE procedures	Writes data to the LOB from a specified offset.
WRITEAPPEND procedures	Writes a buffer to the end of a LOB.