Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

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.

MI_LO_FD mi_lo_from_file(conn, LO_dptr, fname_spec, flags, offset, amount,

LO_spec)

MI_CONNECTION *conn;

MI_LO_HANDLE **LO_dptr;

const char *fname_spec;

mi_integer flags;

mi_integer offset;

mi_integer amount;

MI_LO_SPEC *LO_spec;

conn	is a pointer to the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() has established.
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.
flags	is an integer that is a bit mask to indicate how to open the operating-system file and where this file is located.
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 flags 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 flags 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 the LO handle. It

The mi_lo_from_file() function allocates a new LO handle in the current memory duration.

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 flags 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.

Important: The MI_O_TRUNC flag is valid but is not often useful in a DataBlade API module.

The default flags 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.

See the descriptions of the following functions: mi_lo_copy(), mi_lo_create(), mi_lo_expand(), mi_lo_spec_init(), mi_lo_from_file_by_lofd(), and mi_lo_to_file().

For more information, see Initializing an LO Handle and LO File Descriptor and Using Operating-System Files.