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

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

Syntax

#include "milo.h"

...
const char *mi_lo_to_file(conn, LO_hdl, fname_spec, flags, size)

		MI_CONNECTION *conn;

		MI_LO_HANDLE *LO_hdl;

		const char *fname_spec;

		mi_integer flags;

		mi_integer *size; 


conn
is a pointer to the connection descriptor that a previous call to mi_open() or mi_server_connect() established.

LO_hdl
is a pointer to an LO handle of the smart large object to copy.

fname_spec
is a pathname template for the target file that holds the data. This pathname can include special symbols for the filename.

flags
is an integer bitmask that indicates how to open the destination file and where the file is to be located. 

size
is the size of the file after mi_lo_to_file() completes the copy.







 



Valid in Client Application?

Valid in Server 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 flags argument indicate the location and access mode of the operating-system file to copy.

Valid values include the following file-mode constants.

File-Mode Constant Purpose
MI_O_EXCL
Raise an exception if a file by that name already exists.

MI_O_TRUNC
Truncate the file, if it there.

MI_O_APPEND
Append to the file, if it already 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 root.

MI_O_CLIENT_FILE
The fname_spec file is created on the client computer. The file mode is zero so that the file uses the client umask permission-mask value. The file owner is the client user identifier.

The default value for the flags 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 filename in the following form:

fname_spec.hex_id

In this format, fname_spec is the filename 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 a 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 filename, you can specify the following wildcard symbols in the filename portion of fname_spec:

One or more contiguous question mark (?) characters in the filename preserve digits of the LO-handle identifier.

mi_lo_to_file()

An exclamation point (!) at the end of the filename indicates that the filename does not need to be unique.

mi_lo_to_file()

Tip: These wildcards are also valid in the fname_spec argument of the mi_lo_filename() function. For more information on mi_lo_filename(), see page 12-282.

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

Filename Specification Actual Filename
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

Tip: The mi_lo_to_file() function replaces the mi_large_object_to_file() function, which Informix supports for backward compatibility only. Use mi_lo_to_file() for all new DataBlade routines.

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

Home Contents Index Master Index New Book

mi_lo_to_file()

Syntax

Usage

Return Values

char *
This character string is the filename that results from the wildcard expansion.

NULL
The function was not successful.

Related Topics

DataBlade API Programmer's ManualChapter 12: DataBlade API Function Descriptions Home Contents Index Master Index New Book

mi_lo_to_file()

Syntax

Usage

Return Values char * This character string is the filename that results from the wildcard expansion. NULL The function was not successful.

Related Topics

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

Home Contents Index Master Index New Book

Return Values

char *
This character string is the filename that results from the wildcard expansion.

NULL
The function was not successful.