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 Internationalize ABL 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 Use XML with ABL Applications guide.

NO-ERROR

The NO-ERROR option is used to prevent the statement from raising ERROR and displaying error messages.

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.

See also

NO-ERROR option