The mi_lo_from_file() function

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

Syntax

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
This 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_dptr
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
The full path name to the operating-system file to copy into the new smart large object.
open_mode
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 following Usage section.
offset
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
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
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

Usage

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.

Server only: If the mi_lo_from_file() function allocates an LO handle, it allocates this LO handle in the current memory duration. The mi_lo_from_file() function does not allocate memory for the LO file descriptor. Your UDR can assign this LO file descriptor to user memory with a desired memory duration.
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.
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.
Important: The MI_O_TRUNC flag is valid but is not often useful in a DataBlade® API module.
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.

Server only: The mi_lo_from_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 Informix® DataBlade® API Programmer's Guide.

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

Return values

An MI_LO_FD value
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
The function was not successful.