Copies large object data between BLOBs, CLOBs, MEMPTRs, and LONGCHARs. It also copies large object data to and from the file system, and converts large object data to or from a specified code page.
COPY-LOB [ FROM ] { [ OBJECT ] source-lob | FILE source-filename } [ STARTING AT n ] [ FOR length ] TO { [ OBJECT ] target-lob [OVERLAY AT n [TRIM ] ] | FILE target-filename [ APPEND ] } [ NO-CONVERT | CONVERT convert-phrase ] [ NO-ERROR ]. |
The AVM raises the ERROR condition if source-filename resolves to the Unknown value (?) or the source file cannot be read. The filename can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.
If the specified target object does not yet exist, the AVM either creates a BLOB or a CLOB, or allocates memory for a MEMPTR or a LONGCHAR. If the specified target object already exists, the AVM deletes the object before the copy operation begins, by default. You can specify the OVERLAY AT n option to overlay some portion of an existing target object.
If the target object does not yet exist, the AVM raises the ERROR condition. If the specified overlay position is less than 1, greater than the size of the object, or the Unknown value (?), the AVM raises the ERROR condition.
You can specify the TRIM option only if the target object is a BLOB or CLOB. In this case, the AVM copies the source object or file to the existing target object and truncates any data remaining in the target object. If the target object is a MEMPTR, the AVM ignores this option.
If the target file does not exist, the AVM creates the file. If the target file exists, and you specify the APPEND option, the AVM opens the file and appends the object data to the end of a file. If the target file exists, but you do not specify the APPEND option, the AVM creates the target file anew (which overwrites the original file).
If target-filename resolves to the Unknown value (?), or the target file cannot be created or written, the AVM raises the ERROR condition. The filename can contain Unicode characters.
The NO-CONVERT option specifies that no conversions occur. However, if the target is a LONGCHAR or a CLOB, the AVM validates the character data based on the target object's code page. For a CLOB, this is the code page of the CLOB. For a LONGCHAR, this is -cpinternal unless the LONGCHAR's code page was set using the FIX-CODEPAGE statement. If the validation fails, the AVM raises the ERROR condition.
The CONVERT option lets you specify how the AVM converts object data. Following is the syntax for convert-phrase:
Specify SOURCE CODEPAGE to indicate that a source object is in the specified code page. If you specify TARGET CODEPAGE, the AVM converts the target object to the specified code page.
The following table lists the default character conversions the AVM performs when copying data between the source and target objects. References to CLOBCP and CLOBDB represent CLOB data in either the CLOB's defined code page or the database's defined code page, respectively. References to the "fixed code page" represent the code page of a target LONGCHAR variable set using the FIX-CODEPAGE statement.
When the source object is a . . . | And the target object is a . . . | The AVM converts the source object . . . |
---|---|---|
MEMPTR | LONGCHAR | From -cpinternal to -cpinternal or the fixed code page |
MEMPTR | CLOBDB | From -cpinternal to the database's defined code page |
MEMPTR | CLOBCP | From -cpinternal to the CLOB's defined code page |
BLOB | LONGCHAR | No conversion, the LONGCHAR is in -cpinternal or the fixed code page |
LONGCHAR | MEMPTR | From the LONGCHAR's code page to -cpinternal |
LONGCHAR | BLOB | No conversion, the BLOB's code page is unknown |
LONGCHAR | CLOBDB | From the LONGCHAR's code page to the database's defined code page |
LONGCHAR | CLOBCP | From the LONGCHAR's code page to the CLOB's defined code page |
CLOBDB | MEMPTR | From the database's defined code page to -cpinternal |
CLOBDB | LONGCHAR | From the database's defined code page to -cpinternal or the fixed code page |
CLOBCP | MEMPTR | From the CLOB's defined code page to -cpinternal |
CLOBCP | LONGCHAR | No conversion, or conversion to the fixed code page |
If either the source or the target object is a file, the target's code page defaults to -cpstream.
The Byte Order Mark (BOM) or the encoding declaration is processed when a COPY-LOB operation reads from or writes to a FILE. For example, when a COPY-LOB statement copies data from a FILE (with a BOM) to a CLOB, the statement identifies and translates file content based on the BOM character but ignores the BOM character as part of the copy operation. And, when a COPY-LOB operation copies data from a CLOB to the beginning of a FILE, the statement prepends the BOM character, except when the BOM can be assumed; that is, the code page of the FILE target is UTF-8.
Also, if the COPY-LOB operation is written to a STARTING-AT location embedded within the FILE, the BOM character is not prepended to the written content. For more information on encoding declarations, see the OpenEdge® Development: Working with XML guide.
To check for errors after a statement that uses the NO-ERROR option:
If the statement does not include the NO-ERROR option, you can use a CATCH end block to handle errors raised by the statement.
Some other important usage notes on the NO-ERROR option: