GetAFile Manual

By Daniel Hellerstein

Retrieving files using GETAFILE
GETAFILE is a remote file transfer and display facility that allows easy traversal of the data directory (or a virtual directory) tree. It is highly configurable, and has the ability to record transfer of documents (using the SENDFILE facility).


 * Basically, GETAFILE is a more configurable version of SRE-https' built-in !DIR special command. You may also wish to consider the SHOWDIR dynamic directory list processor - see SHOWDIR.DOC for details on the use of SHOWDIR with SRE-http (note that SHOWDIR is part of the GOHTTP package).

Quick and simple method
The simplest way of using GETAFILE is to specify just a subdirectory. For example: GETAFILE?dir1/subdir1  will display files and subdirectories of the dir1/subdir1 directory (of the GoServe data directory, or of a virtual directory). The displayed information will be of the form: gif Filename.ext creation_date time size where gif is a descriptive icon.

Custom control method
Ambitious users can specify a number of options.

Basic syntax. Set up a URL that generates a request string of the form: /getafile?option1&option2&..&optionN" Alternatively, use (or modify) GETAFILE.HTM.

Specifying which directory to display
Note: if  is missing, then   is assumed.
 * DIR=dirname
 * The directory to view.  is actually a subdirectory under the data directory, or a "local" virtual directory. Thus,   means "display contents of Data directory"


 * ROOTDIR=rootdir
 * The ROOTDIR is used to limit how high up the directory tree GETAFILE will go. This can be useful when you want to allow someone to look at a subdirectory of your data drive, but not the whole directory. Hint: You can set ROOTDIR to be the same as DIR by using.

''This use of the SHOWDIR option of GETAFILE should NOT be confused with use of the SHOWDIR dynamic directory list processor! '' Subdirectories are displayed as links back to GETAFILE; this permits traversal of the directory tree using mouse clicks. Parent (the .. directory) is also included, but NOT if DIR=/.
 * SHOWDIR=BOTTOM, TOP, or NO
 * If BOTTOM or TOP, then display the subdirectories (of the select directory).
 * When a TABLE is not being used; BOTTOM causes subdirectories to be displayed after files, while TOP yields display before files.
 * If TABLE is used, the BOTTOM and TOP are equivalent (directories are always displayed after files).
 * The default is NO.

Specifying a header and "introductory text"
Example:  (note the use ofURL encoding) If not specified, a default header is used.
 * HEADER=a+header+message
 * The message string will be inserted as an  at the top of the document.


 * DISPFILE=filename.ext+a+message:Displays the contents of a file (with the name filename.ext), that is located in the DIR= directory. The optional "a message" will be used to describe the DISPFILE (if missing, the file name is used)
 * LINES=nlines:Sets the maximum number of lines to display from the DISPFILE= file (default is to display the entire file). This is ignored if there is no DISPFILE= option specified.
 * TOP=YES or TOP=NO:Put the DISPFILE= file at the top of the document (default is to put at the bottom). TOP= is ignored if there is no DISPFILE=</tt> option specified.

Specifying what file specific information to display
THUMBNAIL=thumcash/thum1 THUMBNAIL=thumcash/thum1+thumcash/thum5 THUMBNAIL=thumcash/thum1+thumcash/animal*.IND Note if no extension is specified, a .IND is added.
 * SHOWDATE = YES, NO, or YES_SHORT:If SHOWDATE=YES or YES_SHORT, then the file's creation date is displayed (by default, SHOWDATE=NO). YES displays the date using a 23 Nov 1995 format, YES_SHORT uses 11/23/95.
 * SHOWTIME=YES:The time (in 10:41p format) is displayed. This must be used with the SHOWDATE option.
 * SHOWSIZE = YES or SHOWSIZE=NO:If SHOWSIZE=YES, then the file's size in bytes (or K bytes) is displayed (by default, SHOWSIZE=NO)
 * GIFS=YES or GIFS=NO:Put a "descriptive icon" next to the filename (or directory) (courtesy of the GoHTTP HTTP filter).
 * THUMBNAIL=thumbnail_index: Instead of using generic "descriptive icons", use file-specific thumbnails. Thumbnail_index should be a selector  pointing to a thumbnail-cache-index . To use this option, you first must create thumbnails with the ThumbNail SRE-http addon.
 * Note that if you have many thumbnails (say, a few hundred for each of a few hundred files), downloading all the thumbnails to a client may take a long time! Multiple Indices:Actually, you can specify several thumbnail-cache-indices, any one of which may contain a * wildcard. GETAFILE will search each one (in turn) for a matching thumbnail. :Examples:''

Using Tables to Display files and directories
Hint: to display just the date and size in a 3 column table, use TABLE=FILE with TABLEFILE=0 A standard description file consists of single line entries, with each entry containing the file name followed by a description. For example: Example: If a file name matches the  key then the string   will used as the description (which will be displayed in column 4 of the table). Note on directory names: To be recognized, keys for directory names must contain just the subdirectory name (not the path information). For example, if you specify DIR=PUBLIC\, and PUBLIC\ contains the JAN96 directory, the key file (in the PUBLIC subdirectory of the data directory) should contain an entry of {JAN96)
 * TABLE = DIR, TABLE=FILE, TABLE=STANDARD, TABLE=KEY, or TABLE=NO
 * Display results using a table (by default, TABLE=NO).
 * NO : Do not use a TABLE (display files and directories on separate lines)
 * DIR : Put the files & subdirectories in a multi-column table (each cell contains a separate file or subdirectory).
 * FILES : Create a multi-column table containing (1 row per file or directory). The columns consist of:
 * File & directory names (note that the file names do not include the directory name)
 * File size (if SHOWSIZE=YES)
 * File date (if SHOWDATE=YES)
 * If TABLEFILE is selected, a line from it is displayed.
 * STANDARD: Similar to FILE, but process the TABLEFILE (described below) as a standard description file
 * FOOBAR.1 This is the first foobar file
 * BADPUNS.WP5 This is a WordPerfect file containing bad puns
 * /ZOO This is the zoo subdirectory  Note the use of the / to signify a sub-directory description.
 * KEY: Similar to FILE, but process the TABLEFILE (described below) as a keyed description file.  are defined by identifiers that are enclosed in {} brackets. The text following a   is the key's message.


 * AUTO_DESCRIBE=nnn. Where nnn is an integer, and nnn=0 implies NO.
 * AUTO_DESCRIBE is used if you want GETAFILE to attempt to extract a description from each file. In particular:
 * text/html files: the TITLE is extracted, along with selected META of HTTP-EQUIV elements.
 * text/plain files: the beginning of the file is extracted
 * .ZIP files: the .ZIP file is examined for a -z comment. If no -z comment it found, a FILE_ID.DIZ file is extracted (if it exists) from the .ZIP file.
 * Otherwise: no description is generated Regardless of the file type, a maximum of nnn characters is displayed. If nnn=YES, then a default value (250) is used. Notes:
 * AUTO_DESCRIBE is used only if TABLE equals STANDARD or KEY.
 * If the TABLEFILE contains an explicit description of a file, AUTO_DESCRIBE will not be used.
 * AUTO_DESCRIBE makes no attempt to generate descriptions of directories.
 * To generate .ZIP file descriptions, the UNZIPAPI.DLL (it's packaged with SRE-http) must be in your OS/2 LIBPATH or in the GoServe working directory.

If  is used: This is  bold text If  is used: This is bold text
 * TABLEFILE=filename+a+message or TABLEFILE=HTML:filename+a+message
 * TABLEFILE is used when TABLE equals KEY, STANDARD or FILE. It should contain "descriptive" information on the contents of the directory to be included into the TABLE of filenames & directories. As with the DISPFILE, the TABLEFILE should be in the  directory. Notes:
 * The " is displayed as a column header (with +'s converted to spaces)
 * The  variant tells GETAFILE to  interpret   HTML elements found in the description file. If HTML:filename is not used,  HTML elements will be encoded. For example, the following would be displayed ...

This is used if TABLE=DIR is selected. It specifies the number of columns in the table of files/subdirectories.
 * TABLECOLS=n
 * n is an integer between 2 and 5. By default, equals 4.


 * TABLEBORDER=YES or NO
 * If a TABLE=FILE, TABLE=STANDARD, or TABLE=KEY is specified, then TABLEBORDER is used to specify whether to display the exterior and interior boundary lines; with YES meaning "display lines" (the default is NO).


 * CELLSPACING=n
 * If a TABLE=FILE, TABLE=STANDARD, or TABLE=KEY is specified, then CELLSPACING controls the number of pixels between cells (larger values of n yield more spaced out tables). The default value of n is 2.


 * TR_COLORS=YES or NO
 * If TR_COLORS=YES, then an alternating set of bgcolors will be used in each row of a of a table. The number of alternates, and their values, can be customized by changing the TR_COLORS. variables in GETAFILE.CMD.


 * USEDL=YES or NO
 * If USEDL=YES, and TABLE=FILE, STANDARD, or KEY, a <DL> list will be used instead of a table. This can be convenient when talking to browsers that do not support tables, or when there is a lot of descriptive material.


 * USEPRE=YES or NO
 * If USEPRE=YES, then a tabluar format, using the <PRE> HTML tag, is used. This is ignored if the TABLE option is used.

Using SENDFILE to record transfers

 * RECORD=YES or RECORD=NO
 * Use the SENDFILEfacility of SRE-http to transfer files to the client. The default is RECORD=NO.


 * COUNTER=option_list
 * If COUNTER=option_list is present, call COUNTER.RXX, with option_list. For details on the option_list, see COUNTER.DOC.

Access Controls
then only *.HTM and *.DOC files (in the FOODIR directory) will be displayed.Note that if no PATTERN is specified, or if PATTERN=*, then all files (that are not explicitily excluded) will be displayed.
 * PATTERN=file_pattern (several PATTERN= entries can be specified).
 * Only files that match a PATTERN= entry will be displayed. Note that each of these  values may contain * wildcards (typically, they will). + For example, given:


 * DIR_EXCLUSION
 * DIR_EXCLUSION is  not  an option that can be included in a GETAFILE selector. It is an SRE-http parameter that is set in INITFILT.80. DIR_EXCLUSION contains a list of files and subdirectories that GETAFILE will not display.Notes:


 * By default, this list equals: exclusion_list=' HTACCESS. GROUP.LST PASSWD.LST /PRIVATE /TEMP '</tt>.
 * You can specify both an Exclusion List and  options.
 * If desired, you can use a GETAFILE specific DIR_EXCLUSION list (see GETAFILE.CMD for details).
 * DIR_EXCLUSION is also used by the !DIR special command.
 * See INITFILT.DOC for further description of DIR_EXCLUSION.


 * DIR_ACCESS and DIR_ACCESS_PRIVS
 * DIR_ACCESS and DIR_ACCESS_PRIVS are  not  options that can be included in a GETAFILE selector. They are SRE-http parameters set in INITFILT.80 DIR_ACCESS lists directories (possibly wildcarded) that will not be listed. DIR_ACCESS_PRIVS is used to override this suppression, client's with any of the privileges listed in DIR_ACCESS_PRIVS will be able to see the directory listing.Notes:
 * DIR_ACCESS and DIR_ACCESS_PRIVS is also used by the !DIR special command.
 * See INITFILT.DOC for further description of DIR_ACCESS and DIR_ACCESS_PRIVS.

Miscellaneous

 * FORCETEXT=CHECK, CHECK_FIRST, YES, or NO
 * FORCETEXT is used to force SRE-http to return the file as a plain text file (actually, it forces SRE-http to return a content-type of text/plain).
 * CHECK : If no explicit type, examine contents of file; and if all ASCII text, then return as
 * CHECK_FIRST  : Similar to CHECK, but file check before "explicit type check"
 * YES  Assume ALL files are text/plain mime type
 * NO - use explicit type Notes :
 * FOO.HTM will be returned as text/plain if CHECK_FIRST is used, and as text/html if CHECK is used
 * Explicit type  involves comparing file extensions to a list of types (see MEDIATYP.RXX for details on how to assign your own explicit types ).


 * IMGDIR=directory
 * Specifies the subdirectory (of your data directory) that contains the "descriptive icons" (GIF files) used by the GIFS=YES option.

Hint : Use the TYPE="hidden" attribute element in the NAME="IMGDIR"</tt> INPUT element.)

Example: imgdir="/IMGS2" instructs SRE-http to look in the IMGS2 subdirectory for the "little GIF" files.

If IMGDIR is not specified, then the gifs are assumed to be in the IMGS subdirectory (of your data directory). Examples: VIEW_WIN=YES</tt> (to enable) VIEW_WIN=NO</tt> (to disable, files will be displayed in same window as file list)
 * VIEW_WIN=YES (or NO)
 * When YES, files will be displayed in a viewer window. Thus, the list of files will be in one window, while selected files will be in this viewer window.


 * EXPAND_ZIP=YES:Instructs GETFILE to include a link into a .ZIP file. When selected, this link instructs GETAFILE to display a listing of the files in the .ZIP file. Each of these files will have an extraction link. Selection of this extraction link will cause GETAFILE to extract the selected file from  the selected .ZIP file. Notes:
 * When extracting a file from a .ZIP file, the SRE-http access control file may be checked. This is an additiona l check (it explicitly checks access rights for this .ZIP file, rather then access rights to GETAFILE?xxx)
 * Extraction from a .ZIP file involves creation of links that contain two other internal GETAFILE  options: DOEXPANDZIP and FILE_FROMZIP . Curious readers may wish to look at GETAFILE.CMD for details on these two  internal  parameters.
 * When expanding a .ZIP file, most other options are ignored. GETAFILE will use a rudimentary display, consisting of file name, date, and size. Two of the GETAFILE parameters will be recognized: FORCETEXT and SHOWGIFS.

Notes: zip_file_exts='ZIP EXE' zip_file_exts=0
 * ZIP_FILE_EXTS
 * ZIP_FILE_EXTS is not an option that can be included in the request string. Instead, it is a user-configurable variable located in GETAFILE.CMD. ZIP_FILE_EXTS should contain a space delimited list of extensions. Files containing these extensions will checked for a ZIP archive signature.  If such a signature is found (and EXPAND_ZIP='YES') then GETAFILE will include an expand this ZIP file link.
 * To suppress use of ZIP_FILE_EXTS (and assume that .ZIP files are ZIP archives), set
 * Do not include periods (.) in the extension names
 * You should always include
 * You might also want to include  (for self extracting archives).
 * If  is not available, ZIP_FILE_EXTS is set to 0. Examples: