GDBOpen -- Open Generic Database File

See Also: GDBRegister(), GDBReopen(), ALLRegister(), GDBTestOpen(), GDBGetFormatInfo(), fp2type(), Writing GDB Formats, GDB Vector Introduction

CALL SEQUENCE

FILE    *GDBOpen( filename, access );

const char *filename;
           Name of database file to open.

const char *access;
           Access level to open file with.  One of "r" for 
           read or "r+" for read/write.

If the file format is not supported, or something is improper about the file when attempting to open it, a fatal IMP error will be generated. If trapped using IMPFatal(FALSE), then GDBOpen() will return NULL.

Special Considerations

In selected circumstances GDBOpen() will return the FILE * of an existing open dataset, and automatically increment the file reference count on that file using fpReference(), rather than actually open a new file handle. This is done to reduce use of system file handle resources (limited on most systems), and to ensure that a consistant state is maintained for the file relative to this program.

Reuse of an existing file handle will occur if:

• The filename passed in to GDBOpen() is an exact (but case insensitive) match for the name recorded for the existing file handle (as returned by fp2filename()). This means that different paths to the same file will result in separate file handles (eg. "./irvine.pix" and "irvine.pix").

• The FPF_SHARABLE flag is set on the already open file. This is set by default, but can be removed with fpClearFlag().

• The FPF_GDB flag is set on the already open file. This is automatically set by GDBOpen(), and GDBCreate().

• The type (as returned by fp2type()) of the existing file exactly matches the type passed into DKOpen() (eg. FL_TIFF).

• The file is either being opened for read-only access, or the existing file has FPF_WRITABLE set.

PATH MUNGING:

In selected circumstances the GDBOpen() function will use IMPMunge() and IMPSearchFile() to replace environment variables, convert the filename to local path conventions and tweek case sensitivity problems. This can be useful so that paths stored in files, and under other conditions can be - automatically massaged when switching platforms (ie. Unix to Windows), and so that paths may be relative to movable trees (ie. $PCIHOME). This is done in the following circumstances:

• GDBTestOpen() failed for all formats on the initial version of the filename.

• The original filename doesn't exist as a file.

• After IMPMunging() the GDBTestOpen() does succeed.

Note this doesn't actually affect the string passed into GDBOpen(), but it does affect the filename recorded by GDBOpen() and returned with fp2filename(). Also note that DKStat(), and DKCheck() do not do this path munging, so if you DKCheck() for the existance of a file before opening it then mungable files won't be found.

DKOpen() performs similar filename munging at it's level.

See Also: IMPFileSearch(), IMPMunge()

EXAMPLE

         bOldFatal = IMPFatal( FALSE );
         fpCurrent = GDBOpen( filename, "r" );
         IMPFatal( bOldFatal );

         if( fpCurrent == NULL )
         {
             ... no such file, or not a supported format, or corrupt file ...
             return;
         }

         printf( "File Size: %dx%d with %d channels.\n",
                 GDBChanXSize(fpCurrent), GDBChanYSize(fpCurrent),
                 GDBChanNum(fpCurrent) );

         GDBClose(fpCurrent);

@filename{gdblistfilemask}
@title{GDBListFileMask}{retrive the file mask of registered GDB formats}

Retrieve the file mask of registered GDB formats. This list is used
to pass the SGL file selector.

See Also: GDBOpen

1      CALL SEQUENCE

char            *GDBListFileMask(nSegment, nMode, bAddAllFiles, pszAdditionalTypes)

int             nSegment;
                    Segment type to list. Valid options.
                    LAYER_FILE for list of all files
                    LAYER_IMAGE for list of images
                    SEG_VEC for list of vector layers

int             nMode
                   Mode to access files. To get a list of files which 
                   can be exported to use GDB_WRITE else use GDB_READ

   TBool   bAddAllFiles
        Should the file type All Files (*,*) be added to the list.
        If TRUE All Files is added to the front of the list.

   char    *pszAdditionalTypes
        Additional file types which are added to the list. They are 
        added to the front but after the optional All Files type.
        Additional types should be in the form: 
        MyType Files (.xxx) *.xxx|
        pszAdditionalTypes can be NULL.

Returns a string with the file extensions.

1      EXAMPLE

Get a list of writable vectors

char *pszList;

pszList = GDBListFileMask(SEG_VEC, GDB_WRITE, TRUE, NULL);