Informix DataBlade API Programmer's Manual Writing a User-Defined Routine

The DataBlade API provides file-access functions to access to operating-system files within a C UDR. These functions are very similar to the system file-access functions. They call the corresponding operating-system function to perform their task. However, the DataBlade API file-access 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. These DataBlade API file-access functions are safer in a C UDR than their operating-system equivalents. For more information, see Avoiding Blocking I/O Calls.

Figure 12-22 on page 12-76 shows the basic file operations along with the DataBlade API file-access functions that perform them and the analogous operating-system calls for these file operations.

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 very similar in purpose to operating-system file descriptors. The following table summarizes the memory operations for a file descriptor.

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 opened files

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 server environment; that is, it must be set before the database server starts.

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

Figure 12-23 Sample Open of an Operating-System File

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

/usr/local/app/load_files

The call to mi_file_open() in Figure 12-23 opens the following file:

/usr/local/app/load_files/data_file1

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

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

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

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

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, refer to 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 you want to open the operating-system file. The open flags provides 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. Therefore, 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.

For example, the mi_file_open() call in Figure 12-23 on page 12-77 masks the following open flags for the file is to be opened.

The example in Figure 12-23 on page 12-77 assumes the following:

• 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 mi_file_open() function takes as its third argument the open mode in which you want to open the operating-system file. The open mode specifies the ownership for 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 12-23 on page 12-77 specifies an open mode of 0644:

• Read/Write for owner
• Write-only for group
• Write-only for general public

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 file descriptors that mi_file_open() opens are valid until the end of the client session. If you do not explicitly close the files you opened with mi_file_close(), the database server automatically closes them when the client session completes.

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

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

The following sample UDR, logmsg(), uses the DataBlade API file-access functions to output messages to an external file:

#include <mi.h>
#include <fcntl.h>
#include <errno.h>

void logmsg ( filename, message, Gen_fparam )
	mi_lvarchar *   filename,
	mi_lvarchar *   message,
	MI_FPARAM *     Gen_fparam
{
	mi_integer			fd, /* file descriptor */
				ret, /* return status from file-access funcs 
						functions */
				error; /* mi_file_errno() errno return */

	mi_string			pathname[256], /* mi_lvarchar_to_buffer()
								                    result */
				*msg_str, /* mi_lvarchar_to_string() 
						                    result */
				*newline = "\n", /* output new line */
				 msg_error[150], /* errno error message */
				 tmp_error[150], /* temp error message */
				*p;

	if ( mi_get_varlen(filename) >= sizeof(pathname) )
		{
		mi_db_error_raise(NULL,MI_EXCEPTION,
			"Path name exceeded 255 characters!");
		return;
		}

	mi_var_to_buffer(filename, pathname);
	msg_str = mi_lvarchar_to_string(message);

	fd = mi_file_open(pathname, 
		O_WRONLY | O_APPEND | O_CREAT, 0644);
	if ( fd == MI_ERROR )
		{
		error = mi_file_errno();
		switch( error )
			{
			/*  Include your favorite errors from
				/usr/include/sys/errno.h.  */
			case ENOENT:
				p = "No such file or directory";
				break;
			case EACCES:
				p = "Permission denied";
				break;
			case EISDIR:
				p = "Pathname is a directory instead of file";
				break;
			default:
				p = "Unhandled errno case";
				break;
			}

		tmp_error = "logmsg: mi_file_open() failed for";
		sprintf(msg_error, "%s '%s' -- %s (errno=%d)",
			tmp_error, pathname, p, error);

		mi_db_error_raise(NULL,MI_EXCEPTION, msg_error);
		return; /* not reached */
		}

	ret = mi_file_write(fd, msg_str, strlen(msg_str));
	if( ret == MI_ERROR )
		{
			error=mi_file_errno();
			switch( error )
				{
				case ENOSPC:
					p = "No space left on device";
					break;
				default:
					p = "Unhandled errno case";
					break;
				}

			tmp_err = "logmsg: mi_file_write() failed for"
			sprintf(msg_error, "%s '%s' -- %s (errno=%d)",
				tmp_err, pathname, p, error);
			mi_db_error_raise(NULL,MI_EXCEPTION, msg_error);
			return; /* not reached */
			}

	ret = mi_file_write(fd, newline, strlen(newline));
	if( ret == MI_ERROR )
		{
		mi_db_error_raise(NULL, MI_EXCEPTION,
			"mi_file_write() failed for newline!");
		return;
		}

	mi_file_close(fd);
	mi_free(msg_str); /* mi_lvarchar_to_string() allocated
						result */
 
	return;
}