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

filename

is the pathname of the file to open.

open_flags

is 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)

indicates that the file to open is on the server computer.

MI_O_CLIENT_FILE

indicates that 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

is 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

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.

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

>=0

is the file descriptor for the file that mi_file_open( ) has opened.

MI_ERROR

indicates that 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 be invoked.

See also the descriptions of mi_file_allocate( ) and mi_file_close( ) and the IBM Informix: DataBlade API Programmer's Guide.