HTdir - archive browser scripts.

HTdir is a set of archive browsing CGI scripts based on the same rules, layout and control. The same requirements can be used not only for archive browsing - any other structure outside the VMS file structure supported by http server can be supported by the corresponding script.

The simple DCL demo - HTdir shows the browsing basics on VMS directory structure. If You have HTdir installed and configured - You can try it:

The following scripts are available now:

The concept allows not only browse the existing archives. Any directory tree can be archived/compressed and will be vizible as if nothing was done against it. The access to such archives requires much more CPU resources then the traditional file access and is not recommended for frequently accessed directory trees.

The random/sequential archive type should be taken in consideration. The random accessable archives such as ZIPs require much less file activity then the sequential ones such as backup savesets and TARs.

Here are some common requirements for current and future scripts.

Compound path.

The compound requested path consists of script, file and component subpaths, represented as a single path to the client to make possible relative references. The script subpath is detected according to the server mapping rules. All the rest is the path, represented by WWW_PATH_INFO CGI variable. The file subpath is extracted from path until the first "/" after first "." or until the end of path. All the rest is the component subpath. E.g.:

/cgi-bin/script/dir/file.type/idir/ifile.itype

is parsed as

/cgi-bin/script - script
/dir/file.type - file
/idir/ifile.itype - conponent

The file subpath is mapped to real file using the server MAP-PATH: callout as WWW_PATH_TRANSLATED doesn't represent a real file. The component subpath is mapped to archive component in script-specific manner. No any request components other then path should affect the file and component mapping.

Response types.

The script supports three types of responses other then error - file, list and redirect.

The redirection is used when the path doesn't point to a supported file type - in such a case the internal redirection is made directly to the path causing the server fulfil the request.

Location: <WWW_PATH_INFO>

In addition redirection is used when the component subpath is emty - in such a case the external redirection is used to cause the client treat the archive as the directory.

Location: //<WWW_SCRIPT_NAME><WWW_PATH_INFO>/

The file response is used when the component subpath points to the component file - not a subdirectory (doesn't end with "/"). In such a case the component file is extracted and passed to the server after CGI header. In most cases WWW_CONTENT_TYPE should represent the valid content type for the file and can be used for CGI response.

Content-type: <WWW_CONTENT_TYPE>

The valid transfer mode should be reported to the server using Script-control: CGI header line.

The list response is used when the component subpath points to the component subdirectory or root directory (ends with "/"). In such a case the script rsponds with HTML page containing directory listing. The listing of subdirectorys of the current directory should be suppressed, the subdirectorys should be included in the listing instead.

Directory listing structure.

The directory listing is the HTML page consisting of HTML header and HTML body. HTML body consists of header, directory and footer. Directory consists of border and listing. Header consists of title and readme.

HTheader
HTbody
HTbody.header
HTbody.header.title
HTbody.header.readme
HTbody.directory
HTbody.directory.border
HTbody.directory.listing
HTbody.footer

h
e
a
d
e
r
t
i
t
l
e
Any configured HTML - WWW_HTML_HEADER parameter.

//host/path/file.type/ipath/

The first title line references to all the upper paths. The "file." portion points to the archive itself to make it downloadable. <H3><NOBR> is recommended.

r
e
a
d
m
e
Readme of the current directory.
Extracted from the archive (if available).
The <PRE> representation is recommended.
d
i
r
e
c
t
o
r
y
b
o
r
d
e
r
 [   ]  Name                                Revised        Size
















l
i
s
t
i
n
g
 [DIR]  dir1/                     13-Jan-2003 12:51           0
 [DIR]  dir2/                     13-Jan-2003 12:51           0

 [???]  file1.type                13-Jan-2003 12:51         512
 [???]  file2.type                13-Jan-2003 12:51       12345
b
o
r
d
e
r

f
o
o
t
e
r
Any configured HTML - WWW_HTML_FOOTER parameter.

The border should be preformatted and bold (<PRE><B> </B></PRE>)

The colors, fonts, etc. of the page are controlled via WWW_HTML_BODYTAG parameter. The same parameters for the header and footer are controlles via WWW_HTML_HEADERTAG and WWW_HTML_FOOTERTAG respectively. E.g.

WWW_HTML_BODYTAG = "BGCOLOR=#FFEBCD"

causes:

<BODY BGCOLOR=#FFEBCD>

Tables are used to support WWW_HTML_HEADERTAG and WWW_HTML_FOOTERTAG. If these are absent - the corresponding tables shouldn't be generated. If WWW_HTML_HEADERTAG or WWW_HTML_FOOTERTAG begins with "<" character - it's treated as a full "<TABLE><TR><TD>" tag and inserted as-is without prepending "<TABLE>", etc.

WWW_HTML_HEADER and WWW_HTML_FOOTER parameters define any HTML to be inserted in the page header and footer.

All the above parameters can be set using "set ... html=parameter=value" mapping rule.

The same set of parameters can control SSI document layout.

Form parameters are used for additional page layout control. This parameters can be passed to HTdir scripts via "set ... script=params=(FORM_name=value)" mapping rule or via URL query string "...?name=value". In both cases httpd will prepend "WWW_" prefix.

This parameters are experimental, may be non-functional and are reserverd for the future.

Parameter WWW_FORM_HTML_PLAYOUT controls the presence of the directory listing page components. Any letter in WWW_FORM_HTML_PLAYOUT corresponds to the page component:

All components are present by default (WWW_FORM_HTML_PLAYOUT="HTRBLF").

Parameter WWW_FORM_UPD controls the checkboxes and other update elements.

Wildcards and query strings in HREFs.

The title HREFs to the upper-level dirs outside the archive should contain "*.*" to suppress the index file substitution. If there is only one file type supported by script "*.type" should be used instead of "*.*"

The subdir and file listing HREFs and the title HREFs to the upper-level dirs inside the archive should copy wildcards from the initial request.

The initial request's query string should be appended to all HREFs.

Wildcards and query strings shouldn't be present in the visible resource name and in the <A NAME=...> anchor.

Listing record structure.

The listing consists of entry records representing components - files and directorys. Any record contains anchor, checkbox, icon, name and informational fields, such as date, size, etc.. The primary record parameter is the corresponding resource name and is represented as file ("file", "file.", "file.type", "file.type;version", etc.) and directory ("directory/") - let's call it "resource". The resource name is relative to the current path and doesn't contain the path itself.

The anchor field is an anchor with the resource name. It can be used for external referencing to the resource in the long listings via "#resource" URLs.

<A NAME=resource>

The checkbox field is a checkbox named "SEL" with the resource value. It can be used by JavaScript executing from other frame - e.g. file manager. This field requires the presence of <FORM> tag in the listing.

<INPUT TYPE=CHECKBOX NAME=SEL VALUE=resource>

The icon field is the icon representing the resource type and referencing to the resource. The full IMG tag can be accepted from the server callback "ICON-TYPE: resource". The special icons can be accepted the same way with "x-internal/blank", "x-internal/unknown", "x-internal/directory" instead of resource.

<A HREF=resource>
<IMG ALIGN=top BORDER=0 SRC=/httpd/-/icon.gif ALT="[???]">
</A>

The name field is the resource name referencing to the resource. If the resource name length is less then the field length (24 default) - the name field is appended with spaces. If the resource name is longer then the field length - the name is truncated to one less then the field length and appended with "+". If the component is subdirectory - the name should be bold (<B>resource</B>).

<A HREF=resource>resource</A>

Other fields are script-specific.

Reference redirection.

This parameters are experimental, may be non-functional and are reserverd for the future.

All the directory listing references can be redirected to other script and/or window using the <BASE> HTML tag and WWW_FORM_HTML_BASE, WWW_FORM_HTML_TARGET parameters. WWW_FORM_HTML_TARGET defines the target window for all HREFs in the page. WWW_FORM_HTML_BASE prefixes it's value to the current compound path for the new document HREFs base. E.g.:

WWW_FORM_HTML_TARGET = "NewWindow"
WWW_FORM_HTML_BASE = "/NewScript"
path = "/script/path/file.type/ipath/"
causes:

<BASE HREF=/NewScript/script/path/file.type/ipath/ TARGET=NewWindow>

in HTML header. Thus NewScript will accept the compound path as WWW_PATH_INFO, process it or redirect internally to current script. All the output will be passed to NewWindow.

Directory listing example.

Here is the HTML source of the example directory listing.


<HTML> <HEAD> <META NAME="generator" CONTENT="script V0.0"> <TITLE>//host/path/file.type/ipath/</TITLE> <SCRIPT language="JavaScript"><!-- function chkall(ref) { for (idx = 0; idx < ref.form.elements.length; idx++) { if (ref.form.elements[idx].type == 'checkbox') ref.form.elements[idx].checked = ref.checked;} return true } //--></SCRIPT> </HEAD> <BODY BGCOLOR=blanchedalmond>
<TABLE BORDER=0 WIDTH=100%><TR><TD BGCOLOR=lightseagreen>
Here is any HTML from WWW_HTML_HEADER.
<H3><NOBR><A HREF=/script/*.*>//host/</A><A HREF=/script/path/*.*>path/</A><A HREF=/path/file.type;0>file.</A><A HREF=/script/path/file.type/>type/</A><A HREF=/script/path/file.type/ipath/>ipath/</A></NOBR></H3>
<PRE>
And here is the preformatted readme/comment
extracted from the archive/directory.
</PRE>
</TD></TR></TABLE>
<FORM METHOD=POST NAME=LIST ACTION="">
<PRE>
<INPUT TYPE=CHECKBOX ONCLICK=chkall(this)> <IMG ALIGN=top BORDER=0 SRC=/httpd/-/blank.gif ALT="     ">  <B>Name                                Revised        Size</B><HR NOSHADE>
<A NAME=dir/><INPUT TYPE=CHECKBOX NAME=SEL VALUE=dir/> <A HREF=dir/><IMG ALIGN=top BORDER=0 SRC=/httpd/-/directory.gif ALT="[DIR]"></A>  <A HREF=dir/><B>dir/</B></A>                      29-DEC-2002 18:37           0
<A NAME=file.type><INPUT TYPE=CHECKBOX NAME=SEL VALUE=file.type> <A HREF=file.type><IMG ALIGN=top BORDER=0 SRC=/httpd/-/unknown.gif ALT="[???]"></A>  <A HREF=file.type>file.type</A>                 29-DEC-2002 18:37         512
<HR NOSHADE></FORM></PRE>
<TABLE BORDER=0 WIDTH=100%><TR><TD BGCOLOR=lightseagreen>
Here is any HTML from WWW_HTML_FOOTER.
</TD></TR></TABLE>
</BODY>
</HTML>




Availability.

HTdir is free available from S&B web site.