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);
| Parameter | Description |
|---|---|
| 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.
Note: The input BFILE must have been opened prior to using this procedure. No character set conversions are performed implicitly when binary BFILE data is loaded into a CLOB. The BFILE data must already be in the same character set as the CLOB in the database. No error checking is performed to verify this.
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.
Note: If the character set is varying width, UTF-8 for example, the LOB value is stored in the fixed-width UCS2 format. Therefore, if you are using DBMS_LOB.LOADFROMFILE, the data in the BFILE should be in the UCS2 character set instead of the UTF-8 character set. However, you should use sql*loader instead of LOADFROMFILE to load data into a CLOB or NCLOB because sql*loader will provide the necessary character set conversions.
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
| Exception | Description |
|---|---|
| VALUE_ERROR | Any of the input parameters are NULL or INVALID. |
| INVALID_ARGVAL |
Either:
|
Examples
The following example loads the CLOB chapter_text column of the my_book_text table with the contents of the first 100 bytes of the file chapter01.txt in the BOOK_TEXT directory.
Note that the update of the chapter_text column occurs without the issue of an UPDATE statement. LOADFROMFILE accomplishes this via the chapter_text locator, which has been selected FOR UPDATE. LOB locators and DBMS_LOB allow changes to LOB columns in Oracle tables without issuing INSERT or UPDATE statements.
If you want to take this approach, you must lock the row that contains the LOB prior to modification. The best way to obtain this lock is to use the FOR UPDATE clause in the SELECT statement (in this example, this translates to calling the book_text_forupdate function):
INSERT INTO my_book_text (chapter_descr, chapter_text)
VALUES ('Chapter 1', EMPTY_CLOB());
COMMIT;
DECLARE
v_text_loc CLOB;
v_file_loc BFILE;
BEGIN
v_text_loc := book_text_forupdate ('Chapter 1');
v_file_loc := BFILENAME('BOOK_TEXT','chapter01.txt');
DBMS_LOB.LOADFROMFILE (v_text_loc, v_file_loc, 100);
COMMIT;
END;
/
SET LONG 100
COL chapter_descr FOR A15
COL chapter_text FOR A40 WORD_WRAPPED
SELECT chapter_descr, chapter_text
FROM my_book_text
WHERE chapter_descr = 'Chapter 1';
The output of this script is:
CHAPTER_DESCR CHAPTER_TEXT
--------------- ----------------------------------------
Chapter 1 It was a dark and stormy night.
Suddenly a scream rang out. An
EXCEPTION had not been handled.
The next example also loads the CLOB chapter_text column of the my_book_text table with the contents of the first 100 bytes of the file chapter01.txt in the BOOK_TEXT directory. This time, the LOB locator is not selected FOR UPDATE, but has been returned via the RETURNING clause.
Note that the update of the chapter_text column occurs without the issue of an UPDATE statement. LOADFROMFILE accomplishes this via the chapter_text locator, which has been returned by the RETURNING clause. LOB locators and DBMS_LOB allow changes to LOB columns in Oracle tables without issuing INSERT or UPDATE statements.
DECLARE
v_text_loc CLOB;
v_file_loc BFILE;
BEGIN
INSERT INTO my_book_text (chapter_descr, chapter_text)
VALUES ('Chapter 1', EMPTY_CLOB )
RETURNING chapter_text INTO v_text_loc;
v_file_loc := BFILENAME('BOOK_TEXT','chapter01.txt');
DBMS_LOB.LOADFROMFILE(v_text_loc, v_file_loc, 100);
COMMIT;
END;
/
SET LONG 100
COL chapter_descr FOR A15
COL chapter_text FOR A40 WORD_WRAPPED
SELECT chapter_descr, chapter_text
FROM my_book_text
WHERE chapter_descr = 'Chapter 1';
The output of this script is:
CHAPTER_DESCR CHAPTER_TEXT
--------------- ----------------------------------------
Chapter 1 It was a dark and stormy night.
Suddenly a scream rang out. An
EXCEPTION had not been handled.
This example loads the BLOB diagram column of the by_book_diagrams table with the contents of the file ch01_01.bmp in the IMAGES directory. The LOB locator has been returned via the RETURNING clause.
Note that the update of the diagram column occurs without the issue of an UPDATE statement. LOADFROMFILE accomplishes this via the diagram locator, which has been returned by the RETURNING clause. LOB locators and DBMS_LOB allow changes to LOB columns in Oracle tables without issuing INSERT or UPDATE statements.
DECLARE
v_file_loc BFILE;
v_diagram_loc BLOB;
v_diagram_size INTEGER;
BEGIN
v_file_loc := BFILENAME('IMAGES','ch01_01.bmp');
v_diagram_size := DBMS_LOB.GETLENGTH(v_file_loc);
DBMS_OUTPUT.PUT_LINE('Diagram size: ' || v_diagram_size);
DBMS_OUTPUT.PUT_LINE('Inserting Empty Diagram Row');
INSERT INTO my_book_diagrams
(chapter_descr, diagram_no, diagram)
VALUES ( 'Chapter 1', 1, EMPTY_BLOB )
RETURNING diagram INTO v_diagram_loc;
DBMS_OUTPUT.PUT_LINE('Loading Diagram From File');
DBMS_LOB.LOADFROMFILE(v_diagram_loc, v_file_loc, v_diagram_size);
COMMIT;
EXCEPTION
WHEN OTHERS
THEN
DBMS_OUTPUT.PUT_LINE('OTHERS Exception ' || sqlerrm);
END;
/
SELECT chapter_descr,
diagram_no,
dbms_lob.getlength(diagram) diagram_size
FROM my_book_diagrams
WHERE chapter_descr = 'Chapter 1';
This script produces:
Diagram size: 481078 Inserting Empty Diagram Row Loading Diagram From File CHAPTER_DESCR DIAGRAM_NO DIAGRAM_SIZE --------------- ---------- ------------ Chapter 1 1 481078
http://toadworld.com/KNOWLEDGE/KnowledgeXpertforOracle/tabid/648/TopicID/DLPE/Default.aspx