The mi_lo_to_file() function

The mi_lo_to_file() function copies a smart large object to an operating-system file on the client or server computer.

Syntax

const char *mi_lo_to_file(conn, LO_hdl, fname_spec, open_mode, size)
   MI_CONNECTION *conn;
   MI_LO_HANDLE *LO_hdl;
   const char *fname_spec;
   mi_integer open_mode;
   mi_integer *size;

conn

The value is one of the following connection values:

A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().

A NULL-valued pointer (database server only)

LO_hdl

A pointer to an LO handle of the smart large object to copy.

fname_spec

A path name template for the target file that holds the data. This path name can include special symbols for the file name.

open_mode

An integer bit mask to indicate how to open the operating-system file and where this file is located. For a list of valid file-mode constants, see the table in the following “Usage” section.

size

A pointer to the size of the file after mi_lo_to_file() completes the copy.


Valid in client LIBMI application?	Valid in user-defined routine?
Yes	Yes

Usage

The mi_lo_to_file() function can create the target files on either the server or the client computer. The flag values for the open_mode argument indicate the location and access mode of the operating-system file to copy.

Valid values include the following file-mode constants.

MI_O_EXCL: Raise an exception if a file by that name exists.
MI_O_TRUNC: Truncate the file, if it exists.
MI_O_APPEND: Append to the file, if it exists.
MI_O_RDWR: Open the file in read/write mode.
MI_O_WRONLY: Open the file in write-only mode.
MI_O_BINARY: Process the data as binary data.
MI_O_TEXT: Process the data as text (not binary). (Binary is used if you do not specify MI_O_TEXT.)
MI_O_SERVER_FILE: The fname_spec file is created on the server computer. The file mode is read/write for all users. The file owner is the client user ID.
MI_O_CLIENT_FILE: The fname_spec file is created on the client computer. The file owner is the client user and file permissions will be consistent with the client umask setting of the client.

The default value for the open_mode argument is the masking of the following flag values:

MI_O_CLIENT_FILE | MI_O_WRONLY | MI_O_TRUNC | MI_O_BINARY

By default, the mi_lo_to_file() function generates a file name in the following form:

fname_spec.hex_id

In this format, fname_spec is the file name that you specify as an argument to mi_lo_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 16; however, most smart large objects have an identifier with fewer significant digits.

For example, suppose you specify an fname_spec value as follows:

'/tmp/resume'

If the LO handle has an identifier of 00000000000203b2, the mi_lo_to_file() function creates the following file:

/tmp/resume.00000000000203b2

To change this default file name, you can specify the following wildcard symbols in the file name portion of fname_spec:

One or more contiguous question mark (?) characters in the file name preserve digits of the LO-handle identifier.
The mi_lo_to_file() function replaces each question mark with a hexadecimal digit from the identifier of the LO handle. Substitution is right to left. Question marks need not be contiguous. If you specify more than 16 question marks, the mi_lo_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.
The mi_lo_to_file() function omits the exclamation point from the result and does not substitute any characters. The exclamation point overrides the question marks in the file name specification.

Tip: These wildcards are also valid in the “fname_spec” argument of the mi_lo_filename() function.

The following table shows some examples of wildcard substitution when the hexadecimal identifier for the LO handle of a smart large object is 0000000000000019.


File name specification	Actual file name
x!	x
resume.txt!	resume.txt
x	x.0000000000000019
?resume	9resume
resume??.txt	resume19.txt
resume???.???	resume000.019
?abc???.???	0abc000.019
???a???.???	000a000.019
???a???.???b	000a000.019b
???a???.???b!	???a???.???b
???a???.???b??????????????	???a???.?00b00000000000019

If an exception because of file I/O problems occurs, the action that the database server takes depends on the file location set in the flags argument:

If MI_O_SERVER_FILE is set, errno is set.
If MI_O_CLIENT_FILE is set, the exception is raised within the database server.

Server only: The mi_lo_to_file() function does not need a connection descriptor to execute. If your UDR does not need a valid connection for other operations, you can specify a NULL-valued pointer for the conn parameter to establish a NULL connection. For information about the advantages of a NULL connection, see the HCL OneDB™ DataBlade® API Programmer's Guide.

The mi_lo_to_file() function is useful in export functions for opaque data types that contain smart large objects.

For more information, including information about the use of mi_lo_to_file() in an export opaque-type support function, see the HCL OneDB DataBlade API Programmer's Guide.

Return values

A char pointer: A pointer to the file name that results from the wildcard expansion.
NULL: The function was not successful.