OS/2 Shareware BBS: 35 Internet

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / DIR.DOC < prev next >

Wrap

Text File | 2001-05-02 | 16KB | 342 lines

02 May 2001 !DIR: SRE-http's built-in directory display facility I. Introduction !DIR is SRE-http's built in directory display facility. It has a number of display options, and can even automatically generate "descriptions" of text documents. !DIR is invoked in one of two ways: i) By explicitily calling it with a selector of !DIR. Example: /!DIR?dir1 ii) By the !CREATE option of AUTO_NAME; which instructs SRE-http to generate a directory listing "when there is no INDEX file". Example: /dir1/ (assuming there is no "directory specific index file" in the DIR1 subdirectory) Notes: * To improve performance, !DIR will "cache" directory listings; which it will use (after checking for changes). * For those interested in a more configurable directory display procedure, we recommend SRE-http's GETAFILE addon (http://www.srehttp.org/apps/getafile). -------------------------- II. Options By default, !DIR displays a sorted directory listing with a descriptive icon, a filename (that links to the file), the creation date, and the size. A link when selected will be processed by SRE-http using the standard rules (for example, it will be subject to selector-specific access controls). You can change these display options by modifying several SRE-http parameters: DIR_EXCLUSION and DIR_OPTIONS. You can also suppress display of selected directory (trees) by setting: DIR_ACCESS and DIR_ACCESS_PRIVS (all four of these parameters are in INITFILT.80, and can be modified with the intermediate configurator). When you use a !DIR selector, you can also include a list of options in the selector (after a ?) --they will override the options specified in the DIR_OPTIONS parameter. II.1. Descriptions of the DIR_ parameters: 1) DIR_EXCLUSION: a space delimited list of 'files and subdirectories' to exclude. Note that the * wildcard can be used. Example: dir_exclusion='HTACCESS. DESCRIBE.TXT /PRIVATE *.CNT ' Files and subdirectories listed in DIR_EXCLUSION will not be displayed by !DIR. However, the appearance of a directory in DIR_EXCLUSION does NOT suppress display of the entire directory (should it be the target of its own !DIR). For example, if DIR_EXCLUSION='PRIVATE ' if D:\WWW is the default data directory, and it has D:\WWW\JOE, D:\WWW\JOE\PRIVAVE. D:\WWW\PETER, and D:\WWW\PETER\PRIVATE subdirectories, then * a !DIR?JOE request will list all files and directories under d:\WWW\JOE, EXCCEPT for the PRIVATE directory. * a !DIR?PETER request will list all files and directories under D:\WWW\PETER, EXCEPT for the PRIVATE directory. * a !DIR?JOE/PRIVATE will list the contents of D:\WWW\JOE\PRIVATE Thus, a well-informed client can view the contents of an "excluded" directory (but will still be subject to access controls if she tries to download anything from it). * If you want to suppress "viewing the contents of" D:WWW\JOE\PRIVATE (or D:\WWW\PETER\PRIVATE), use the DIR_ACCESS options. 2) DIR_ACCESS and DIR_ACCESS_PRIVS For extra security, you can use DIR_ACCESS to suppress display of selected directories. DIR_ACCESS should contain a space delimited list of "selectors" that !DIR will limit access to. More precisely, each item in DIR_ACCESS is compared against the requested directory; and if any of them match (possibly using wildcards) then the client must have one of the privileges listed in DIR_ACCESS_PRIVS (or must be a SUPERUSER). If the client does not have one of these privileges, !DIR will not display the directory. Example: DIR_ACCESS=' SYSTEM */PRIVATE ' Note that !DIR?JOE/PRIVATE would match */PRIVATE. DIR_ACCESS_PRIVS='SUPERUSER DIRPRIVS ' For a further description, see INITFILT.DOC. Note: DIR_ACCESS and DIR_ACCESS_PRIVS are also used by the GETAFILE addon. 3)DIR_OPTIONS: A space delimited list of display options, including: AUTO_DESCRIBE == Try to create descriptions. This is done by extracting <TITLE> and <META NAME="DESCRIPTION" Content="xx"> headers from HTML files, the -z comments or FILE_ID.DIZ files from .ZIP files, and the beginning of plain text files. DESCRIBE=filename.ext == Use one line descriptions that are contained in filename.ext. If just a DESCRIBE is included, the filename.ext is assumed to be DESCRIBE.TXT (see below for more details) DESC_LEN=nnn == Maximum characters to display in the description (ignored if neither DESCRIBE or AUTO_DESCRIBE options are included) DATEFMT=x == The date format used; where x is one of B C D E M N O S U W. Where, given a date of 27 Aug 1988 B: 725975 D: 240 E: 27/08/88 L: 27 August 1988 M: August N: 27 Aug 1988 O: 88/08/27 S: 19880827 U: 08/27/88 W: Saturday Note that if "x" is not one of these, N is used. HEADERFILE=filename.ext == A file to use as a "header". If no filename.ext is given, then DIR.HDR is looked for. See below for details. FOOTERILE=filename.ext == A file to use as a "footer". If no filename.ext is given, then DIR.FTR is looked for. See below for details. MULTI_SEND == If the client's browser supports "Connection:Keep-Alive" (i.e.; NetScape 1.3), and the directory contains more then 20 files, and AUTO_DESCRIBE will be attempted .. then MULTI_SEND instructs !DIR to display "status" messages as the files are processed. These status messages (written after every 15 files) are sequentially displayed; and after all files have been processed, they will be overwritten by the directory listing. Note that older browsers (such as IBM's WebEx) do not support "Connection:Keep-Alive"; !DIR will detect this and not attempt to send status messages to such browsers. NOCACHE == If =1, Do NOT use the !DIR cache (force re-creation of the directory listing) NOSIZE == If =1, Suppress display of size. NOTIME == If =1, Suppress display of creation time NODATE == If =1, Suppress display of creation time and date NOICON == If =1, Suppress icon display NOSORT == If =1, Suppress sorting (default is to sort by name) NODIR == If =1, Suppress subdirectory display (display files only) NO_RECURSE_DIR == Do NOT Use DIR on subsequent directories. When NO_RECURSE_DIR=0, clicking on a directory link will yield a new !DIR style listing (using the current options). When NO_RECURSE_DIR=1, clicking on a directory link is treated as a standard request -- SRE-http will try to find a "directory specific" default file, and if it can't it might "automatically create a directory listing" Thus, if you want to use !DIR to examine the files in AND under a particular directory, you should set NO_RECURSE_DIR=0. PATTERN== Include only files that match this (possibly wildcard containing) pattern. You can have many PATTERN= elements. Example: PATTERN=*.HTM+PATTERN=*.DOC PREFIX == Add a "special directive" before each element in the list of file links. Typically, this would be "SENDAS_CHECK_TYPE"; or one of the other "mime type modifiers". Note that if your forget to start the PREFIX with a !, one will be added. Example: PREFIX=!SENDAS_CHECK_TYPE SHOWPARENT == Allow client to go up to parent. This CAN be used with the NODIR option. SIZEFMT=aaaaa == The size format: aaaaa=ABBREV means 13K, aaaaa=0 means 13,012 SORT=xxx == Sort criteria. xxx can be one of: NAME -- Sort by name (the default) DATE -- Sort by date SIZE -- Sort by date DESCRIBE -- Sort using the order of entries in a DESCRIBE file. Note that you MUST also specify a DESCRIBE option. EXT -- Sort by extension NONE -- Do not sort. SORT=NONE has the same effect as NOSORT Note that SIZE and EXT are used, directories will be sorted by name. Also, if DESCRIBE is chosen and DESCRIBE file is not available, or the DESCRIBE option is not specified, then sort by name is used. TABLE == use an HTML TABLE to display (otherwise, use <PRE> formatting) TABLE_BORDER=nnn == Size of border (if table used). If nnn=0, then no border is shown. TARGET=href_target == the "target window" -- if non-zero, a seperate window is used to display files (and directories) whose link is selected. TIMEFMT=nn == The time format: nn=24 means use 13:01, nn=0 means 1:01p Examples: DIR_OPTIONS='notime describe no_recurse_dir datefmt=u nocache ' DIR_OPTIONS='showparent table auto_describe desc_len=300 multi_send ' II.2. Specifying options in the selector. When invoking !DIR with a selector, you can append options after the directory name (the directory name MUST immediately follow the ?. Seperate each option with a space (or a + if you are hand coding a URL), and NOT with a &. The options are the same as above. For example: /DIR?dir1+nosize+auto_describe Each of these options can be specified as is, or as option=0, which "turns them off". This =0 form is useful if you wish to override a "parameter" settting with "request selector" option. Alternatively, option=1 "turns them on" (note that turning on a NOxxx option may mean suppressing a piece of the file info display). II.3 Notes on the DESCRIBE option: * The description file (say, DESCRIBE.TXT) is assumed to be in the "own directory". Thus, seperate directories must have their "own" description file. * The DESCRIBE option expects a "filename.ext" after an = sign. If you leave this off, DESCRIBE.TXT is used (if available). For example: !DIR?dir2+describe means "use the DESCRIBE.TXT file in the DIR2 subdirectory". * The description file (i.e.; DESCRIBE.TXT) file should be organized as FILE1.xxx a description file2.yyy another description /subdir1 a subdirectory description * Note that descriptions start with a file name (or a directory name, which must be preceded by a /) followed by the description (seperated from the filename by at least one space). These refer to subdirectories of the request directory (for example, if D:\WWW is the default data directory, and !DIR?DIR2 is used, the /SUBDIR1 refers to d:\www\dir2\subdir1) * The description must be on one (arbitrarily long) line. However, it will be formatted to fit in the (possibly multi-line) display area. This is in contrast with several SRE-http addons, which permit multi-line descriptions. * When used with AUTO_DESCRIBE, if an explicit description is found in the description file, it is always used. That is, AUTO_DESCRIBE only applies to files that do NOT have an entry in the description file (assuming the DESCRIBE option is used). * If you want to suppress all descriptions (!DIR is much faster when you don't display descriptions), set AUTO_DESCRIBE=0 and DESCRIBE=0. II.4. Notes on the HEADERFILE and FOOTERFILE options. * The header-file and footer-file is assumed to be in the "own" directory. * If a HEADERFILE is specified, and exists, the default header is NOT written. THUS.... If a HEADERFILE is specified, it MUST contain a <BODY> element. In all likelihood, that's why you'ld use it (so that you could specify a <BODY BACKGROUND=xxx.gif> element)! * The HEADERFILE option expects a "filename.ext" after an = sign. If you leave this off, DIR.HDR is used (if available). Similarly, if no file exists after the FOOTERFILE, a DIR.FTR file is used (if available). II.5. Note on PATTERN= and DIR_EXCLUSION * DIR_EXCLUSION is a "can not match list". PATTERN= entries, after concatenation (nb: you can have multiple PATTERN= entries in your option list) form a "must match list". You can have both -- in which case the file MUST match a PATTERN=, and must NOT match a DIR_EXCLUSION element. * When invoking !DIR as a selector: To override a PATTERN=xx.xx that you've included in the DIR_OPTIONS; just include a PATTERN=* option in the selector. For example: /!DIR?PICTURES+PATTERN=*.JPG+PATTERN=INDEX.HTML * Reminder: DIR_EXCLUSION and PATTERN refers to files (and subdirectories) in a requested directory. DIR_ACCESS and DIR_ACCESS_PRIVS refers to the requested directory itself. Thus, in order for DIR_EXCLUSION and PATTERN to come into play, DIR_ACCESS must first be satisfied. -------------------------- III. Notes on caching * Caching is meant to be used in conjunction with the AUTO_DESCRIBE and DESCRIBE=filename option. If you are not including descriptions, then caching will probably not help a lot. * A fairly simple caching algorithim is used, which will limit the cache's usefulness if !DIR is used extensively. If you intend to use !DIR extensively, you should consider using the BBS addon. * Caching uses files that are stored in the TEMPDATA_DIR directory (typically, \GOSERVE\TEMP). A _DIR.IDX file is used as a reference index, and _nnnnn.DSH files are used as "directory cache" files. * SRE-http will check the file-stamps of all files and subdirectories in the requested directory. In addition, it will check the dir_option and dir_exclusion parameters. If any of these have changed, the cache entry will not be used. Note: actually, a CRC of this information is used; thus, on very rare occasions SRE-http will NOT detect a change. * The DIR_CACHE_DURATION and DIR_CACHE_SIZE variables (set in INIT_STA.80) are used to set the size and lifespan of entries in the directory cache. The default values are 3 days and 1Megabyte. Note that about once a day, !DIR will (when invoked) clean up the directory cache (say, get rid of entries that have somehow become orphaned). * To suppress, on a request specific basis, SRE-http's use of this cache; just include a NOCACHE option in the request selector (using the !DIR?dirname+NOCACHE syntax). To permanently suppress it, set DIR_CACHE_SIZE=0 * Cache entries are identified by both fully qualified directory, and by the "option list and exclusion" lists. Thus, multiple views of the same directory may be cached. -------------------------- :End of DIR.DOC.