COPY-LOB statement

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.

Syntax

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 ].

[ OBJECT ]source-lob

The source object to be copied, which can be a MEMPTR or LONGCHAR variable, a BLOB or CLOB database or temp-table field, or a dynamic expression that resolves to a BLOB or CLOB database or temp-table field. The source object data at this location is copied to the specified target object or file.

FILE source-filename

A character expression that specifies the name of a file containing the source object data to be copied. The object data in this source file is copied to the specified target object or file. You can specify an absolute or relative pathname. Any relative pathname is relative to the current working directory.

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.

STARTING AT n

An integer expression indicating a one-based offset position, in the source object or file, from which to start copying. The copy begins at offset 1, by default. The AVM raises the ERROR condition if the specified offset position is less than 1, greater than the size of the object or file, or the Unknown value (?).

Note: Offsets are measured in bytes for binary data (BLOB or MEMPTR), and characters for character data (CLOB or LONGCHAR).

FOR length

An integer expression indicating the number of bytes or characters to copy from the source object or file starting at the specified offset position. The AVM copies from the specified offset position to the end of the object or file, by default. The AVM raises the ERROR condition if the specified length is less than 0, greater than the size of the object or file, or the Unknown value (?).

Note: Offsets are measured in bytes for binary data (BLOB or MEMPTR), and characters for character data (CLOB or LONGCHAR).

[ OBJECT ]target-lob

The target object to receive the copy, which can be a MEMPTR or LONGCHAR variable, a BLOB or CLOB database or temp-table field, or a dynamic expression that resolves to a BLOB or CLOB database or temp-table field. The object data in the specified source object or file is copied to the target object.

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.

Note: Although the AVM allocates memory for a target MEMPTR, you are responsible for freeing that memory.

OVERLAY AT n[ TRIM ]

An overlay position in the target object. The AVM copies the source object or file to an existing BLOB, CLOB, MEMPTR, or LONGCHAR target starting at the given position. If the operation results in writing past the end of a target BLOB, CLOB, or LONGCHAR, the AVM extends the target object as necessary. If the operation results in writing past the end of a target MEMPTR, the AVM raises the ERROR condition.

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.

FILE target-filename[ APPEND ]

A character expression that specifies the name of the target file to which the object data in the specified source object or file is copied. You can specify an absolute or relative pathname. Any relative pathname is relative to the current working directory.

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.

NO-CONVERT | CONVERT convert-phrase

Lets you specify the character conversion behavior between the source and target objects.

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:

{   [ SOURCE CODEPAGE codepage ]   [ TARGET CODEPAGE codepage ] }

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.

Default COPY-LOB statement character conversions

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

Note:

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.

NO-ERROR

Suppresses ABL errors or error messages that would otherwise occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement is not done and execution continues with the next statement. If the statement fails, any persistent side-effects of the statement are backed out. If the statement includes an expression that contains other executable elements, like methods, the work performed by these elements may or may not be done, depending on the order the AVM resolves the expression elements and the occurrence of the error.

To check for errors after a statement that uses the NO-ERROR option:

• Check the ERROR-STATUS:ERROR attribute to see if the AVM raised the ERROR condition.
• Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than zero to see if the AVM generated error messages. ABL handle methods used in a block without a CATCH end block treat errors as warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR attribute, but do add messages to the ERROR-STATUS system handle. Therefore, this test is the better test for code using handle methods without CATCH end blocks. ABL handle methods used in a block with a CATCH end block raise ERROR and add messages to the error object generated by the AVM. In this case, the AVM does not update the ERROR-STATUS system handle.
• Use ERROR-STATUS:GET-MESSAGE( message-num ) to retrieve a particular message, where message-num is 1 for the first message.

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:

• NO-ERROR does not suppress errors that raise the STOP or QUIT condition.
• A CATCH statement, which introduces a CATCH end block, is analogous to a NO-ERROR option in that it also suppresses errors, but it does so for an entire block of code. It is different in that the error messages are contained in a class-based error object (generated by the AVM or explicitly thrown), as opposed to the ERROR-STATUS system handle. Also, if errors raised in the block are not handled by a compatible CATCH block, ON ERROR phrase, or UNDO statement, then the error is not suppressed, but handled with the default error processing for that block type.
• When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.
• If an error object is thrown to a statement that includes the NO-ERROR option, then the information and messages in the error object will be used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.

Notes

• If a source or target object is stored in a database, its record must be available to copy. The lock mode of the record containing the target object must be EXCLUSIVE-LOCK or SHARE-LOCK and upgradeable; otherwise, the COPY-LOB statement raises the ERROR condition.
• You can also assign large object data from one BLOB or MEMPTR to another, and one CLOB or LONGCHAR to another, using the Assignment (=) statement or ASSIGN statement. You cannot use the Assignment (=) statement or ASSIGN statement to assign large object data between BLOBs or MEMPTRs and CLOBs or LONGCHARs.