htp on-line reference : FILE

syntax

<file execute="command-line" (output="filename" | redirect) [noerror]>
<file include="includefilename" [parameters ...]>
<file name>
<file [ name="filename" ] size[ = (byte|kbyte|mbyte|gbyte) ] [precision=n]>
<file [ name="filename" ] time[ ="format" ]>
<file [ name="filename" ] date[ ="format" ]>
<file search="searchpath">
<file template="templatefilename">



synopsis

As with all HTML, these tags do not have to be on their own line, so the following is perfectly acceptable:

    <EM>File "<FILE NAME>" last updated <FILE TIME>, <FILE DATE></EM>


NAME, TIME, SIZE

To include information about another file, such as an archive file or graphic image, specify its name with the NAME attribute followed by the type of information to be displayed:

    File image.gif <FILE NAME="image.gif" SIZE=KBYTE> kilobytes
    Last modified <FILE NAME="image.gif" TIME>, <FILE NAME="image.gif" DATE>


For file size information, the value BYTE, KBYTE, etc. dictates how the information is displayed. In anything other than byte format, the information is displayed in floating-point notation. The amount of precision (the number of digits to the right of the decimal point) can be set with the optional PRECISION attribute. The default precision is zero (0), which means no fractional portion is displayed.

At the request of many people, the TIME and DATE attributes will now accept formatting characters that are passed directly into the ANSI C library function. This allows for the time and date to be displayed in virtually any format. Users not wishing to mess around with this should stick to the default format, which is used if no formatting value is specified (i.e., just using 12:23:41 PM).

Consult any C programmer's guide discussing the standard C library function strftime() for information on how to build a format string. If unsure, ask an experienced C programmer for help, or consider just sticking to the default formatting.

INCLUDE

INCLUDE files are pre-processed as any other file. The resulting text is incorporated into the HTML output as if the file had been copied into the source at the same location as the FILE markup tag.

htp will automatically convert slashes and backslashes to match the operating system's directory separator.

Additional parameters can be set in the FILE INCLUDE tag, which are interpreted as macros that are "passed" to the included file. The macros are available only to the include file (and any macros or included files it holds). After the file is completely included, the macros are no longer available. So:

    <FILE INCLUDE="include.hti" name="Jim Nelson" email="jnelson@crl.com">
    This tag will fail: <USE name>


Macros named "name" and "email" are set, and available inside the included file. They are not available, however, past the tag (which is why the second statement will fail.)

TEMPLATE

A template file is nothing more than a default include file, one that is included once the input text has been completely processed. So, an input file can define many "standard" macros, which are then expanded by a template file to form a consistent page layout.

The template file can be set many times, but only the last filename specified will be processed by htp. If multiple template files need to be included, specify one template file, and from that file use FILE INCLUDE to branch off.

Template files are most useful when placed inside an htp default file.

SEARCH

A search path can be specified, which is searched if an include file cannot be found. This is handy to keep a set of "common" include files that many documents in many directories may need to access. More than one directory can be specified in the search path, if they are separated by a semi-colon. Spaces should not precede or trail the search path string.

When htp starts, the search path is clear. FILE SEARCH would be a handy command to use in an htp defaults file.

EXECUTE

When FILE EXECUTE is used, htp will launch a program (as specified by the EXECUTE attribute) and include its output as if a FILE INCLUDE was performed on the file. Either the OUTPUT or REDIRECT attribute must also be included.

OUTPUT specifies the file the command will produce. This is used if the program is either hard-coded to produce output to a particular file, or relies on one of its command-line arguments to determine where to place the output. The output file is deleted after its results have been imported into the output file.

If the program produces output straight to standard output (as most UNIX and some DOS programs do), then the REDIRECT attribute can be used. In this case htp will take care of the redirection. Depending on the OS features it will either append a '>' and the name of a temporary file or it will use pipe mechanism to directly redirect without temporary files.

htp will halt processing with an error if the executable exits with an error code of anything but zero (0). Some programs, however, do not specify an error code when exiting, so the exit code is undetermined. If htp should ignore the error code, specify the NOERROR attribute.