MI_LO_FD mi_lo_from_file(conn, LO_dptr, fname_spec, open_mode, offset,amount, 
   LO_spec)
   MI_CONNECTION *conn;
   MI_LO_HANDLE **LO_dptr;
   const char *fname_spec;
   mi_integer open_mode;
   mi_integer offset;
   mi_integer amount;
   MI_LO_SPEC *LO_spec;

conn

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_dptr

is a doubly indirected pointer to the LO handle that identifies the new smart large object. This smart large object is where mi_lo_from_file( ) copies the file data.

fname_spec

is the full pathname to the operating-system file to copy into the new smart large object.

open_mode

is an integer bitmask 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.

offset

is the point to begin the read in the operating-system file. The offset value is the number of bytes from the beginning of the file, starting at 0.

amount

is the amount of data to read from the operating-system file, starting at the offset. An amount value of -1 means read to the end of the file.

LO_spec

is a pointer to an LO-specification structure that contains the storage characteristics of the new smart large object.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_lo_from_file( ) function performs the following steps to create a new smart large object that LOhdl_dptr references and copy data from an operating-system file to a new smart large object:

1. It creates an LO handle for the new smart large object and assigns a pointer to the handle to the argument that LOhdl_dptr references.

   If the LOhdl_dptr argument is NULL, mi_lo_from_file( ) allocates a new LO handle for the new smart large object and assigns a pointer to this handle to LOhdl_dptr. If LOhdl_dptr is not NULL, mi_lo_from_file( ) assumes that you have already allocated an LO handle and uses the LOhdl_dptr argument to locate the LO handle for the new smart large object.

2. It assigns the storage characteristics from the LO-specification structure, LO_spec, to the new smart large object.

   If the LO-specification structure has not been updated with storage characteristics (the associated fields are null), the mi_lo_from_file( ) function uses the system-specified storage characteristics.

   If the LO-specification structure was updated with storage characteristics, mi_lo_from_file( ) uses the storage characteristics that the LO-specification structure defines for the new smart large object.

3. It opens the new smart large object in read/write access mode (MI_LO_RDWR).

   The mi_lo_from_file( ) function does not accept an open-mode flag for the smart large object as an argument. The open_mode argument specifies the open mode for the operating-system file.

4. It copies the contents of the operating-system file whose name is in the fname_spec buffer into the new smart large object that LOhdl_dptr references.

   The mi_lo_from_file( ) function opens the operating-system file in the mode that the open_mode argument indicates. In the fname_spec operating-system file, the mi_lo_from_file( ) function begins the read operation at the file offset that offset indicates and reads the number of bytes that amount specifies. The function writes the file data to the sbspace of the new smart large object.

5. It returns an LO file descriptor that identifies the new smart large object.

   When the mi_lo_from_file( ) function is successful, it returns a valid LO file descriptor. When it completes, mi_lo_from_file( ) leaves the LO file position at the end of the smart large object. It does not reset the LO file position to the beginning of the smart large object.

   You can use this file descriptor to identify which smart large object to access in subsequent function calls, such as mi_lo_read( ) and mi_lo_write( ).

The mi_lo_from_file( ) function is a constructor function for both an LO file descriptor and an LO handle.

You can include environment variables in the fname_spec path with the following syntax:

$ENV_VAR

These environment variables must be set in the database server environment; that is, they must be set before the database server starts.

The mi_lo_from_file( ) function can access the operating-system files on either the server or the client computer. The file-mode values for the open_mode argument indicate the location of the file to copy and the access mode of the source file. Valid values include the following file-mode constants.

File-Mode Constant

Purpose

MI_O_EXCL

Open the file only if fname_spec does not exist.

MI_O_TRUNC

Zero out the input file before reading it.

MI_O_APPEND

Allow appending to the end of the file. (This function does not write to the source file.)

MI_O_RDWR

Open the file in read/write mode. (This function does not write to the source file.)

MI_O_RDONLY

Open the file in read-only mode.

MI_O_TEXT

Process the file as text (not binary).

MI_O_SERVER_FILE

The fname_spec file is on the server computer.

MI_O_CLIENT_FILE

The fname_spec file is on the client computer.

The default open_mode value is:

MI_O_RDONLY | MI_O_CLIENT_FILE

The mi_lo_from_file( ) function allows you to copy part of a file with the offset and amount parameters.

Each mi_lo_from_file( ) call is implicitly associated with the current session. When this session ends, the database server deallocates any smart large object that mi_lo_from_file( ) has created if its LO handle has not been stored in a column (its reference count is zero) and no open LO file descriptors exist for the smart large object.

An MI_LO_FD value

is the LO file descriptor of the open smart large object that LOhdl_dptr references. The function also initializes the LO handle that LOhdl_dptr references.

MI_ERROR

indicates that the function was not successful.

See also the descriptions of mi_lo_copy( ), mi_lo_create( ), mi_lo_from_buffer( ), mi_lo_spec_init( ), mi_lo_from_file_by_lofd( ), and mi_lo_to_file( ).

For information on the use of mi_lo_from_file( ) in an import opaque-type support function, see the IBM Informix: DataBlade API Programmer's Guide.