Database File System API

Topics:

Overview
Conditional Directives
64-Bit Support
Data Structures
Functions

Overview

The database file system API is a collection of data structures and standalone functions used to define the underlying file system used by the gxDatabase class. By separating the file system API calls from the database engine you can change the underlying file system without modifying the gxDatabase class. This is design allows you to support multiple files systems using a single interface and is usually utilized to support large files and proprietary file systems.

NOTE: None of the data structures and functions documented here are intended to be used directly. They are used internally by the gxDatabase class to call the correct native file API function for each supported platform/compiler.

Conditional Directives

__64_BIT_DATABASE_ENGINE__ - Directive used to enable 64-bit file offsets. NOTE: This directive also requires a platform/compiler specific 64-bit integer directive:

__WIN32__ - Directive used to enable 64-bit integer support on all WIN32 platforms.

__MSVC__ - Directive used to enable 64-bit integer support using MSVC version 4.2 and higher.

__UNIX__ - Directive used to enable 64-bit integer support on all UNIX platforms.

_LARGEFILE64_SOURCE - Directive used on all UNIX platforms to enable large file support.

__LINUX__ - Directive used to enable 64-bit integer support on all Linux platforms.

__HPUX__ - Directive used to enable 64-bit integer support on all HPUX platforms.

__SOLARIS__ - Directive used to enable 64-bit integer support on all Solaris platforms.

__BCC32__ - Directive used to enable 64-bit integer support using BCC32 5.5. NOTE: At the time of this publication large file support has not been implemented under BCC 5.5, although the use of 64-bit integers is supported.

64-Bit Support

Currently 64-bit support is limited to Windows NT, RedHat 6.2/7.2, HPUX 11.0 and Solaris 2.8 platforms, with HPUX 11.0 supporting a maximum single file size of 128 GB. As large file support and 64-bit operating systems become more prevalent support will be included for all the platforms supported by the 32-bit database engine.

The 64-bit UNIX API is based on the non-POSIX standard UNIX API interfaces to support large files:

::fopen64()
::fseeko64()
::ftello64()
::stat64()

NOTE: Since these functions are not part of the POSIX standard they may be removed in future compiler versions.

Data Structures

gxdFPTR - The gxdFPTR data structure defines the file pointer type used by the underlying file system.

Functions

gxdFPTR *gxdFPTRCreate(const char *fname) - Create a new file and truncate existing files. Returns a null value if the file cannot be created.

gxdFPTR *gxdFPTROpen(const char *fname, gxDatabaseAccessMode mode) - Open an existing file. The mode" variable determines if the file is opened for read only or read/write access. Returns a null value if the specified file cannot be opened. NOTE: This version of the open functions will only accept: gxDBASE_READONLY and fxDBASE_READWRITE access modes.

int gxdFPTRClose(gxdFPTR *stream) - Close an open file. Returns a non-zero value to indicate an error condition or zero if successful.

int gxdFPTRFlush(gxdFPTR *stream) - Flush the any open disk buffers. Returns a non-zero value to indicate an error condition or zero if successful.

int gxdFPTRRead(gxdFPTR *stream, void *buf, __UWORD__ bytes) - Read a specified number of bytes from the current file position into a memory buffer. Returns a non-zero value to indicate an error condition or zero if successful.

int gxdFPTRWrite(gxdFPTR *stream, const void *buf, __UWORD__ bytes) - Write a specific number of bytes from a memory buffer to the current file position. Returns a non-zero value to indicate an error condition or zero if successful.

FAU_t gxdFPTRSeek(gxdFPTR *stream, FAU_t, gxDatabaseSeekMode mode) - Seek to the specified offset starting at the beginning (gxDBASE_ SEEK_SET), end (gxDBASE_ SEEK_END) or current offset (gxDBASE_ SEEK_CUR). Returns a -1 to indicate an error condition or the current file position if successful.

FAU_t gxdFPTRTell(gxdFPTR *stream) - Returns the current file position or -1 if an error occurs.

int gxdFPTRExists(const char *fname) - Returns true if the specified file exists.

FAU_t gxdFPTRFileSize(const char *fname) - Returns the length of the specified file or -1 to indicate an error condition.

End Of Document