The ifx_lo_copy_to_file() function

The ifx_lo_copy_to_file() function copies the contents of a smart large object into an operating-system file.

Syntax

mint ifx_lo_copy_to_file(LO_ptr, fname, flags, result)
   ifx_lo_t *LO_ptr;
   char *fname;
   mint flags;
   char *result;

LO_ptr: A pointer to the LO-pointer structure that you provide to identify the smart large object to copy. For more information about LO-pointer structures, see The LO-pointer structure.
fname: The full path name of the target file to hold the data.
flags: An integer that specifies the location of the fname file.
result: A pointer to a buffer that contains the file name that ifx_lo_copy_to_file() generates.

Usage

The ifx_lo_copy_to_file() function can create the target files on either the server or the client computer. The flag values for the flags argument indicate the location of the file to copy. Valid values include the following constants, which the locator.h header file defines.

File-location constant: Purpose
LO_CLIENT_FILE: The fname file is on the client computer.
LO_SERVER_FILE: The fname file is on the server computer.

By default, the ifx_lo_copy_to_file() function generates a file name of the form:

fname.hex_id

In this format, fname is the file name you specify as an argument to ifx_lo_copy_to_file() and hex_id is the unique hexadecimal smart-large-object identifier. The maximum number of digits for a smart-large-object identifier is 17; however most smart large objects would have an identifier with fewer digits.

For example, suppose you specify a pathname value as '/tmp/resume'.

If the CLOB column has an identifier of 203b2, the ifx_lo_copy_to_file() function creates the file: /tmp/resume.203b2.

To change this default file name, you can specify the following wildcards in the file name portion of fname:

One or more contiguous question mark (?) characters in the file name can generate a unique file name.
The ifx_lo_copy_to_file() function replaces each question mark with a hexadecimal digit from the identifier of the BLOB or CLOB column. For example, suppose you specify a pathname value as '/tmp/resume??.txt'.
The ifx_lo_copy_to_file() function puts two digits of the hexadecimal identifier into the name. If the CLOB column has an identifier of 203b2, the ifx_lo_copy_to_file() function would create the file /tmp/resumeb2.txt.
If you specify more than 17 question marks, the ifx_lo_copy_to_file() function ignores them.
An exclamation point (!) at the end of the file name indicates that the file name does not need to be unique.
For example, suppose you specify a path name value as '/tmp/resume.txt!'.
The ifx_lo_copy_to_file() function does not use the smart-large-object identifier in the file name so it generates the following file: ifx_lo_copy_to_file()
The exclamation point overrides the question marks in the file name specification.

Tip: These wildcards are also valid in the fname argument of the ifx_lo_filename() function. For more information about ifx_lo_filename(), see The ifx_lo_filename() function.

Your application must ensure that there is sufficient space to hold the generated file.

Return codes

0: The function was successful.
<0: The function was not successful and the return value indicates the cause of the failure.