LOTOFILE Function

The LOTOFILE function copies a smart large object to an operating-system file.

The first parameter specifies the BLOB or CLOB column to copy. The function determines what file to create from the following parameters:

The pathname identifies the directory path and the source file name.
The file destination identifies the computer, 'client' or 'server', on which this file resides:
- Set file destination to 'client' to identify the client computer as the location of the source file. The pathname can be either a full pathname or a path relative to the current directory.
- Set file destination to 'server' to identify the server computer as the location of the source file. The full pathname is required.

By default, the LOTOFILE function generates a filename of the form:

file.hex_id

In this format, file is the filename you specify in pathname and hex_id is the unique hexadecimal smart-large-object identifier. The maximum number of digits for a smart-large-object identifier is 17. Most smart large objects, however, would have an identifier with fewer digits.

For example, suppose that you specify a UNIX pathname value as follows:

'/tmp/resume'

If the CLOB column has the identifier 203b2, then LOTOFILE creates the file:

/tmp/resume.203b2

For another example, suppose that you specify a Windows pathname value as follows:

'C:\tmp\resume'

If the CLOB column has an identifier of 203b2, the LOTOFILE function would create the file:

C:\tmp\resume.203b2

To change the default filename, you can specify the following wildcards in the filename of the pathname:

One or more contiguous question mark ( ? ) characters in the filename can generate a unique filename.
The LOTOFILE function replaces each question mark with a hexadecimal digit from the identifier of the BLOB or CLOB column.

For example, suppose that you specify a UNIX pathname value as follows:
```
'/tmp/resume??.txt'
```
The LOTOFILE function puts 2 digits of the hexadecimal identifier into the name. If the CLOB column has an identifier of 203b2, the LOTOFILE function would create the file:
```
/tmp/resume20.txt  
```
If you specify more than 17 question marks, LOTOFILE ignores them.
An exclamation ( ! ) point at the end of the filename indicates that the filename does not need to be unique.
For example, suppose that you specify a Windows pathname value as follows:
```
'C:\tmp\resume.txt!'
```
The LOTOFILE function does not use the smart-large-object identifier in the filename, so it generates the following file:
```
C:\tmp\resume.txt 
```

If the filename that you specify already exists, LOTOFILE returns an error.

The LOTOFILE function performs any code-set conversion that might be required when it copies a CLOB value from the database to a file on the client or server computer.

When you qualify LOTOFILE with the name of a remote database and a remote database server, the BLOB or CLOB column, the pathname, and the file destination become relative to the remote database server.

When you specify server as the file destination, as in the next example, the LOTOFILE function copies the smart large object from the remote database server to a source file in the specified directory on the remote database server:

rdb@rserv:LOTOFILE(blob_col, 'C:\tmp\photo.gif!', 'server')

If you specify client as the file destination, as in the following example, the LOTOFILE function copies the smart large object from the remote database server to a source file in the specified directory on the local client computer:

rdb@rserv:LOTOFILE(clob_col, 'C:\tmp\essay.txt!', 'client')