Access to Operating-System Files

Home | Previous Page | Next Page Creating User-Defined Routines > Writing a User-Defined Routine > Performing Input and Output >

Access to Operating-System Files

The DataBlade API provides file-access functions for access to operating-system files from within a C UDR. These functions provide file management that is similar to what operating-system file-access functions provide. The DataBlade API file-access functions call the corresponding operating-system functions to perform their tasks; however, the DataBlade API functions periodically yield the virtual processor to limit the effects of blocking I/O.

Important:

Do not call operating-system file I/O functions from within a C UDR. Use these DataBlade API file-access functions instead because they are safer in a C UDR than their operating-system equivalents. For more information, see Avoiding Blocking I/O Calls.

Table 91 lists the DataBlade API functions for the basic file-access operations and the analogous operating-system calls for these operations.

Table 91. DataBlade API File-Access Functions
File-Access Operation	File-Access Function	Operating-System Call
Open an operating-system file and generate a file descriptor for the file	mi_file_open( )	open( )
Seek to a specified position to begin a read or write operation	mi_file_seek( )	seek( )
Obtain the current seek position	mi_file_tell( )	tell( )
Perform a read or write operation for a specified number of bytes	mi_file_read( ), mi_file_write( )	read( ), write( )
Obtain status information about a specified smart large object	mi_file_sync( )	sync( )
Close an operating-system file and deallocate the file descriptor	mi_file_close( )	close( )
Unlink (remove) an operating-system file	mi_file_unlink( )	unlink( )
Obtain an errno value for the file operation	mi_file_errno( )	GLOBAL INT ERRNO;

Tip:

The DataBlade API file-access functions execute in client LIBMI applications as well as C UDRs. For DataBlade API modules that you design to run in both client LIBMI applications and UDRs, use these file-access functions. For information on the behavior of these functions in a client LIBMI application, see Appendix A. Writing a Client LIBMI Application.

The DataBlade API accesses operating-system files through file descriptors. These file descriptors are similar in purpose to operating-system file descriptors. The following table summarizes the memory durations for a file descriptor.

Memory Duration	Memory Operation	Function Name
Duration of session (PER_SESSION)	Constructor	mi_file_open( )
Duration of session (PER_SESSION)	Destructor	mi_file_close( ), mi_file_unlink( )

Opening a File

The mi_file_open( ) function is the constructor function for a file descriptor. Through the file descriptor, you access an operating-system file. This section provides the following information on how to open a file:

How to specify the filename, including its path
How to specify the open flags and open mode, which the underlying operating-system call supports
How UDRs can share open files

Specifying a Filename

The filename argument of mi_file_open( ) identifies the operating-system file to open. This filename is relative to the server computer. You can include an environment variable in the filename path for the mi_file_open( ) and mi_file_to_file( ) file-access functions. This environment variable must be set in the database server environment; that is, it must be set before the database server starts.

For example, Figure 82 shows an mi_file_open( ) call that opens the operating-system file data_file1, which resides in the directory that the DATA_FILES environment variable specifies.

Figure 82. Sample Call to Open an Operating-System File

fd = mi_file_open("$DATA_FILES/data_file1", 
   O_WRONLY | O_APPEND | O_CREAT, 0644);

Suppose the DATA_FILES environment variable is set to the following directory in the database server environment:

/usr/local/app/load_files

The call to mi_file_open( ) in Figure 82 opens the following file:

/usr/local/app/load_files/data_file1

Calling the Operating-System Open Call

To open a file, the mi_file_open( ) function calls the open system call that your operating system supports.

UNIX/Linux Only

On UNIX or Linux, the open( ) system call opens an operating-system file.

End of UNIX/Linux Only

Windows Only

On Windows, the _open command opens an operating-system file.

End of Windows Only

The mi_file_open( ) function provides the following information about the file to the appropriate system call.

Argument of mi_file_open( )	Information Provided
open_flags (second argument)	Access mode for the operating-system file
open_mode (third argument)	Open mode for the operating-system file.

The function takes this information and passes it directly to the underlying operating-system call. Therefore, mi_file_open( ) supports the access modes and open modes that your operating-system open call supports.

Tip:

For more information on the open flags and open mode, see the documentation for your operating-system open call.

Specifying Open Flags

The mi_file_open( ) function takes as its second argument the open flags with which to open the operating-system file. The open flags value provides two pieces of information:

A masked flag value that specifies information such as access mode (read/write, read-only, write-only)
The mi_file_open( ) function passes these open flags directly to the underlying operating-system call that opens a file, so you must use flag values that your operating system supports. Also, you must include the operating-system header file (such as fcntl.h) that defines the open-flag constants you use.
A file-mode flag to indicate on which computer the file to open resides
The DataBlade API file-access functions support access to a file on either the server or client computer. By default, the mi_file_open( ) function opens a file on the server computer. To open a server file, you can omit the file-mode flag or specify the MI_O_SERVER_FILE file-mode flag. To open a client file, you must include the MI_O_CLIENT_FILE file-mode flag as part of the open flags.

For example, the mi_file_open( ) call in Figure 82 masks the following open flags for the file to open.

Open-Flag Constant: Purpose
O_WRONLY: Open the file write-only.
O_APPEND: Append new data to the end of the file.
O_CREAT: If the file does not exist, create it.

The example in Figure 82 is based on the following assumptions:

The operating-system open call supports the O_WRONLY, O_APPEND, and O_CREAT flags.
The code that executes this mi_file_open( ) call includes the header file that defines O_WRONLY, O_APPEND, and O_CREAT.
The file resides on the server computer.

Specifying the Open Mode

The mi_file_open( ) function takes as its third argument the open mode in which to open the operating-system file. The open mode specifies the ownership of the file. The mi_file_open( ) function passes this open mode directly to the underlying operating-system call. The semantics for mode must match those that the underlying operating-system call supports.

For example, the mi_file_open( ) call in Figure 82 specifies an open mode of 0644:

Read/write for owner
Read-only for group
Read-only for general public

Sharing Open Files

All UDRs that execute under the same connection can share a file (because they have the same connection descriptor). For example, if UDR1 opens a file, UDR2 can read, write to, or close this file, as long as these two UDRs execute under the same connection. However, UDRs that do not execute under the same connection cannot share a file.

The DataBlade API generates an error if your UDR attempts any of the following file I/O tasks:

To access a file that a UDR outside the session opened
To access a file that was not opened at all
To access a file that was opened and was closed

Closing a File

To close an operating-system file, free the associated file descriptor. A file descriptor remains active until either of the following events occurs:

The mi_file_close( ) function explicitly closes the file.
The client application ends the session.

Server Only

In a C UDR, a file descriptor has a memory duration of PER_SESSION. Files remain open after the UDR closes the connection.

End of Server Only

Client Only

In a client LIBMI application, a connection descriptor has a scope of the session. For more information, see Accessing Operating-System Files in Client LIBMI Applications.

End of Client Only

Copying a File

The DataBlade API provides the mi_file_to_file( ) function to enable you to copy an operating-system file between the computer on which the database server runs and the client computer. This function provides the open-mode flags for the new operating-system file. Unlike the mi_file_open( ) function, these open-mode flags are not those of the underlying operating-system open function. Instead, mi_file_to_file( ) supports the set of DataBlade API file-mode constants in Table 43.