DBMS_LOB dbms_lob tips


Call now: 252-767-6166 

 

 Home
  E-mail Us

 Oracle

Articles

New Oracle Articles


 Oracle

Training
 Oracle

Tips


 Oracle

Forum
 Class

Catalog


 Remote

DBA
 Oracle

Tuning
 Emergency

911
 RAC

Support
 Apps

Support
 Analysis
 Design
 Implementation
 Oracle

Support


 SQL Tuning
 Security

 Oracle

UNIX
 Oracle

Linux
 Monitoring
 Remote s
upport
 Remote

plans
 Remote

services
 Application

Server

 Applications
 Oracle

Forms
 Oracle

Portal
 App

Upgrades
  SQL

Server
  Oracle Concepts
 Software Support
 Remote

S upport

 

 Development  

 Implementation


 Consulting Staff
 Consulting

Prices
 Help

Wanted!

 

 Oracle Posters
 Oracle Books

 Oracle

Scripts

 Ion

 Excel-DB  

Don Burleson Blog  

 

 

 


 

 

 

 

 


Oracle dbms_lob tips

Oracle Database Tips by Donald Burleson


About
Oracle dbms_lob

Oracle provides the
DBMS_LOB package which is used to access and
manipulate LOB values in both internal or
external storage locations.

dbms_lob Routines That Can Modify
BLOB, CLOB, And NCLOB Values

 

Routines That Read Or
Examine LOB Values in dbms_lob

 

dbms_lob Read-Only Routines Specific
To Bfiles

 

dbms_lob Datatypes

Parameters for the DBMS_LOB
routines use the datatypes:


dbms_lob
examples


The following SQL statements show the rule
conditions for the above mentioned rules:

SELECT
dbms_lob.substr(rule_condition,dbms_lob.getlength(rule_condition),1)
rule_condition FROM dba_rules where
rule_name = ‘NY270’
/

RULE_CONDITION
————————————————–|
((:dml.get_object_owner () = ‘NY2’) and
:dml.is_nul
l_tag() = ‘Y’ and
:dml.get_source_database_name ()

= ‘DNYTST10.WORLD’ )

SELECT
dbms_lob.substr(rule_condition,dbms_lob.getlength(rule_condition),1)
rule_condition
FROM dba_rules where rule_name = ‘NY271’
/

GRAPHICS_DBA
BEGIN dbms_lob.read (:1, :2, :3, :4);
END;2121 1 0 10251 488

 

Below is a list containing some of the main
procedures and functions that are presented in this package and what
they do.

 



n 


isopen
:
 This function checks to see
if the LOB was already opened using the input locator.



n 



createtemporary
:

 
The procedure



createtemporary

creates a
temporary CLOB or BLOB and its corresponding index in the user
default temporary tablespace.



n 


instr
: 
Used to return the matching position of the nth
occurrence of the pattern in the LOB.



n 


getlength
: 
Used to
get the length of specified LOB.



n 


copy
:
Copies part or
all of a source internal LOB to a destination internal LOB.



n 


writeappend
: 
Writes a
specified amount of data to the end of an internal LOB.



n 


trim
: 
Trims the
value of the internal LOB to the length specified by
the newlen parameter.

 

Here is how to perform, search and replace in a
CLOB with some procedures of the dbms_lob
package. First, create the test table and insert some rows.

 



<


 
Code  
2.4 – dbms_lob.sql

Conn pkg/pkg#123

 

Connected to Oracle 11g Enterprise Edition
Release 11.1.0.6.0

Connected as pkg

 

drop table

  
tab_dbms_lob_search

purge

/

 

Table dropped

 

create table tab_dbms_lob_search(

  
clob_id number,

  
c clob

);

 

Table created

 

insert into

  
tab_dbms_lob_search

values

  
1,’Oracle Database 7i,8i,9i and 10g’)

/

 

1 row inserted

insert into

  
tab_dbms_lob_search

values

  
(2,‘Oracle Database 7i,8i,9i
and 10g’)

/

 

1 row inserted

 

commit

/

 

Commit complete



 

Let’s create a procedure that uses the
dbms_lob package to search and replace
text within a LOB (CLOB, BLOB).

 



<
Code  
2.5 – search_n_replace_text_lob.sql

create or replace procedure
  
proc_dbms_lob_search_rep(

lob_local  
in out clob,

       
srch_string varchar2,

       
rep_string 
varchar2) as

temp_clob     
clob;

end_offset    
integer := 1;

start_offset  
integer := 1;

nth     
number := 1;

rep_string_len number := length(rep_string);

temp_clob_len 
number := 0;

lob_local_len 
number := 0;

  

begin

    
if lob_local is NULL then

      
raise_application_error(-20001, ‘LOB is empty. You need to
execute inserts first!’);

    
end if;

  

 

    
–The function isopen check to see if the LOB was already
opened using the input locator

    
if dbms_lob.isopen(

          
lob_local) = 0

    
dbms_output.put_line(‘ LOB is open!’);

 

    
then

      
null;

    
dbms_output.put_line(‘ LOB is closed!’);

 

    
end if;

  

    
–The procedure create temporary creates a temporary CLOB

    
dbms_lob.createtemporary(

       
temp_clob,

       
TRUE,

       
dbms_lob.session);



LOOP

      
— The function instr returns the matching position of the
nth    
occurrence of

      
–the pattern in the LOB, starting from the offset you
specify.

 

     
 
end_offset :=
dbms_lob.instr
(lob_local, srch_string, 1, nth);

      
if end_offset = 0

  
then

        
temp_clob_len :=
dbms_lob.getlength
(temp_clob);

        
lob_local_len :=
dbms_lob.getlength
(lob_local) – start_offset + 1;

       

        
if lob_local_len > 0

        
then

        
–The procedure copy copies all, or a part of, a source
internal LOB to a destination internal LOB.

          
dbms_lob.copy(

             
temp_clob,

             
lob_local,

             
lob_local_len,

             
temp_clob_len + 1,

             
start_offset);

        
end if;

        
exit;

      
end if;

      
–The function getlength gets the length of the specified
LOB.

      
temp_clob_len := dbms_lob.getlength(temp_clob);

      
if (end_offset – start_offset) > 0

      
then

        
dbms_lob.copy(

           
temp_clob,

           
lob_local,

           
(end_offset – start_offset),

           
temp_clob_len + 1,

           
start_offset);

      
end if;

      
start_offset := end_offset + length(srch_string);

      
nth   
:= nth + 1;

  

      
if rep_string is not null then

     

  
–The procedure writeappend writes a specified amount of data
to the end of an internal LOB.

 

        
dbms_lob.writeappend(

           
temp_clob,

           
rep_string_len,

           
rep_string);

      
end if;

    
end loop;

    
if length(srch_string) > length(rep_string) then

      
–The procedure trim trims the value of the internal LOB to
the length you specify in the

      
–newlen parameter

      
dbms_lob.trim(

         
lob_loc => lob_local,

         
newlen  => 
dbms_lob.getlength(

                       
temp_clob)

      
);

    
end if;

    
dbms_lob.copy(

       
lob_local,

       
temp_clob,

       
dbms_lob.getlength(temp_clob),
1, 1);

  
end;

  /

 

Procedure created

 

–Check for errors

show errors

 

No errors for procedure
pkg.proc_dbms_lob_search_rep

 

This procedure executed the following steps: 

 



1.      
First, it finds the position of the
first occurrence of the searched text.

 



2.      
Then it creates a temporary NCLOB,
copies everything from the original NCLOB to it up to the point
where it found the text to be replaced, and appends the new text.

 



3.      
Now, it trims the temporary NCLOB to
keep only what came after the word to replace.

 

Now let’s look at the table results to see how
they are before the search and replace process.

 

select

  
*

from

  
tab_dbms_lob_search;

 

  
CLOB_ID C

———-
———————————————————

        
1 Oracle Database 7i,8i,9i
and 10g

        
2 Oracle Database 7i,8i,9i
and 10g

 

Call the procedure to change the value for the
first row only (clob_id=1).

 

declare

     
lob_local clob;

   
begin

     
select c

        
into lob_local

     
from

tab_dbms_lob_search

     
where

clob_id = 1

     
for update;

     
proc_dbms_lob_search_rep(

        
lob_local  
=> lob_local,

        
srch_string => 
and 10g’,

        
rep_string  => 
‘ ,10g and 11g ‘);

    
commit;

  
end;

 /



 

The results below show the new replaced text.

 

select

  
*

from

  
tab_dbms_lob_search

/


 

CLOB_ID  
C

——
———————————————————-

        
1 Oracle Database 7i,8i,9i ,10g and 11g

        
2 Oracle Database 7i,8i,9i and 10g

 

In the preceding example, the following
procedures and functions were used: 
isopen,
createtemporary,
instr,
getlength,
copy
and
trim.

 

 

See these related
notes on Oracle dbms_lob

Oracle_dbms_lob.writeappend to join
BLOB columns

Oracle_datapump dbms_lob.filegetname

dbms_lob.converttoclob Tips

dbms_lob.getlength gives incorrect length

dbms_lob.getlength tips

 



For more dbms_lob tips
see:

Advanced Oracle
Utilities: The
Definitive Reference
by Rampant TechPress is
written by top Oracle database
experts (Bert Scalzo,  Donald
Burleson, and Steve Callan). 

Buy
direct from the
publisher and save 30%!


 

 

��

 

 

 

Oracle Training at Sea

 

 

 

 

oracle dba poster

 

 

Follow us on Twitter  

 

Oracle performance tuning software  

 

Oracle Linux poster

 

 
 

 

Burleson is the American Team

Note:

This Oracle

documentation was created as a support and Oracle training reference for use by our

DBA performance tuning consulting professionals. 

Feel free to ask questions on our

Oracle forum .

Verify

experience!

Anyone

considering using the services of an Oracle support expert should

independently investigate their credentials and experience, and not rely on

advertisements and self-proclaimed expertise. All legitimate Oracle experts

publish

their Oracle

qualifications .

Errata?

 Oracle technology is changing and we

strive to update our BC Oracle support information.  If you find an error

or have a suggestion for improving our content, we would appreciate your

feedback.  Just 

e-mail:

 

and include the URL for the page.


                    


Burleson Consulting


The Oracle of

Database Support

Oracle

Performance Tuning

Remote DBA Services


 

Copyright © 1996 –  2017

All rights reserved by

Burleson

Oracle ®

is the registered trademark of Oracle Corporation.

Remote Emergency Support provided by
Conversational

 

Go to main content

59/206

52 DBMS_LOB

The DBMS_LOB package provides subprograms to operate on BLOBs, CLOBs, NCLOBs, BFILEs, and temporary LOBs. You can use DBMS_LOB to access and manipulation specific parts of a LOB or complete LOBs.

This chapter contains the following topics:


Using DBMS_LOB


Overview

DBMS_LOB can read and modify BLOBs, CLOBs, and NCLOBs; it provides read-only operations for BFILEs. The bulk of the LOB operations are provided by this package.


Security Model

This package must be created under SYS. Operations provided by this package are performed under the current calling user, not under the package owner SYS.

Any DBMS_LOB subprogram called from an anonymous PL/SQL block is executed using the privileges of the current user. Any DBMS_LOB subprogram called from a stored procedure is executed using the privileges of the owner of the stored procedure.

When creating the procedure, users can set the AUTHID to indicate whether they want definer’s rights or invoker’s rights. For example:

CREATE PROCEDURE proc1 authid definer ... 

or

CREATE PROCEDURE proc1 authid current_user ...

You can provide secure access to BFILEs using the DIRECTORY feature discussed in BFILENAME function in the Oracle Database Application Developer’s Guide – Large Objects and the Oracle Database SQL Reference .

For information about the security model pertaining to temporary LOBs, see Operational Notes .


Constants

DBMS_LOB defines the following constants:

file_readonly CONSTANT BINARY_INTEGER := 0;
lob_readonly CONSTANT BINARY_INTEGER := 0;
lob_readwrite CONSTANT BINARY_INTEGER := 1;
lobmaxsize CONSTANT INTEGER := 18446744073709551615;
call CONSTANT PLS_INTEGER := 12;
session CONSTANT PLS_INTEGER := 10;

Datatypes

The DBMS_LOB package uses the datatypes shown in Table 52-1 .

Table 52-1 Datatypes Used by DBMS_LOB

TypeDescription

BLOB

Source or destination binary LOB.

RAW

Source or destination RAW buffer (used with BLOB).

CLOB

Source or destination character LOB (including NCLOB).

VARCHAR2

Source or destination character buffer (used with CLOB and NCLOB).

INTEGER

Specifies the size of a buffer or LOB, the offset into a LOB, or the amount to access.

BFILE

Large, binary object stored outside the database.

The DBMS_LOB package defines no special types.

An NCLOB is a CLOB for holding fixed-width and varying-width, multibyte national character sets.

The clause ANY_CS in the specification of DBMS_LOB subprograms for CLOBs enables the CLOB type to accept a CLOB or NCLOB locator variable as input.


Rules and Limits

General Rules and Limits

Rules and Limits Specific to External Files (BFILEs)

 

In general, you should ensure that files opened in a PL/SQL block using DBMS_LOB are closed before normal or abnormal termination of the block.

Maximum LOB Size

The maximum size of a LOB supported by the database is equal to the value of the db_block_size initialization parameter times the value 4294967295. This allows for a maximum LOB size ranging from 8 terabytes to 128 terabytes.

Maximum Buffer Size

The maximum buffer size, 32767 bytes, is represented by maxbufsize.


Operational Notes

All DBMS_LOB subprograms work based on LOB locators. For the successful completion of DBMS_LOB subprograms, you must provide an input locator that represents a LOB that already exists in the database tablespaces or external file system. See also Chapter 1 of Oracle Database Application Developer’s Guide – Large Objects.

To use LOBs in your database, you must first use SQL data definition language (DDL) to define the tables that contain LOB columns.

Internal LOBs

To populate your table with internal LOBs after LOB columns are defined in a table, you use the SQL data manipulation language (DML) to initialize or populate the locators in the LOB columns.

External LOBs

For an external LOB (BFILE) to be represented by a LOB locator, you must:

Once you have completed these tasks, you can insert or update a row containing a LOB column using the given LOB locator.

After the LOBs are defined and created, you can then SELECT from a LOB locator into a local PL/SQL LOB variable and use this variable as an input parameter to DBMS_LOB for access to the LOB value.

For details on the different ways to do this, you must refer to the section of the Oracle Database Application Developer’s Guide – Large Objects that describes “Accessing External LOBs (BFILEs).”

Temporary LOBs

The database supports the definition, creation, deletion, access, and update of temporary LOBs. Your temporary tablespace stores the temporary LOB data. Temporary LOBs are not permanently stored in the database. Their purpose is mainly to perform transformations on LOB data.

For temporary LOBs, you must use the OCI, PL/SQL, or another programmatic interface to create or manipulate them. Temporary LOBs can be either BLOBs, CLOBs, or NCLOBs.

A temporary LOB is empty when it is created. By default, all temporary LOBs are deleted at the end of the session in which they were created. If a process dies unexpectedly or if the database crashes, then temporary LOBs are deleted, and the space for temporary LOBs is freed.

There is also an interface to let you group temporary LOBs together into a logical bucket. The duration represents this logical store for temporary LOBs. Each temporary LOB can have separate storage characteristics, such as CACHE/ NOCACHE. There is a default store for every session into which temporary LOBs are placed if you don’t specify a specific duration. Additionally, you are able to perform a free operation on durations, which causes all contents in a duration to be freed.

There is no support for consistent read (CR), undo, backup, parallel processing, or transaction management for temporary LOBs. Because CR and rollbacks are not supported for temporary LOBs, you must free the temporary LOB and start over again if you encounter an error.

Because CR, undo, and versions are not generated for temporary LOBs, there is potentially a performance impact if you assign multiple locators to the same temporary LOB. Semantically, each locator should have its own copy of the temporary LOB.

A copy of a temporary LOB is created if the user modifies the temporary LOB while another locator is also pointing to it. The locator on which a modification was performed now points to a new copy of the temporary LOB. Other locators no longer see the same data as the locator through which the modification was made. A deep copy was not incurred by permanent LOBs in these types of situations, because CR snapshots and version pages enable users to see their own versions of the LOB cheaply.

You can gain pseudo-REF semantics by using pointers to locators in OCI and by having multiple pointers to locators point to the same temporary LOB locator, if necessary. In PL/SQL, you must avoid using more than one locator for each temporary LOB. The temporary LOB locator can be passed by reference to other procedures.

Because temporary LOBs are not associated with any table schema, there are no meanings to the terms in-row and out-of-row temporary LOBs. Creation of a temporary LOB instance by a user causes the engine to create and return a locator to the LOB data. The PL/SQL DBMS_LOB package, PRO*C, OCI, and other programmatic interfaces operate on temporary LOBs through these locators just as they do for permanent LOBs.

There is no support for client side temporary LOBs. All temporary LOBs reside in the server.

Temporary LOBs do not support the EMPTY_BLOB or EMPTY_CLOB functions that are supported for permanent LOBs. The EMPTY_BLOB function specifies the fact that the LOB is initialized, but not populated with any data.

A temporary LOB instance can only be destroyed by using OCI or the DBMS_LOB package by using the appropriate FREETEMPORARY or OCIDurationEnd statement.

A temporary LOB instance can be accessed and modified using appropriate OCI and DBMS_LOB statements, just as for regular permanent internal LOBs. To make a temporary LOB permanent, you must explicitly use the OCI or DBMS_LOB COPY command, and copy the temporary LOB into a permanent one.

Security is provided through the LOB locator. Only the user who created the temporary LOB is able to see it. Locators are not expected to be able to pass from one user’s session to another. Even if someone did pass a locator from one session to another, they would not access the temporary LOBs from the original session. Temporary LOB lookup is localized to each user’s own session. Someone using a locator from somewhere else is only able to access LOBs within his own session that have the same LOB ID. Users should not try to do this, but if they do, they are not able to affect anyone else’s data.

The database keeps track of temporary LOBs for each session in a v$ view called V$TEMPORARY_LOBS, which contains information about how many temporary LOBs exist for each session. V$ views are for DBA use. From the session, the database can determine which user owns the temporary LOBs. By using V$TEMPORARY_LOBS in conjunction with DBA_SEGMENTS, a DBA can see how much space is being used by a session for temporary LOBs. These tables can be used by DBAs to monitor and guide any emergency cleanup of temporary space used by temporary LOBs.

The following notes are specific to temporary LOBs:

  1. All functions in DBMS_LOB return NULL if any of the input parameters are NULL. All procedures in DBMS_LOB raise an exception if the LOB locator is input as NULL.

  2. Operations based on CLOBs do not verify if the character set IDs of the parameters (CLOB parameters, VARCHAR2 buffers and patterns, and so on) match. It is the user’s responsibility to ensure this.

  3. Data storage resources are controlled by the DBA by creating different temporary tablespaces. DBAs can define separate temporary tablespaces for different users, if necessary.

  4. Temporary LOBs still adhere to value semantics in order to be consistent with permanent LOBs and to try to conform to the ANSI standard for LOBs. As a result, each time a user does an OCILobLocatatorAssign, or the equivalent assignment in PL/SQL, the database makes a copy of the temporary LOB.

    Each locator points to its own LOB value. If one locator is used to create a temporary LOB, and then is assigned to another LOB locator using OCILobLOcatorAssign in OCI or through an assignment operation in PL/SQL, then the database copies the original temporary LOB and causes the second locator to point to the copy.

    In order for users to modify the same LOB, they must go through the same locator. In OCI, this can be accomplished fairly easily by using pointers to locators and assigning the pointers to point to the same locator. In PL/SQL, the same LOB variable must be used to update the LOB to get this effect.

    The following example shows a place where a user incurs a copy, or at least an extra round-trip to the server.

    DECLARE a blob; b blob;
    BEGIN dbms_lob.createtemporary(b, TRUE); -- the following assignment results in a deep copy a := b;
    END; 

    The PL/SQL compiler makes temporary copies of actual arguments bound to OUT or IN OUT parameters. If the actual parameter is a temporary LOB, then the temporary copy is a deep (value) copy.

    The following PL/SQL block illustrates the case where the user incurs a deep copy by passing a temporary LOB as an IN OUT parameter.

    DECLARE a blob; procedure foo(parm IN OUT blob) is BEGIN ... END;
    BEGIN dbms_lob.createtemporary(a, TRUE); -- the following call results in a deep copy of the blob a foo(a);
    END; 

    To minimize deep copies on PL/SQL parameter passing, use the NOCOPY compiler hint where possible.

    The duration parameter passed to dbms_lob.createtemporary() is a hint. The duration of the new temp LOB is the same as the duration of the locator variable in PL/SQL. For example, in the preceding program block, the program variable a has the duration of the residing frame. Therefore at the end of the block, memory of a will be freed at the end of the function.

    If a PL/SQL package variable is used to create a temp LOB, it will have the duration of the package variable, which has a duration of SESSION.

    BEGIN y clob; END;
    /
    BEGIN dbms_lob.createtemporary(package.y, TRUE);
    END; 

Exceptions

Table 52-2 DBMS_LOB Exceptions

ExceptionCodeDescription

INVALID_ARGVAL

21560

The argument is expecting a nonNULL, valid value but the argument value passed in is NULL, invalid, or out of range.

ACCESS_ERROR

22925

You are trying to write too much data to the LOB: LOB size is limited to 4 gigabytes.

NOEXIST_DIRECTORY

22285

The directory leading to the file does not exist.

NOPRIV_DIRECTORY

22286

The user does not have the necessary access privileges on the directory or the file for the operation.

INVALID_DIRECTORY

22287

The directory used for the current operation is not valid if being accessed for the first time, or if it has been modified by the DBA since the last access.

OPERATION_FAILED

22288

The operation attempted on the file failed.

UNOPENED_FILE

22289

The file is not open for the required operation to be performed.

OPEN_TOOMANY

22290

The number of open files has reached the maximum limit.

NO_DATA_FOUND

 

EndofLob indicator for looping read operations. This is not a hard error.

VALUE_ERROR

6502

PL/SQL error for invalid values to subprogram’s parameters.


Summary of DBMS_LOB Subprograms

Table 52-3 DBMS_LOB Package Subprograms

SubprogramDescription

APPEND Procedures

Appends the contents of the source LOB to the destination LOB

CLOSE Procedure

Closes a previously opened internal or external 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, 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, 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 BLOB or CLOB and its corresponding index in the user’s default temporary tablespace

ERASE Procedures

Erases all or part of a LOB

FILECLOSE Procedure

Closes the file

FILECLOSEALL Procedure

Closes all previously opened files

FILEEXISTS Function

Checks if the file exists on the server

FILEGETNAME Procedure

Gets the directory object name and file name

FILEISOPEN Function

Checks if the file was opened using the input BFILE locators

FILEOPEN Procedure

Opens a file

FREETEMPORARY Procedures

Frees the temporary BLOB or CLOB in the user’s default temporary tablespace

GETCHUNKSIZE Functions

Returns the amount of space used in the LOB chunk to store the LOB value

GETLENGTH Functions

Gets the length of the LOB value

GET_STORAGE_LIMIT

Returns the storage limit for LOBs in your database configuration

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 if the locator is pointing to a temporary LOB

LOADBLOBFROMFILE Procedure

Loads BFILE data into an internal BLOB

LOADCLOBFROMFILE Procedure

Loads BFILE data into an internal CLOB

LOADFROMFILE Procedure

Loads BFILE data into an internal LOB

OPEN Procedures

Opens a LOB (internal, external, or temporary) in the indicated mode

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


APPEND Procedures

This procedure appends the contents of a source internal LOB to a destination LOB. It appends the complete source LOB.

There are two overloaded APPEND procedures.

Syntax

DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB);
DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_lob IN CLOB CHARACTER SET dest_lob%CHARSET);

Parameters

Table 52-4 APPEND Procedure Parameters

ParameterDescription

dest_lob

Locator for the internal LOB to which the data is to be appended.

src_lob

Locator for the internal LOB from which the data is to be read.

Exceptions

Table 52-5 APPEND Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Either the source or the destination LOB is NULL.

Usage Notes

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.


CLOSE Procedure

This procedure closes a previously opened internal or external LOB.

Syntax

DBMS_LOB.CLOSE ( lob_loc IN OUT NOCOPY BLOB);
DBMS_LOB.CLOSE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS);
DBMS_LOB.CLOSE ( file_loc IN OUT NOCOPY BFILE); 

Parameters

Table 52-6 CLOSE Procedure Parameters

ParameterDescription

lob_loc

LOB locator. For more information, see Operational Notes .

Exceptions

No error is returned if the BFILE exists but is not opened. An error is returned if the LOB is not open.

Usage Notes

CLOSE requires a round-trip to the server for both internal and external LOBs. For internal LOBs, CLOSE triggers other code that relies on the close call, and for external LOBs (BFILEs), CLOSE actually closes the server-side operating system file.

It is not mandatory that you wrap all LOB operations inside the Open/Close APIs. However, if you open a LOB, you must close it before you commit or rollback the transaction; an error is produced if you do not. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

It is an error to commit the transaction before closing all opened LOBs that were opened by the transaction. When the error is returned, the openness of the open LOBs is discarded, but the transaction is successfully committed. Hence, all the changes made to the LOB and non-LOB data in the transaction are committed, but the domain and function-based indexes are not updated. If this happens, you should rebuild the functional and domain indexes on the LOB column.


COMPARE Functions

This function compares two entire LOBs or parts of two LOBs.

Syntax

DBMS_LOB.COMPARE ( lob_1 IN BLOB, lob_2 IN BLOB, amount IN INTEGER := 4294967295, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER;
DBMS_LOB.COMPARE ( lob_1 IN CLOB CHARACTER SET ANY_CS, lob_2 IN CLOB CHARACTER SET lob_1%CHARSET, amount IN INTEGER := 4294967295, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER;
DBMS_LOB.COMPARE ( lob_1 IN BFILE, lob_2 IN BFILE, amount IN INTEGER, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER;

Pragmas

pragma restrict_references(COMPARE, WNDS, WNPS, RNDS, RNPS);

Parameters

Table 52-7 COMPARE Function Parameters

ParameterDescription

lob_1

LOB locator of first target for comparison.

lob_2

LOB locator of second target for comparison.

amount

Number of bytes (for BLOBs) or characters (for CLOBs) to compare.

offset_1

Offset in bytes or characters on the first LOB (origin: 1) for the comparison.

offset_2

Offset in bytes or characters on the first LOB (origin: 1) for the comparison.

Return Values

Usage Notes

You can only compare LOBs of the same datatype (LOBs of BLOB type with other BLOBs, and CLOBs with CLOBs, and BFILEs with BFILEs). For BFILEs, the file must be already opened using a successful FILEOPEN operation for this operation to succeed.

COMPARE returns zero if the data exactly matches over the range specified by the offset and amount parameters. Otherwise, a nonzero INTEGER is returned.

For fixed-width n-byte CLOBs, if the input amount for COMPARE is specified to be greater than (4294967295/n), then COMPARE matches characters in a range of size (4294967295/n), or Max(length(clob1), length(clob2)), whichever is lesser.

Exceptions

Table 52-8 COMPARE Function Exceptions for BFILE operations

ExceptionDescription

UNOPENED_FILE

File was not opened using the input locator.

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.

INVALID_OPERATION

File does not exist, or you do not have access privileges on the file.


CONVERTTOBLOB Procedure

This procedure reads character data from a source CLOB or NCLOB instance, converts the character data to the character set you specify, writes the converted data to a destination BLOB instance in binary format, and returns the new offsets. You can use this interface with any combination of persistent or temporary LOB instances as the source or destination.

Syntax

DBMS_LOB.CONVERTTOBLOB( dest_lob IN OUT NOCOPY BLOB, src_clob IN CLOB CHARACTER SET ANY_CS, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER, blob_csid IN NUMBER, lang_context IN OUT INTEGER, warning OUT INTEGER); 

Parameters

Table 52-9 CONVERTTOBLOB Procedure Parameters

ParameterDescription

dest_lob

LOB locator of the destination LOB instance.

src_blob

LOB locator of the source LOB instance.

amount

Number ofcharacters to convert from the source LOB.

If you want to copy the entire LOB, pass the constant DBMS_LOB.LOBMAXSIZE. If you pass any other value, it must be less than or equal to the size of the LOB.

dest_offset

(IN)Offset in bytes in the destination LOB for the start of the write. Specify a value of 1 to start at the beginning of the LOB.

(OUT)The new offset in bytes after the end of the write.

src_offset

(IN)Offset in characters in the source LOB for the start of the read.

(OUT)Offset in characters in the source LOB right after the end of the read.

blob_csid

Desired character set ID of the converted data.

lang_context

(IN) Language context, such as shift status, for the current conversion.

(OUT) The language context at the time when the current conversion is done.

This information is returned so you can use it for subsequent conversions without losing or misinterpreting any source data. For the very first conversion, or if do not care, use the default value of zero.

warning

(OUT) Warning message. This parameter indicates when something abnormal happened during the conversion. You are responsible for checking the warning message.

Currently, the only possible warning is — inconvertible character. This occurs when the character in the source cannot be properly converted to a character in destination. The default replacement character (for example, ‘?’) is used in place of the inconvertible character. The return value of this error message is defined as the constant warn_inconvertible_char in the DBMS_LOB package.

Usage Notes

Preconditions

Before calling the CONVERTTOBLOB procedure, the following preconditions must be met:

Constants and Defaults

All parameters are required. You must pass a variable for each OUT or IN OUT parameter. You must pass either a variable or a value for each IN parameter.

Table 52-10 gives a summary of typical values for each parameter. The first column lists the parameter, the second column lists the typical value, and the last column describes the result of passing the value. Note that constants are used for some values. These constants are defined in the dbmslob.sql package specification file.

Table 52-10 DBMS_LOB.CONVERTTOBLOB Typical Values

ParameterValueDescription

amount

LOBMAXSIZE (IN)

convert the entire file

dest_offset

1 (IN)

start from the beginning

src_offset

1 (IN)

start from the beginning

csid

DEFAULT_CSID (IN)

default CSID, use same CSID as source LOB

lang_context

DEFAULT_LANG_CTX (IN)

default language context

warning

NO_WARNING (OUT)

WARN_INCONVERTIBLE_CHAR (OUT)

no warning message, success

character in source cannot be properly converted

General Notes

You must specify the desired character set for the destination LOB in the blob_csid parameter. You can pass a zero value for blob_csid. When you do so, the database assumes that the desired character set is the same as the source LOB character set, and performs a binary copy of the data—no character set conversion is performed.

You must specify the offsets for both the source and destination LOBs, and the number of bytes to copy from the source LOB. The amount and src_offset values are in characters and the dest_offset is in bytes. To convert the entire LOB, you can specify LOBMAXSIZE for the amount parameter.

Exceptions

Table 52-11 gives possible exceptions this procedure can throw. The first column lists the exception string and the second column describes the error conditions that can cause the exception.

Table 52-11 CONVERTTOBLOB Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or INVALID.

INVALID_ARGVAL

One or more of the following:

src_offset or dest_offset < 1.

src_offset or dest_offset > LOBMAXSIZE.

amount < 1.

amount > LOBMAXSIZE.


CONVERTTOCLOB Procedure

This procedure takes a source BLOB instance, converts the binary data in the source instance to character data using the character set you specify, writes the character data to a destination CLOB or NCLOB instance, and returns the new offsets. You can use this interface with any combination of persistent or temporary LOB instances as the source or destination.

Syntax

DBMS_LOB.CONVERTTOCLOB( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_blob IN BLOB, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER, blob_csid IN NUMBER, lang_context IN OUT INTEGER, warning OUT INTEGER);

Parameters

Table 52-12 CONVERTTOCLOB Procedure Parameters

ParameterDescription

dest_lob

LOB locator of the destination LOB instance.

src_blob

LOB locator of the source LOB instance.

amount

Number of bytes to convert from the source LOB.

If you want to copy the entire BLOB, pass the constant DBMS_LOB.LOBMAXSIZE. If you pass any other value, it must be less than or equal to the size of the BLOB.

dest_offset

(IN) Offset in characters in the destination LOB for the start of the write. Specify a value of 1 to start at the beginning of the LOB.

(OUT) The new offset in characters after the end of the write. This offset always points to the beginning of the first complete character after the end of the write.

src_offset

(IN) Offset in bytes in the source LOB for the start of the read.

(OUT) Offset in bytes in the source LOB right after the end of the read.

blob_csid

Desired character set ID of the converted data.

lang_context

(IN) Language context, such as shift status, for the current conversion.

(OUT) The language context at the time when the current conversion is done.

This information is returned so you can use it for subsequent conversions without losing or misinterpreting any source data. For the very first conversion, or if do not care, use the default value of zero.

warning

Warning message. This parameter indicates when something abnormal happened during the conversion. You are responsible for checking the warning message.

Currently, the only possible warning is — inconvertible character. This occurs when the character in the source cannot be properly converted to a character in destination. The default replacement character (for example, ‘?’) is used in place of the inconvertible character. The return value of this error message is defined as the constant warn_inconvertible_char in the DBMS_LOB package.

Usage Notes

Preconditions

Before calling the CONVERTTOCLOB procedure, the following preconditions must be met:

Constants and Defaults

All parameters are required. You must pass a variable for each OUT or IN OUT parameter. You must pass either a variable or a value for each IN parameter.

Table 52-13 gives a summary of typical values for each parameter. The first column lists the parameter, the second column lists the typical value, and the last column describes the result of passing the value. Note that constants are used for some values. These constants are defined in the dbmslob.sql package specification file.

Table 52-13 DBMS_LOB.CONVERTTOCLOB Typical Values

ParameterValueDescription

amount

LOBMAXSIZE (IN)

convert the entire file

dest_offset

1 (IN)

start from the beginning

src_offset

1 (IN)

start from the beginning

csid

DEFAULT_CSID (IN)

default CSID, use destination CSID

lang_context

DEFAULT_LANG_CTX (IN)

default language context

warning

NO_WARNING (OUT)

WARN_INCONVERTIBLE_CHAR (OUT)

no warning message, success

character in source cannot be properly converted

General Notes

You must specify the desired character set for the destination LOB in the blob_csid parameter. You can pass a zero value for blob_csid. When you do so, the database assumes that the BLOB contains character data in the same character set as the destination CLOB, and performs a binary copy of the data to the destination LOB, no character set conversion being performed.

You must specify the offsets for both the source and destination LOBs, and the number of bytes to copy from the source BLOB. The amount and src_offset values are in bytes and the dest_offset is in characters. To convert the entire BLOB, you can specify LOBMAXSIZE for the amount parameter.

Exceptions

Table 52-14 CONVERTTOCLOB Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or INVALID.

INVALID_ARGVAL

One or more of the following:

src_offset or dest_offset < 1.

src_offset or dest_offset > LOBMAXSIZE.

amount < 1.

amount > LOBMAXSIZE.


COPY Procedures

This procedure copies all, or a part of, a source internal LOB to a destination internal LOB. You can specify the offsets for both the source and destination LOBs, and the number of bytes or characters to copy.

Syntax

DBMS_LOB.COPY ( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB, amount IN INTEGER, dest_offset IN INTEGER := 1, src_offset IN INTEGER := 1);
DBMS_LOB.COPY ( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_lob IN CLOB CHARACTER SET dest_lob%CHARSET, amount IN INTEGER, dest_offset IN INTEGER := 1, src_offset IN INTEGER := 1);

Parameters

Table 52-15 COPY Procedure Parameters

ParameterDescription

dest_lob

LOB locator of the copy target.

src_lob

LOB locator of source for the copy.

amount

Number of bytes (for BLOBs) or characters (for CLOBs) to copy.

dest_offset

Offset in bytes or characters in the destination LOB (origin: 1) for the start of the copy.

src_offset

Offset in bytes or characters in the source LOB (origin: 1) for the start of the copy.

Exceptions

Table 52-16  COPY Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or invalid.

INVALID_ARGVAL

Either:

src_offset or dest_offset < 1

src_offset or dest_offset > LOBMAXSIZE

amount < 1

amount > LOBMAXSIZE

Usage Notes

If the offset you specify in the destination LOB is beyond the end of the data currently in this LOB, then zero-byte fillers or spaces are inserted in the destination BLOB or CLOB respectively. If the offset is less than the current length of the destination LOB, then existing data is overwritten.

It is not an error to specify an amount that exceeds the length of the data in the source LOB. Thus, you can specify a large amount to copy from the source LOB, which copies data from the src_offset to the end of the source LOB.

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.


CREATETEMPORARY Procedures

This procedure creates a temporary BLOB or CLOB and its corresponding index in your default temporary tablespace.

Syntax

DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY BLOB, cache IN BOOLEAN, dur IN PLS_INTEGER := 10);
DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, cache IN BOOLEAN, dur IN PLS_INTEGER := 10);

Parameters

Table 52-17 CREATETEMPORARY Procedure Parameters

ParameterDescription

lob_loc

LOB locator. For more information, see Operational Notes .

cache

Specifies if LOB should be read into buffer cache or not.

dur

1 of 2 predefined duration values (SESSION or CALL) which specifies a hint as to whether the temporary LOB is cleaned up at the end of the session or call.

If dur is omitted, then the session duration is used.


ERASE Procedures

This procedure erases an entire internal LOB or part of an internal LOB.

Syntax

DBMS_LOB.ERASE ( lob_loc IN OUT NOCOPY BLOB, amount IN OUT NOCOPY INTEGER, offset IN INTEGER := 1);
DBMS_LOB.ERASE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN OUT NOCOPY INTEGER, offset IN INTEGER := 1);

Parameters

Table 52-18 ERASE Procedure Parameters

ParameterDescription

lob_loc

Locator for the LOB to be erased.For more information, see Operational Notes .

amount

Number of bytes (for BLOBs or BFILES) or characters (for CLOBs or NCLOBs) to be erased.

offset

Absolute offset (origin: 1) from the beginning of the LOB in bytes (for BLOBs) or characters (CLOBs).

Usage Notes

When data is erased from the middle of a LOB, zero-byte fillers or spaces are written for BLOBs or CLOBs respectively.

The actual number of bytes or characters erased can differ from the number you specified in the amount parameter if the end of the LOB value is reached before erasing the specified number. The actual number of characters or bytes erased is returned in the amount parameter.

Exceptions

Table 52-19 ERASE Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any input parameter is NULL.

INVALID_ARGVAL

Either:

amount < 1 or amount > LOBMAXSIZE

offset < 1 or offset > LOBMAXSIZE

Usage Notes

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.


FILECLOSE Procedure

This procedure closes a BFILE that has already been opened through the input locator.

Syntax

DBMS_LOB.FILECLOSE ( file_loc IN OUT NOCOPY BFILE); 

Parameters

Table 52-20 FILECLOSE Procedure Parameters

ParameterDescription

file_loc

Locator for the BFILE to be closed.

Exceptions

Table 52-21 FILECLOSE Procedure Exceptions

ExceptionDescription

VALUE_ERROR

NULL input value for file_loc.

UNOPENED_FILE

File was not opened with the input locator.

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.

INVALID_OPERATION

File does not exist, or you do not have access privileges on the file.


FILECLOSEALL Procedure

This procedure closes all BFILEs opened in the session.

Syntax

DBMS_LOB.FILECLOSEALL; 

Exceptions

Table 52-22 FILECLOSEALL Procedure Exception

ExceptionDescription

UNOPENED_FILE

No file has been opened in the session.


FILEEXISTS Function

This function finds out if a given BFILE locator points to a file that actually exists on the server’s file system.

Syntax

DBMS_LOB.FILEEXISTS ( file_loc IN BFILE) RETURN INTEGER; 

Pragmas

pragma restrict_references(FILEEXISTS, WNDS, RNDS, WNPS, RNPS);

Parameters

Table 52-23 FILEEXISTS Function Parameter

ParameterDescription

file_loc

Locator for the BFILE.

Return Values

Table 52-24 FILEEXISTS Function Return Values

ReturnDescription

0

Physical file does not exist.

1

Physical file exists.

Exceptions

Table 52-25 FILEEXISTS Function Exceptions

ExceptionDescription

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.


FILEGETNAME Procedure

This procedure determines the directory object and filename, given a BFILE locator. This function only indicates the directory object name and filename assigned to the locator, not if the physical file or directory actually exists.

The maximum constraint values for the dir_alias buffer is 30, and for the entire path name, it is 2000.

Syntax

DBMS_LOB.FILEGETNAME ( file_loc IN BFILE, dir_alias OUT VARCHAR2, filename OUT VARCHAR2); 

Parameters

Table 52-26 FILEGETNAME Procedure Parameters

ParameterDescription

file_loc

Locator for the BFILE

dir_alias

Directory object name

filename

Name of the BFILE

Exceptions

Table 52-27 FILEGETNAME Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or INVALID.

INVALID_ARGVAL

dir_alias or filename are NULL.


FILEISOPEN Function

This function finds out whether a BFILE was opened with the given FILE locator.

Syntax

DBMS_LOB.FILEISOPEN ( file_loc IN BFILE) RETURN INTEGER; 

Pragmas

PRAGMA RESTRICT_REFERENCES(fileisopen, WNDS, RNDS, WNPS, RNPS);

Parameters

Table 52-28 FILEISOPEN Function Parameter

ParameterDescription

file_loc

Locator for the BFILE.

Return Values

INTEGER: 0 = file is not open, 1 = file is open

Usage Notes

If the input FILE locator was never passed to the FILEOPEN procedure, then the file is considered not to be opened by this locator. However, a different locator may have this file open. In other words, openness is associated with a specific locator.

Exceptions

Table 52-29 FILEISOPEN Function Exceptions

ExceptionDescription

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.


FILEOPEN Procedure

This procedure opens a BFILE for read-only access. BFILE data may not be written through the database.

Syntax

DBMS_LOB.FILEOPEN ( file_loc IN OUT NOCOPY BFILE, open_mode IN BINARY_INTEGER := file_readonly); 

Parameters

Table 52-30 FILEOPEN Procedure Parameters

ParameterDescription

file_loc

Locator for the BFILE.

open_mode

File access is read-only.

Exceptions

Table 52-31 FILEOPEN Procedure Exceptions

ExceptionDescription

VALUE_ERROR

file_loc or open_mode is NULL.

INVALID_ARGVAL

open_mode is not equal to FILE_READONLY.

OPEN_TOOMANY

Number of open files in the session exceeds session_max_open_files.

NOEXIST_DIRECTORY

Directory associated with file_loc does not exist.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.

INVALID_OPERATION

File does not exist, or you do not have access privileges on the file.


FREETEMPORARY Procedures

This procedure frees the temporary BLOB or CLOB in your default temporary tablespace.

Syntax

DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY BLOB);
DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS); 

Parameters

Table 52-32 FREETEMPORARY Procedure Parameters

ParameterDescription

lob_loc

LOB locator.For more information, see Operational Notes .

Usage Notes

After the call to FREETEMPORARY, the LOB locator that was freed is marked as invalid.

If an invalid LOB locator is assigned to another LOB locator using OCILobLocatorAssign in OCI or through an assignment operation in PL/SQL, then the target of the assignment is also freed and marked as invalid.


GET_STORAGE_LIMIT

The DBMS_LOB.GET_STORAGE_LIMIT function returns the LOB storage limit for your database configuration. The DBMS_LOB package supports LOB instances up to this storage limit in size.

Syntax

DBMS_LOB.GET_STORAGE_LIMIT RETURN INTEGER; 

Return Value

The value returned from this function is the maximum allowable size for LOB instances for your database configuration. The return value depends on your DB_BLOCK_SIZE initialization parameter setting and is calculated as (4 gigabytes minus 1) times the value of the DB_BLOCK_SIZE initialization parameter.

Usage

Note that BLOB instances are sized in bytes while CLOB and NCLOB instances are sized in characters.


GETCHUNKSIZE Functions

When creating the table, you can specify the chunking factor, which can be a multiple of database blocks. This corresponds to the chunk size used by the LOB data layer when accessing or modifying the LOB value. Part of the chunk is used to store system-related information, and the rest stores the LOB value.

This function returns the amount of space used in the LOB chunk to store the LOB value.

Syntax

DBMS_LOB.GETCHUNKSIZE ( lob_loc IN BLOB) RETURN INTEGER;
DBMS_LOB.GETCHUNKSIZE ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER; 

Pragmas

PRAGMA RESTRICT_REFERENCES(getchunksize, WNDS, RNDS, WNPS, RNPS); 

Parameters

Table 52-33 GETCHUNKSIZE Function Parameters

ParameterDescription

lob_loc

LOB locator. For more information, see Operational Notes .

Return Values

The value returned for BLOBs is in terms of bytes. The value returned for CLOBs is in terms of characters.

Usage Notes

Performance is improved if you enter read/write requests using a multiple of this chunk size. For writes, there is an added benefit, because LOB chunks are versioned, and if all writes are done on a chunk basis, then no extra or excess versioning is done or duplicated. You could batch up the WRITE until you have enough for a chunk, instead of issuing several WRITE calls for the same chunk.


GETLENGTH Functions

This function gets the length of the specified LOB. The length in bytes or characters is returned.

The length returned for a BFILE includes the EOF, if it exists. Any 0-byte or space filler in the LOB caused by previous ERASE or WRITE operations is also included in the length count. The length of an empty internal LOB is 0.

Syntax

DBMS_LOB.GETLENGTH ( lob_loc IN BLOB) RETURN INTEGER;
DBMS_LOB.GETLENGTH ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
DBMS_LOB.GETLENGTH ( file_loc IN BFILE) RETURN INTEGER;

Pragmas

pragma restrict_references(GETLENGTH, WNDS, WNPS, RNDS, RNPS);

Parameters

Table 52-34 GETLENGTH Function Parameter

ParameterDescription

file_loc

The file locator for the LOB whose length is to be returned.

Return Values

The length of the LOB in bytes or characters as an INTEGER. NULL is returned if the input LOB is NULL or if the input lob_loc is NULL. An error is returned in the following cases for BFILEs:


INSTR Functions

This function returns the matching position of the nth occurrence of the pattern in the LOB, starting from the offset you specify.

Syntax

DBMS_LOB.INSTR ( lob_loc IN BLOB, pattern IN RAW, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER;
DBMS_LOB.INSTR ( lob_loc IN CLOB CHARACTER SET ANY_CS, pattern IN VARCHAR2 CHARACTER SET lob_loc%CHARSET, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER;
DBMS_LOB.INSTR ( file_loc IN BFILE, pattern IN RAW, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER;

Pragmas

pragma restrict_references(INSTR, WNDS, WNPS, RNDS, RNPS);

Parameters

Table 52-35 INSTR Function Parameters

ParameterDescription

lob_loc

Locator for the LOB to be examined. For more information, see Operational Notes .

file_loc

The file locator for the LOB to be examined.

pattern

Pattern to be tested for. The pattern is a group of RAW bytes for BLOBs, and a character string (VARCHAR2) for CLOBs.The maximum size of the pattern is 16383 bytes.

offset

Absolute offset in bytes (BLOBs) or characters (CLOBs) at which the pattern matching is to start. (origin: 1)

nth

Occurrence number, starting at 1.

Return Values

Table 52-36 INSTR Function Return Values

ReturnDescription

INTEGER

Offset of the start of the matched pattern, in bytes or characters.

It returns 0 if the pattern is not found.

NULL

Either:

-any one or more of the IN parameters was NULL or INVALID.

offset < 1 or offset > LOBMAXSIZE.

nth < 1.

nth > LOBMAXSIZE.

Usage Notes

The form of the VARCHAR2 buffer (the pattern parameter) must match the form of the CLOB parameter. In other words, if the input LOB parameter is of type NCLOB, then the buffer must contain NCHAR data. Conversely, if the input LOB parameter is of type CLOB, then the buffer must contain CHAR data.

For BFILEs, the file must be already opened using a successful FILEOPEN operation for this operation to succeed.

Operations that accept RAW or VARCHAR2 parameters for pattern matching, such as INSTR, do not support regular expressions or special matching characters (as in the case of SQL LIKE) in the pattern parameter or substrings.

Exceptions

Table 52-37 INSTR Function Exceptions for BFILES

ExceptionDescription

UNOPENED_FILE

File was not opened using the input locator.

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.

INVALID_OPERATION

File does not exist, or you do not have access privileges on the file.


ISOPEN Functions

This function checks to see if the LOB was already opened using the input locator. This subprogram is for internal and external LOBs.

Syntax

DBMS_LOB.ISOPEN ( lob_loc IN BLOB) RETURN INTEGER;
DBMS_LOB.ISOPEN ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
DBMS_LOB.ISOPEN ( file_loc IN BFILE) RETURN INTEGER; 

Pragmas

PRAGMA RESTRICT_REFERENCES(isopen, WNDS, RNDS, WNPS, RNPS); 

Parameters

Table 52-38 ISOPEN Function Parameters

ParameterDescription

lob_loc

LOB locator. For more information, see Operational Notes .

file_loc

File locator.

Usage Notes

For BFILES, openness is associated with the locator. If the input locator was never passed to OPEN, the BFILE is not considered to be opened by this locator. However, a different locator may have opened the BFILE. More than one OPEN can be performed on the same BFILE using different locators.

For internal LOBs, openness is associated with the LOB, not with the locator. If locator1 opened the LOB, then locator2 also sees the LOB as open. For internal LOBs, ISOPEN requires a round-trip, because it checks the state on the server to see if the LOB is indeed open.

For external LOBs (BFILEs), ISOPEN also requires a round-trip, because that’s where the state is kept.


ISTEMPORARY Functions

This function determines whether a LOB instance is temporary.

Syntax

DBMS_LOB.ISTEMPORARY ( lob_loc IN BLOB) RETURN INTEGER;
DBMS_LOB.ISTEMPORARY ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;

Pragmas

PRAGMA RESTRICT_REFERENCES(istemporary, WNDS, RNDS, WNPS, RNPS);

Parameters

Table 52-39 ISTEMPORARY Procedure Parameters

ParameterDescription

lob_loc

LOB locator. For more information, see Operational Notes .

Return Values

This function returns TRUE in temporary if the locator is pointing to a temporary LOB. It returns FALSE otherwise.


LOADBLOBFROMFILE Procedure

This procedure loads data from BFILE to internal BLOB. This achieves the same outcome as LOADFROMFILE, and returns the new offsets.

Syntax

DBMS_LOB.LOADBLOBFROMFILE ( dest_lob IN OUT NOCOPY BLOB, src_bfile IN BFILE, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER);

Parameters

Table 52-40 LOADBLOBFROMFILE Procedure Parameters

ParameterDescriptionw

dest_lob

BLOB locator of the target for the load.

src_bfile

BFILE locator of the source for the load.

amount

Number of bytes to load from the BFILE. You can also use DBMS_LOB.LOBMAXSIZE to load until the end of the BFILE.

dest_offset

(IN) Offset in bytes in the destination BLOB (origin: 1) for the start of the write. (OUT) New offset in bytes in the destination BLOB right after the end of this write, which is also where the next write should begin.

src_offset

(IN) Offset in bytes in the source BFILE (origin: 1) for the start of the read.(OUT) Offset in bytes in the source BFILE right after the end of this read, which is also where the next read should begin.

Usage Notes

You can specify the offsets for both the source and destination LOBs, and the number of bytes to copy from the source BFILE. The amount and src_offset, because they refer to the BFILE, are in terms of bytes, and the dest_offset is in bytes for BLOBs.

If the offset you specify in the destination LOB is beyond the end of the data currently in this LOB, then zero-byte fillers or spaces are inserted in the destination BLOB. If the offset is less than the current length of the destination LOB, then existing data is overwritten.

There is an error if the input amount plus offset exceeds the length of the data in the BFILE (unless the amount specified is LOBMAXSIZE which you can specify to continue loading until the end of the BFILE is reached).

It is not mandatory that you wrap the LOB operation inside the OPEN/CLOSE operations. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the OPEN/CLOSE, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.

Constants and Defaults

There is no easy way to omit parameters. You must either declare a variable for IN/OUT parameter or provide a default value for the IN parameter. Here is a summary of the constants and the defaults that can be used.

Table 52-41 Suggested Values of the Parameter

ParameterDefault ValueDescription

amount

DBMSLOB.LOBMAXSIZE (IN)

Load the entire file

dest_offset

1 (IN)

start from the beginning

src_offset

1 (IN)

start from the beginning

Constants defined in DBMSLOB.SQL

lobmaxsize CONSTANT INTEGER := 4294967295;

Exceptions

Table 52-42 LOADBLOBFROMFILE Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or INVALID.

INVALID_ARGVAL

Either:

src_offset or dest_offset < 1.

src_offset or dest_offset > LOBMAXSIZE.

amount < 1.

amount > LOBMAXSIZE.


LOADCLOBFROMFILE Procedure

This procedure loads data from a BFILE to an internal CLOB/NCLOB with necessary character set conversion and returns the new offsets.

Syntax

DBMS_LOB.LOADCLOBFROMFILE ( dest_lob IN OUT NOCOPY BLOB, src_bfile IN BFILE, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER, bfile_csid IN NUMBER, lang_context IN OUT INTEGER, warning OUT INTEGER);

Parameters

Table 52-43 LOADCLOBFROMFILE Procedure Parameters

ParameterDescription

dest_lob

CLOB/NCLOB locator of the target for the load.

src_bfile

BFILE locator of the source for the load.

amount

Number of bytes to load from the BFILE. Use DBMS_LOB.LOBMAXSIZE to load until the end of the BFILE.

dest_offset

(IN) Offset in characters in the destination CLOB (origin: 1) for the start of the write. (OUT) The new offset in characters right after the end of this load, which is also where the next load should start. It always points to the beginning of the first complete character after the end of load. If the last character is not complete, offset goes back to the beginning of the partial character.

src_offset

(IN) Offset in bytes in the source BFILE (origin: 1) for the start of the read.(OUT)Offset in bytes in the source BFILE right after the end of this read, which is also where the next read should begin.

bfile_csid

Character set id of the source (BFILE) file.

lang_context

(IN) Language context, such as shift status, for the current load.

(OUT) The language context at the time when the current load stopped, and what the next load should be using if continuing loading from the same source. This information is returned to the user so that they can use it for the continuous load without losing or misinterpreting any source data. For the very first load or if do not care, simply use the default 0. The details of this language context is hidden from the user. One does not need to know what it is or what’s in it in order to make the call

warning

(OUT) Warning message. This indicates something abnormal happened during the loading. It may or may not be caused by the user’s mistake. The loading is completed as required, and it’s up to the user to check the warning message. Currently, the only possible warning is the inconvertible character. This happens when the character in the source cannot be properly converted to a character in destination, and the default replacement character (for example, ‘?’) is used in place. The message is defined as warn_inconvertible_char in DBMSLOB.

Usage Notes

You can specify the offsets for both the source and destination LOBs, and the number of bytes to copy from the source BFILE. The amount and src_offset, because they refer to the BFILE, are in terms of bytes, and the dest_offset is in characters for CLOBs.

If the offset you specify in the destination LOB is beyond the end of the data currently in this LOB, then zero-byte fillers or spaces are inserted in the destination CLOB. If the offset is less than the current length of the destination LOB, then existing data is overwritten.

There is an error if the input amount plus offset exceeds the length of the data in the BFILE (unless the amount specified is LOBMAXSIZE which you can specify to continue loading until the end of the BFILE is reached).

Note the following requirements:

Constants

Here is a summary of the constants and the suggested values that can be used.

Table 52-44 Suggested Values of the Parameter

ParameterSuggested ValueDescription

amount

DBMSLOB.LOBMAXSIZE (IN)

Load the entire file

dest_offset

1 (IN)

start from the beginning

src_offset

1 (IN)

start from the beginning

csid

0 (IN)

default csid, use destination csid

lang_context

0 (IN)

default language context

warning

0 (OUT)

no warning message, everything is ok

Constants defined in DBMSLOB.SQL

lobmaxsize CONSTANT INTEGER := 18446744073709551615;
warn_inconvertible_char CONSTANT INTEGER := 1;
default_csid CONSTANT INTEGER := 0;
default_lang_ctx CONSTANT INTEGER := 0;
no_warning CONSTANT INTEGER := 0;

Exceptions

Table 52-45 LOADCLOBFROMFILE Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or INVALID.

INVALID_ARGVAL

Either:

src_offset or dest_offset < 1.

src_offset or dest_offset > LOBMAXSIZE.

amount < 1.

amount > LOBMAXSIZE.


LOADFROMFILE Procedure

This procedure copies all, or a part of, a source external LOB (BFILE) to a destination internal LOB.

Syntax

DBMS_LOB.LOADFROMFILE ( dest_lob IN OUT NOCOPY BLOB, src_file IN BFILE, amount IN INTEGER, dest_offset IN INTEGER := 1, src_offset IN INTEGER := 1);

Parameters

Table 52-46 LOADFROMFILE Procedure Parameters

ParameterDescription

dest_lob

LOB locator of the target for the load.

src_file

BFILE locator of the source for the load.

amount

Number of bytes to load from the BFILE.

dest_offset

Offset in bytes or characters in the destination LOB (origin: 1) for the start of the load.

src_offset

Offset in bytes in the source BFILE (origin: 1) for the start of the load.

Usage Notes

You can specify the offsets for both the source and destination LOBs, and the number of bytes to copy from the source BFILE. The amount and src_offset, because they refer to the BFILE, are in terms of bytes, and the dest_offset is either in bytes or characters for BLOBs and CLOBs respectively.

If the offset you specify in the destination LOB is beyond the end of the data currently in this LOB, then zero-byte fillers or spaces are inserted in the destination BLOB or CLOB respectively. If the offset is less than the current length of the destination LOB, then existing data is overwritten.

There is an error if the input amount plus offset exceeds the length of the data in the BFILE.

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.

Exceptions

Table 52-47 LOADFROMFILE Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of the input parameters are NULL or INVALID.

INVALID_ARGVAL

Either:

src_offset or dest_offset < 1.

src_offset or dest_offset > LOBMAXSIZE.

amount < 1.

amount > LOBMAXSIZE.


OPEN Procedures

This procedure opens a LOB, internal or external, in the indicated mode. Valid modes include read-only, and read/write.

Syntax

DBMS_LOB.OPEN ( lob_loc IN OUT NOCOPY BLOB, open_mode IN BINARY_INTEGER);
DBMS_LOB.OPEN ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, open_mode IN BINARY_INTEGER);
DBMS_LOB.OPEN ( file_loc IN OUT NOCOPY BFILE, open_mode IN BINARY_INTEGER := file_readonly);

Parameters

Table 52-48 OPEN Procedure Parameters

ParameterDescription

lob_loc

LOB locator. For more information, see Operational Notes .

open_mode

Mode in which to open.

For BLOB and CLOB types, the mode can be either: LOB_READONLY or LOB_READWRITE.

For BFILE types, the mode must be FILE_READONLY.

Usage Notes

OPEN requires a round-trip to the server for both internal and external LOBs. For internal LOBs, OPEN triggers other code that relies on the OPEN call. For external LOBs (BFILEs), OPEN requires a round-trip because the actual operating system file on the server side is being opened.

It is not mandatory that you wrap all LOB operations inside the Open/Close APIs. However, if you open a LOB, you must close it before you commit or rollback the transaction; an error is produced if you do not. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

It is an error to commit the transaction before closing all opened LOBs that were opened by the transaction. When the error is returned, the openness of the open LOBs is discarded, but the transaction is successfully committed. Hence, all the changes made to the LOB and nonLOB data in the transaction are committed, but the domain and function-based indexes are not updated. If this happens, you should rebuild the functional and domain indexes on the LOB column.


READ Procedures

This procedure reads a piece of a LOB, and returns the specified amount into the buffer parameter, starting from an absolute offset from the beginning of the LOB.

The number of bytes or characters actually read is returned in the amount parameter. If the input offset points past the End of LOB, then amount is set to 0, and a NO_DATA_FOUND exception is raised.

Syntax

DBMS_LOB.READ ( lob_loc IN BLOB, amount IN OUT NOCOPY BINARY_INTEGER, offset IN INTEGER, buffer OUT RAW);
DBMS_LOB.READ ( lob_loc IN CLOB CHARACTER SET ANY_CS, amount IN OUT NOCOPY BINARY_INTEGER, offset IN INTEGER, buffer OUT VARCHAR2 CHARACTER SET lob_loc%CHARSET);
DBMS_LOB.READ ( file_loc IN BFILE, amount IN OUT NOCOPY BINARY_INTEGER, offset IN INTEGER, buffer OUT RAW);

Parameters

Table 52-49 READ Procedure Parameters

ParameterDescription

lob_loc

Locator for the LOB to be read. For more information, see Operational Notes .

file_loc

The file locator for the LOB to be examined.

amount

Number of bytes (for BLOBs) or characters (for CLOBs) to read, or number that were read.

offset

Offset in bytes (for BLOBs) or characters (for CLOBs) from the start of the LOB (origin: 1).

buffer

Output buffer for the read operation.

Exceptions

Table 52-50 lists exceptions that apply to any LOB instance. Table 52-51 lists exceptions that apply only to BFILEs.

Table 52-50 READ Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of lob_loc, amount, or offset parameters are NULL.

INVALID_ARGVAL

Either:

amount < 1

amount > MAXBUFSIZE

offset < 1

offset > LOBMAXSIZE

amount is greater, in bytes or characters, than the capacity of buffer.

NO_DATA_FOUND

End of the LOB is reached, and there are no more bytes or characters to read from the LOB: amount has a value of 0.

Table 52-51 READ Procedure Exceptions for BFILEs

ExceptionDescription

UNOPENED_FILE

File is not opened using the input locator.

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.

INVALID_OPERATION

File does not exist, or you do not have access privileges on the file.

Usage Notes

The form of the VARCHAR2 buffer must match the form of the CLOB parameter. In other words, if the input LOB parameter is of type NCLOB, then the buffer must contain NCHAR data. Conversely, if the input LOB parameter is of type CLOB, then the buffer must contain CHAR data.

When calling DBMS_LOB.READ from the client (for example, in a BEGIN/END block from within SQL*Plus), the returned buffer contains data in the client’s character set. The database converts the LOB value from the server’s character set to the client’s character set before it returns the buffer to the user.


SUBSTR Functions

This function returns amount bytes or characters of a LOB, starting from an absolute offset from the beginning of the LOB.

For fixed-width n-byte CLOBs, if the input amount for SUBSTR is greater than (32767/n), then SUBSTR returns a character buffer of length (32767/n), or the length of the CLOB, whichever is lesser. For CLOBs in a varying-width character set, n is the maximum byte-width used for characters in the CLOB.

Syntax

DBMS_LOB.SUBSTR ( lob_loc IN BLOB, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN RAW;
DBMS_LOB.SUBSTR ( lob_loc IN CLOB CHARACTER SET ANY_CS, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN VARCHAR2 CHARACTER SET lob_loc%CHARSET;
DBMS_LOB.SUBSTR ( file_loc IN BFILE, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN RAW;

Pragmas

pragma restrict_references(SUBSTR, WNDS, WNPS, RNDS, RNPS);

Parameters

Table 52-52 SUBSTR Function Parameters

ParameterDescription

lob_loc

Locator for the LOB to be read. For more information, see Operational Notes .

file_loc

The file locator for the LOB to be examined.

amount

Number of bytes (for BLOBs) or characters (for CLOBs) to be read.

offset

Offset in bytes (for BLOBs) or characters (for CLOBs) from the start of the LOB (origin: 1).

Return Values

Table 52-53 SUBSTR Function Return Values

ReturnDescription

RAW

Function overloading that has a BLOB or BFILE in parameter.

VARCHAR2

CLOB version.

NULL

Either:

– any input parameter is NULL

amount < 1

amount > 32767

offset < 1

offset > LOBMAXSIZE

Exceptions

Table 52-54 SUBSTR Function Exceptions for BFILE operations

ExceptionDescription

UNOPENED_FILE

File is not opened using the input locator.

NOEXIST_DIRECTORY

Directory does not exist.

NOPRIV_DIRECTORY

You do not have privileges for the directory.

INVALID_DIRECTORY

Directory has been invalidated after the file was opened.

INVALID_OPERATION

File does not exist, or you do not have access privileges on the file.

Usage Notes

The form of the VARCHAR2 buffer must match the form of the CLOB parameter. In other words, if the input LOB parameter is of type NCLOB, then the buffer must contain NCHAR data. Conversely, if the input LOB parameter is of type CLOB, then the buffer must contain CHAR data.

When calling DBMS_LOB.SUBSTR from the client (for example, in a BEGIN/END block from within SQL*Plus), the returned buffer contains data in the client’s character set. The database converts the LOB value from the server’s character set to the client’s character set before it returns the buffer to the user.


TRIM Procedures

This procedure trims the value of the internal LOB to the length you specify in the newlen parameter. Specify the length in bytes for BLOBs, and specify the length in characters for CLOBs.

If you attempt to TRIM an empty LOB, then nothing occurs, and TRIM returns no error. If the new length that you specify in newlen is greater than the size of the LOB, then an exception is raised.

Syntax

DBMS_LOB.TRIM ( lob_loc IN OUT NOCOPY BLOB, newlen IN INTEGER);
DBMS_LOB.TRIM ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, newlen IN INTEGER);

Parameters

Table 52-55 RIM Procedure Parameters

ParameterDescription

lob_loc

Locator for the internal LOB whose length is to be trimmed. For more information, see Operational Notes .

newlen

New, trimmed length of the LOB value in bytes for BLOBs or characters for CLOBs.

Exceptions

Table 52-56 TRIM Procedure Exceptions

ExceptionDescription

VALUE_ERROR

lob_loc is NULL.

INVALID_ARGVAL

Either:

new_len < 0

new_len > LOBMAXSIZE

Usage Notes

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.


WRITE Procedures

This procedure writes a specified amount of data into an internal LOB, starting from an absolute offset from the beginning of the LOB. The data is written from the buffer parameter.

WRITE replaces (overwrites) any data that already exists in the LOB at the offset, for the length you specify.

Syntax

DBMS_LOB.WRITE ( lob_loc IN OUT NOCOPY BLOB, amount IN BINARY_INTEGER, offset IN INTEGER, buffer IN RAW);
DBMS_LOB.WRITE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN BINARY_INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET); 

Parameters

Table 52-57 WRITE Procedure Parameters

ParameterDescription

lob_loc

Locator for the internal LOB to be written to. For more information, see Operational Notes .

amount

Number of bytes (for BLOBs) or characters (for CLOBs) to write, or number that were written.

offset

Offset in bytes (for BLOBs) or characters (for CLOBs) from the start of the LOB (origin: 1) for the write operation.

buffer

Input buffer for the write.

Exceptions

Table 52-58 WRITE Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of lob_loc, amount, or offset parameters are NULL, out of range, or INVALID.

INVALID_ARGVAL

Either:

amount < 1

amount > MAXBUFSIZE

offset < 1

offset > LOBMAXSIZE

Usage Notes

There is an error if the input amount is more than the data in the buffer. If the input amount is less than the data in the buffer, then only amount bytes or characters from the buffer is written to the LOB. If the offset you specify is beyond the end of the data currently in the LOB, then zero-byte fillers or spaces are inserted in the BLOB or CLOB respectively.

The form of the VARCHAR2 buffer must match the form of the CLOB parameter. In other words, if the input LOB parameter is of type NCLOB, then the buffer must contain NCHAR data. Conversely, if the input LOB parameter is of type CLOB, then the buffer must contain CHAR data.

When calling DBMS_LOB.WRITE from the client (for example, in a BEGIN/END block from within SQL*Plus), the buffer must contain data in the client’s character set. The database converts the client-side buffer to the server’s character set before it writes the buffer data to the LOB.

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.


WRITEAPPEND Procedures

This procedure writes a specified amount of data to the end of an internal LOB. The data is written from the buffer parameter.

Syntax

DBMS_LOB.WRITEAPPEND ( lob_loc IN OUT NOCOPY BLOB, amount IN BINARY_INTEGER, buffer IN RAW);
DBMS_LOB.WRITEAPPEND ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN BINARY_INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET); 

Parameters

Table 52-59 WRITEAPPEND Procedure Parameters

ParameterDescription

lob_loc

Locator for the internal LOB to be written to. For more information, see Operational Notes .

amount

Number of bytes (for BLOBs) or characters (for CLOBs) to write, or number that were written.

buffer

Input buffer for the write.

Usage Notes

There is an error if the input amount is more than the data in the buffer. If the input amount is less than the data in the buffer, then only amount bytes or characters from the buffer are written to the end of the LOB.

Exceptions

Table 52-60 WRITEAPPEND Procedure Exceptions

ExceptionDescription

VALUE_ERROR

Any of lob_loc, amount, or offset parameters are NULL, out of range, or INVALID.

INVALID_ARGVAL

Either:

amount < 1

amount > MAXBUFSIZE

Usage Notes

The form of the VARCHAR2 buffer must match the form of the CLOB parameter. In other words, if the input LOB parameter is of type NCLOB, then the buffer must contain NCHAR data. Conversely, if the input LOB parameter is of type CLOB, then the buffer must contain CHAR data.

When calling DBMS_LOB.WRITEAPPEND from the client (for example, in a BEGIN/END block from within SQL*Plus), the buffer must contain data in the client’s character set. The database converts the client-side buffer to the server’s character set before it writes the buffer data to the LOB.

It is not mandatory that you wrap the LOB operation inside the Open/Close APIs. If you did not open the LOB before performing the operation, the functional and domain indexes on the LOB column are updated during the call. However, if you opened the LOB before performing the operation, you must close it before you commit or rollback the transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap the LOB operation inside the Open/Close API, the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. Therefore, it is recommended that you enclose write operations to the LOB within the OPEN or CLOSE statement.

Scripting on this page enhances content navigation, but does not change the content in any way.