The mi_file_open() function

The mi_file_open() function opens an operating-system file.

Syntax

mi_integer mi_file_open(filename, open_flags, open_mode)
   const char *filename;
   mi_integer open_flags;
   mi_integer open_mode;

filename

The path name of the file to open.

open_flags

A value bit mask that can have any of the following values:

Open flags that the operating-system open command supports: UNIX™ or Linux™ open(2) or Windows™ _open.

MI_O_SERVER_FILE (default): The file to open is on the server computer.
MI_O_CLIENT_FILE: The file to open is on the client computer. When you set this flag, you also need to include the appropriate file-mode flag values, as described later in this section.

open_mode

The file-permission mode in a format that the operating-system open command supports: UNIX™ or Linux™ open(2) or Windows™ _open.


Valid in client LIBMI application?	Valid in user-defined routine?
Yes	Yes

Usage

The mi_file_open() function opens the filename file in the access mode that open_flags specifies and the open mode that open_mode specifies. The function returns an integer file descriptor to this open file, through which you can access an operating-system file. The mi_file_open() function is the constructor function for a file descriptor. The mi_file_open() function allocates a new file descriptor for the duration of the client session.

The file ownership (owner and permissions) that open_mode specifies must be compatible with what open_flags specifies and what the operating-system open command supports.

Server only: From a C UDR, mi_file_open() can access files on the server computer. The function uses the user and group identifier of the session user to open the file. The function assumes the file ownership of the server environment.

Client only: In a client LIBMI application, mi_file_open() assumes the file ownership of the application user.

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

$ENV_VAR

This environment variable must be set in the server environment; that is, it must be set before the database server starts.

The open_flags argument contains two pieces of information:

Whether the file to open is on the server or client computer
By default, mi_file_open() assumes that the file to open resides on the server computer. If the file you need to open is on the client computer, include the MI_O_CLIENT_FILE flag in the open_flags bit mask. The file owner is the client user and file permissions will be consistent with the client user's umask setting.
Which flags to send to the underlying operating-system call that opens a file

For opening client files, the mi_file_open() function passes the open_flags argument to the underlying operating-system call that opens a file. These flags are translated to appropriate operating-system flags on the client side. (Therefore, the open_flags values must match those that your operating-system call supports.)

The file-mode flag values for the open_flags argument indicate the access modes of the file.

Server only: Valid values for server-side processing using the MI_O_CLIENT_FILE flag include the following file-mode constants. When MI_O_CLIENT_FILE is specified, you must include an MI_* flag.

File-mode constant: Purpose
MI_O_EXCL: Open the file only if fname_spec does not exist. Raise an exception if fname_spec does exist.
MI_O_TRUNC: Truncate the file, if it already exists.
MI_O_APPEND: Append to the file, if it already exists.
MI_O_RDONLY: Open the file in read-only mode (from_open_mode only).
MI_O_RDWR: Open the file in read/write mode.
MI_O_WRONLY: Open the file in write-only mode (to_open_mode only).
MI_O_BINARY: Process the data as binary data (to_open_mode only).
MI_O_TEXT: Process the data as text data (not binary, which is used if you do not specify MI_O_TEXT).

Client only: The default for the mi_file_open() function is to open the file on the server. The file mode is read/write for all users. The file owner is the client user ID. Valid values for the open_flags argument for opening server files include the following file-mode constants that can be used in client LIBMI applications.

File-mode constant: Purpose
O_EXCL: Open the file only if fname_spec does not exist. Raise an exception if fname_spec does exist.
O_TRUNC: Truncate the file, if it already exists.
O_APPEND: Append to the file, if it already exists.
O_RDONLY: Open the file in read-only mode (from_open_mode only).
O_RDWR: Open the file in read/write mode.
O_WRONLY: Open the file in write-only mode (to_open_mode only).
O_CREAT: Create the file, if the file does not exist.

For a complete list of open() system calls, consult the man pages (UNIX™) for your computer's operating system.

Return values

>=0: The file descriptor for the file that mi_file_open() has opened.
MI_ERROR: The function was not successful.

The mi_file_open() function does not throw an MI_Exception event when it encounters a runtime error. Therefore, it does not cause callbacks to start.