A directory listing is sometimes refered to as a document Index, and is generally titled "Index of ...".
Unless disabled by the server's configuration, a directory listing is recognised by the server whenever a wildcard is present in a specification and there is no query string directing another activity (e.g. a document search). Compliant with other web implementations, a directory listing is also generated if a URL specifies a directory only and that directory contains no home page.
All specifications must be made using URL-style paths. See 2.3 - Document Specification.
The directory listing is designed to look very much like the basic layout of other servers, except that all directories are grouped at the top. In the opinion of the author, this looks and functions better than when interspersed with the files, as is otherwise common. The default listing provides:
The description can be either just that, a description of the role of that type of file under VMS, or if presented within quotes, an HTML document's own internal description taken from the "<TITLE></TITLE>" element.
Note that directory listings only processes the physical file system. This may or may not correspond to the web environment's virtual mappings.
The following link illustrates the directory listing format: *.*
The default listing has a generic WWW look about it, however it can be made to look a little more like the format of the VMS "DIRECTORY" command. In this mode the directories are presented as VMS subdirectories, the version number is shown, if a version wildcard was included in the specification then all matching versions are shown, the size is presented in used and allocated blocks, and automatic script activation is disabled. The VMS-style format is enabled by providing an explicit or wildcard version number with the specification, as in the following example: *.*;
By default (and generally) WASD installations are configured to return a binary file for unknown content-types (usually triggering a browser "save-as" dialog). For such files, and in fact all files in general, a directory listing icon is usually a link to a plain-text version of the file (regardless of the actual content). This becomes convenient way to access the content for files with "interesting" file name extensions and the actual markup of HTML source files, etc. Of course some files containing non-textual data will be variously displayed as gibberish depending on the browser.
YMMV
Some browsers and operating systems insist they know better than the server and ignore the response-specified content-type, inferring presentation of the content from magic bytes in that content or the trailing dot-separated file name extension.
The following files (empty, or not), when within a specific directory regulate access to that directory, and the listing of any parent directory or subdirectories.
Any file name beginning with a period is hidden from the directory listing mechanism (i.e. in VMS parlance it has only a type/suffix/extension). If specifically accessed they will be retrieved however. Hence the following files would not appear in a directory listing:
The WASD server behaviour can be modified using server directives. For directory listings this involves the inclusion of a query string beginning with "?httpd=index". The server detects this URI query string and processes it internally, changing the default action of directory listings.
Multiple directives can be combined by concatenating them with intervening ampersands, as per normal URI syntax.
?httpd=index&autoscript=no ?httpd=index&readme=no ?httpd=index&type=text/plain ?httpd=index&layout=format ?httpd=index&script=script-name ?httpd=index&script=script-name&readme=no ?httpd=index&delimit=none&readme=no&nos=yes
Server directives specified in the URI propagate when moving between directories unless the query string also contains
&local=yes
The control file .WWW_WASD can be used to contain server directives. Directives are generally included one per line with "#" prefixed comment lines allowed.
When a .WWW_WASD file is present in a directory it takes precedence over any SSI or URI (query string) directives also being applied, unless it includes an override=yes directive. When this is present any SSI and/or URI directive string is also applied to the request.
# an example .WWW_WASD file autoscript=no readme=no style=sort2 sort=s- override=yes
Allows specification of the directory listing layout from the URL, overriding the server default. The layout directive is a short, case-insensitive string that specifies the included fields, relative placement and optionally the width of the fields in a directory listing. Each field is controlled by a single letter (one with colon-separated parameter) and optional leading decimal number specifying the width. When a width is not specified an appropriate default applies. An underscore is used to indicate a single space and is used to separate the fields (two consecutive works well).
The default layout is:
I__L__R__S__D
The following provide other examples:
?httpd=index&layout=UI__L__R__S__D ?httpd=index&layout=I__L__R__S:b__D ?httpd=index&layout=I__L__R__S__D ?httpd=index&layout=I__15L__S__D ?httpd=index&layout=15L__9R__S ?httpd=index&layout=15N_9C_9R_S
By default the size of files is calculated as 1024 byte kilos.
When using the "S:D", the size is displayed as per "F" with 1000 byte kilos. If it is prefered to have the default display in 1000 byte kilos then set the directory listing layout using:
?httpd=index&layout=I__L__R__S:d__Dor explicitly direct the "kilo" quantity to 1000 with
?httpd=index&layout=I__L__R__S:0__Dto 1024 (as per VMS /UNIT=BYTES) with
?httpd=index&layout=I__L__R__S:2__Dwith or without an explicit size directive
?httpd=index&layout=I__L__R__S:2:K__D
The following links illustrate the difference between the "kilo" values:
1000
1024
If unsure of the kilo value being used check the "<META>" information in the directory listing.
The following links illustrate this functionality by listing this document's directory in various formats.
Default.
Only an icon and link.
Icon, link and size (in VMS-style format).
Name, day created and day revised.
Name (in upper-case), day created and day revised.
Description (fixed width) as a link, size in bytes, and day revised.
WASD has a default directory listing style where the page title is a series of links to the various directories in the path, then column labels are separated from directory links by a horizontal line, the after the listed directories a blank line, and the listed files, followed by another horizontal line, all in monospace font. There have been a small number of variations on this over the years. The current default (post-v10.4) style is implemented using an HTML table and differs from the historical preformatted text approach.
For each style there is a second variant where the horizontal lines partitioning the listing are not present.
The various directory listing styles are illustrated below.
*.* (style=default, style=table)
*.*? httpd=index&style=default2 (style=table2)
*.*?httpd=index&style=sort
*.*?httpd=index&style=sort2
*.*?httpd=index&style=anchor
*.*?httpd=index&style=anchor2
*.*?httpd=index&style=htdir
*.*?httpd=index&style=htdir2
*.*?httpd=index&style=original
*.*?httpd=index&style=original2
There is also a useful alternate style that allows manual, automatic and programmatic sorting of the listing content. The sort is performed by JavaScript and does not require a re-request of the server. A sortable listing is indicated by ▼▲ in the header icon column (if present). When a column has been sorted ascending/descending symbols are present adjacent to the column label. The taper of the symbol shape ▼ indicating larger/later to smaller/earlier top to bottom (descending), and ▲ smaller/earlier to larger/later top to bottom (ascending). Manual sorting is accomplished by clicking on the column label. This reverses the current sort order.
The examples above include the basic sortable listing.
The sortable listing by default generates the standard WASD ascending by name listing. It is also possible to automatically sort a listing on a particular column when it is generated. This is done with an additional parameter specifying the layout column character as used in 3.3.2 - Layout. The default is to list top-to-bottom ascending order. An optional "-" lists top-to-bottom in descending order (the redundant "+") is also accepted.
Examples of automatic sort on size, descending size, revision data and descending revision date are below.
*.*?httpd=index&style=sort&sort=s
*.*?httpd=index&style=sort2&sort=s-
*.*?httpd=index&style=sort&sort=r+
*.*?httpd=index&style=sort2&sort=r-
Programmatic listing from JavaScript embedded in a README.HTML or enclosing SSI document can be performed by calling the wasdDirSort() function with a string parameter containing the column character and optional order character. The following example sorts descending by size.
<script language="JavaScript">wasdDirSort('S-')</script>
To make all directory listings for a server or site sortable, place the following mapping rule appropriately close to the top of relevant mapping rules.
SET * dir=style=sort
The WASD directory listing permits the use of VMS wildcards in the file specification. This directly allows selected listings of files. For example, all files, all the SDML files in this document's directory, all the HTML files, and finally all the files containing 01 in the name.
*.*
*.sdml
*.html
*01*.*
In addition, it is possible to selectively include and/or exclude selected files using the server directive ?httpd=index&these=. The parameter is one or more, comma-separated file name specifications which may contain wildcards. The directory listing usually would have file name and type wildcard (though can be a selector in itself) and then files are selected using using the above directive. If a selector is preceded by an exclamation point ("!") this excludes matching files. Matching is first to last and the first match hit is applied.
The following examples provide the equivalent listings to the examples above.
*.*?httpd=index&these=*
*.*?httpd=index&these=*.sdml
*.*?httpd=index&these=*.html
*.*?httpd=index&these=*01*.*
This example lists all of the files above in the one listing.
*.*?httpd=index&these=*.sdml,*.html,*01*.*
This example lists all files except those with an .HTML type.
*.*?httpd=index&these=!*.html
Historically and by default, directory listings are provided in a monospace font. The parent document or browser (proprtional) font may be used instead with the ?httpd=index&font=inherit directive. This can only be used with the sortable and tabular (post-v10.4) listings. Historical listing styles are only suitable for monospace fonts.
*.*?httpd=index&font=inherit
There is the per-path SET dir=font=inherit mapping rule equivalent.
As described above, a directory listing can be requested in a VMSish style by appending a version delimter to the URL file specification, with multiple versions of the file, where they exist, displayed with version number.
Multiple versions may also be selectively listed using the ?httpd=index&versions= directive. The parameter can be an integer representing the maximum number of versions to be listed, or an asterisk wildcard indicating all versions should be listed.
?httpd=index&versions=0 ?httpd=index&versions=3 <A TARGET="_blank" HREF="*.*?httpd=index&versions=*">*.*</A>
There is the per-path SET dir=versions= mapping rule equivalent.
When a directory listing is generated any "README.", "README.TXT" or "README.HTML" file (or others as configured for the particular server) in the directory will have the contents displayed immediately below the title of the page. This allows additional information on the directory's contents, function, etc., to be presented. This can be suppressed by appending the following query-string to the directory specification, as in the accompanying example:
?httpd=index&readme=no <A TARGET="_blank" HREF="*.*?httpd=index&readme=no">*.*</A>
Read-me files can be SSI documents if configured by the server administrator. General SSI guidelines apply to these, see 4 - Server Side Includes (SSI)
A directory listing is normally delimited by a header, comprising an "Index of", column headings and horizontal line, and a footer, comprising a horizintal line. This default behaviour may be modified using the "delimit=" directive.
?httpd=index&delimit=none ?httpd=index&delimit=top
Parent and subdirectories may be suppressed in a listing using the "nop", "nops" and "nos" directives. These parallel the purpose of the directory listing control files described in 3.1 - Controlling Access To A Directory, and if set to true suppress the listing of the corresponding directories.
?httpd=index&nop=yes ?httpd=index&nops=yes ?httpd=index&nos=yes
Directory listings and trees may be pre-expired. That is, the listing is reloaded each time the page is referenced. This is convenient in some environments where directory contents change frequently, but adds considerable over-head and so is often disabled by default. Individual directory listings may have either default behaviour over-ridden using syntax similar to the following examples:
/dir1/dir2/*.*?httpd=index?expired=yes /dir1/dir2/*.*?httpd=index?expired=no /tree/dir1/dir2/?httpd=index?expired=yes /tree/dir1/dir2/?httpd=index?expired=no
When a directory listing is requested a script name can be specified to be used as a prefix to all of the file links in the listing. When the client selects a file link the script specified is implicitly activated.
?httpd=index&script=script_name <A TARGET="_blank" HREF="*.*?httpd=index&script=/cgi-bin/liner">liner *.*</A>The following link illustrates this facility by specifying the liner script. When a link is selected the liner script presents the file with preprended line numbers:
liner *.*
The server's auto-scripting facility (see description of [AddType] configuration directive in the Technical Overview) can be suppressed by appending the following query-string to the directory specification, as in the accompanying example:
?httpd=index&autoscript=no <A HREF="*.*?httpd=index&autoscript=no">get me *.*</A>
This implies that any file accessed from the listing will be transfered without any data conversion possible due to script activation. The browser must then process the document in some fashion (often by activating a save as dialog).
Files generally open in the current browser window. It is possible to open a file in another window using the target= directive.
?httpd=index&target=_blank <A HREF="*.*?httpd=index&target=_blank">example *.*</A>
example *.*
|
When accessing files it is possible to explicitly specify the identifying content-type to be returned to the browser in the HTTP response header. Of course this does not change the actual content of the file, just the header content-type! This is primarily provided to allow access to plain-text documents that have obscure, non"-standard" or non-configured file extensions. See 2.2 - Explicitly Specifying Content-Type.
It could also be used for other purposes, "forcing" the browser to accept a particular file as a particular content-type. This can be useful if the extension is not configured (as mentioned above) or in the case where the file contains data of a known content-type but with an extension conflicting with an already configured extension specifying data of a different content-type.
It is posssible to "force" the content-type for all files in a particular directory. Enter the path to the directory and then add
?httpd=index&type=text/plain
(or what-ever type is desired). Links to files in the listing will contain the appropriate "?httpd=content&type=..." appended as a query string.
This is an example:
*.*
*.*?httpd=index&type=text/plain
YMMV
Some browsers and operating systems insist they know better than the server and ignore the response-specified content-type, inferring presentation of the content from magic bytes in that content or the trailing dot-separated file name extension.
Directory listing icons are generally links to the content of the file displayed as plain-text (Listing Icons). This can be disabled using the ilink directive.
?httpd=index&ilink=no <A TARGET="_blank" HREF="*.*?httpd=index&ilink=no">get me *.*</A>There is a per-path mapping "SET dir=noilink" equivalent.
The query=<string> directive can be used to propagate an explicit query string to subsequent directory requests. This is intended to be applied from a .WWW_WASD control file because actual URI query strings are propagated by default.
# an example .WWW_WASD file query=httpd=index&style=sort2&sort=s-
When a .WWW_WASD file is present in a directory it takes precedence over any SSI or URI (query string) directives also available, unless it includes an override=yes directive. When this is present any SSI and/or URI directive string is also applied to the request.
# an example .WWW_WASD file override=yes
The "Tree" internal script allows a directory tree to be generated. This script is supplied with a directory name from which it displays all subdirectories in a hierarchical layout, showing subordinancies. Selecting any one of the subdirectories displayed generates a directory listing (see 3 - Directory Listing).
Appending a file specification (with or without wildcards) to the directory name results in the any directory listing displaying only files matching the specification. To display all files a "*.*" should always be appended.
Note that this script only processes the physical file system. This may or may not correspond to the web environment's virtual mappings.
To enable the VMS-style directory listing format, or to use any of the directory server directives, append one, or a combination of, the following query strings to the directory specification:
?httpd=index&autoscript=no ?httpd=index&readme=no ?httpd=index&script=script-name ?httpd=index&script=script-name&readme=no
The following links provide online demonstrations:
/wasd_root/ tree
/wasd_root/ (VMS-ish) tree
Note that this activity is I/O intensive, and can take a considerable period if the tree is extensive.