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.

GETAFILE options

Specifying which directory to display

DIR=dirname
The directory to view. Dirname is actually a subdirectory under the data directory, or a "local" virtual directory. Thus, DIR=/ means "display contents of Data directory"
Note: if DIR= is missing, then DIR=/ is assumed.
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 ROOTDIR=!.

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.

    • 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"
    HEADER=a+header+message
    The message string will be inserted as an <H2> at the top of the document.
    Example: header=(From+our+staff) (note the use of URL encoding)
    If not specified, a default header is used.
    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= option specified.
    Specifying what file specific information to display
    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:
         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
    TABLE = DIR, TABLE=FILE, TABLE=STANDARD, TABLE=KEY, or TABLE=NO
    Display results using a table (by default, TABLE=NO).
    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: 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: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 DIR= directory. Notes:
    TABLECOLS=n
    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.
    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 SENDFILE facility 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
    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
    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
    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.
    • 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). 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" 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).
    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.
    Examples:
    VIEW_WIN=YES (to enable)
    VIEW_WIN=NO (to disable, files will be displayed in same window as file list)
    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:


    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.
    Notes:

  • 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'
    zip_file_exts=0

    Created