DataBlade API Programmer's Manual

DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions

Home Contents Index Master Index New Book

mi_lo_from_file()

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

#include "milo.h"

...
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() or mi_server_connect() established.

LOhdl_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_expand() copies the file data.

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

flags
is an integer that is a bitmask 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 Application?

Valid in Server 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 obtains an LO handle for the new smart large object and assigns a pointer to the handle to the argument that LOhdl_dptr references.

mi_lo_from_file()

mi_lo_from_file()

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

mi_lo_from_file()

If the LO-specification structure has been 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).

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

mi_lo_from_file()

mi_lo_from_file()

5. It returns an LO file descriptor that identifies the new smart large object and is positioned at the start of this smart large object.

mi_lo_from_file()

mi_lo_read()

mi_lo_write()

The mi_lo_from_file() function can access the operating-system files on either the server or the client computer. The flag 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.

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.

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

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.

Return Values

An MI_LO_FD
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.

Related Topics

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().

In Chapter 3, "Handling Smart Large Objects," see "Initializing an LO Handle and LO File Descriptor" and "Using Operating-System Files".

DataBlade API Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.