- NAME
- DESCRIPTION

- Creating a new FILE Column
- Inserting into the Column
- Retreiving from Column

- COPYRIGHT
- VERSION

# NAME

GT::SQL::File - adds file upload and download abilities to GT::SQL

GT::SQL::File::Fh - basic file object

# DESCRIPTION

GT::SQL::File is not created directly by the user. This module is an internal module for GT::SQL to provide the abilty to upload/download files into a database column (or so it seems).

GT::SQL::File::Fh is often accessed by the user as well as created by the user whenever the user wants to store a file in the database.

## Creating a new FILE Column

When a new table is created or a column is converted into 'FILE' type, two things are created. First a column of type text which will save the name of the file that is being stored. Secondly, a piggy-back table will be greated under the name ``parent_table_name_File''. This new table will store the location of the uploaded/stored file and various associated file attributes.

To create a new file table, include a column something like the following.

        File_Col_Name => {

                    # common parameters
                           pos  => 2,
                           type => 'FILE',

                    # location of the directory where
                    # all the files should be saved
                           file_save_in => '/tmp',

                    # the method all the files are saved
                    # 'hashed', or 'simple'
                    #
                    # Defaults to hashed, and stores files in:
                    #   file_save_in/hashed_letter/ID
                    # Simple stores files in:
                    #   file_save_in/ID_OwnName.OwnExt
                           file_save_scheme => 'hashed',
                         } ...

## Inserting into the Column

Once you have the table created, to insert:

        # Include all the modules
        use GT::SQL;
        use GT::SQL::File;

        # First create a file object pointing to the file
        $f = GT::SQL::File->open('/path/to/file.txt');

        # Then create a table object
        $DB = GT::SQL->new('path/to/defs');
        $tbl = $DB->table();

        # Create the record
        # the file field can also be GT::CGI::Fh type
        $rec = {
            File_Column => $f,
            # ... and all the other columns
        };

# optionally, if you know the path to the file, you can provide # a scalar ref of the path and the module will autoload # the values # simple scalar values will be dropped $rec = { File_Column => \``/path/to/file.txt'' # ... and all the other columns };

        # Then to store the file
        $id = $tbl->add( $rec );

## Retreiving from Column

When a file has been stored. A standard select will only return the name of the file.

To get a filehandle, taking the previous example, if we know the unique id, you can do the following.

        $fh = $tbl->file_info( 'File_Column', $id );

You can use this file handle just like any other, however hidden behind are special functions that can be used as follows:

        print "Content-type: ", $fh->File_MimeType(), "\n\n";
        print <$fh>;

The following is a partial list of special functions you may access.

        Method             Returns
        ------             -------
        File_Name          the basic filename
        File_Directory     path to the file
        File_MimeType      mimetype of the file
        File_Size          site of the file
        File_RelativePath  the permuted file and directory without root
        File_URL           if possible, the URL to the requested file
        File_RelativeURL   the relative URL to the requested file

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: File.pm,v 1.69 2009/03/10 20:18:49 brewt Exp $