GetAFile Manual

From Wiki
Jump to: navigation, search

By Daniel Hellerstein


Retrieving files using GETAFILE

GETAFILE is a remote file transfer and display facility that allows easy traversal of the [/web/20060822094236/ 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 [/web/20060822094236/ !DIR] special command. You may also wish to consider the [/web/20060822094236/ 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:


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.

GETAFILE options

Specifying which directory to display

The directory to view. Dirname is actually a subdirectory under the [/web/20060822094236/ data directory], or a [/web/20060822094236/ "local" virtual] directory. Thus, DIR=/ means "display contents of Data directory"
Note: if DIR= is missing, then DIR=/ is assumed.
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 ROOTDIR=!.
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.
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=/.
Specifying a header and "introductory text"
The message string will be inserted as an

at the top of the document.
Example: header=(From+our+staff) (note the use of[/web/20060822094236/ URL encoding])
If not specified, a default header is used.

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)
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.
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= option specified.
Specifying what file specific information to display
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.
The time (in 10:41p format) is displayed. This must be used with the SHOWDATE option.
If SHOWSIZE=YES, then the file's size in bytes (or K bytes) is displayed (by default, SHOWSIZE=NO)
Put a "descriptive icon" next to the filename (or directory) (courtesy of the [/web/20060822094236/ GoHTTP HTTP filter ]) .
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 [/web/20060822094236/ 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.
�� � THUMBNAIL=thumcash/thum1
� � �THUMBNAIL=thumcash/thum1+thumcash/thum5
� � �THUMBNAIL=thumcash/thum1+thumcash/animal*.IND
Note if no extension is specified, a .IND is added.
Using Tables to Display files and directories
Display results using a table (by default, TABLE=NO).
  • NO : Do not use a TABLE (display files and directories on seperate lines)
  • DIR : Put the files & subdirectories in a multi-column table (each cell contains a seperate file or subdirectory).
  • FILES : Create a multi-column table containing (1 row per file or directory). The columns consist of:
    1. File & directory names (note that the file names do not include the directory name)
    2. File size (if SHOWSIZE=YES)
    3. File date (if SHOWDATE=YES)
    4. If TABLEFILE is selected, a line from it is displayed.
      Hint: to display just the date and size in a 3 column table, use TABLE=FILE with TABLEFILE=0
  • STANDARD: Similar to FILE, but process the TABLEFILE (described below) as a standard description file
    A standard description file consists of single line entries, with each entry containing the file name followed by a description. For example:
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. Keys are defined by identifiers that are enclosed in { } brackets. The text following a key is the key's message.
    Example: {afile.1a} a description of this file {afile.2} this is another file described
    If a file name matches the {afile.1a} key then the string a description of this file 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)
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.
TABLEFILE=filename+a+message or TABLEFILE=HTML
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 DIR= directory. Notes:
  • The a+message" is displayed as a column header (with +'s converted to spaces)
  • The HTML:filename 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 ...
    If HTML:filename is used: This is bold text
    If filename is used: This is bold text
n is an integer between 2 and 5. By default, equals 4.
This is used if TABLE=DIR is selected. It specifies the number of columns in the table of files/subdirectories.
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).
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.
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.
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.
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
Use the [/web/20060822094236/ SENDFILE ]facility of SRE-http to transfer files to the client. The default is RECORD=NO.
If COUNTER=option_list is present, call COUNTER.RXX, with option_list. For details on the option_list, see [/web/20060822094236/ COUNTER.DOC ].
Access Controls
PATTERN=file_pattern (several PATTERN= entries can be specified).
Only files that match a PATTERN= entry will be displayed. Note that each of these PATTERN= values may contain * wildcards (typically, they will). + For example, given: GETAFILE?DIR=FOODIR&Pattern=*.HTM&Pattern=*.DOC
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.
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 ' .
You can specify both an Exclusion List and PATTERN= 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 descripton of DIR_EXCLUSION.
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 descripton of DIR_ACCESS and DIR_ACCESS_PRIVS.
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 text/plain
  • 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 ).
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" 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).

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.
VIEW_WIN=YES (to enable)
VIEW_WIN=NO (to disable, files will be displayed in same window as file list)
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 explicitily 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.
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 ZIP_FILE_EXTS=0
Do not include periods (.) in the extension names
You should always include ZIP
You might also want to include EXE (for self extracting archives).
If filerexx.dll is not available, ZIP_FILE_EXTS is set to 0. Examples:
zip_file_exts='ZIP EXE'