CML Reference Guide

Chapter 4.3:  File Access


Include the entire text of file name at this point.

The $file() function should only be used to include relatively short (a couple of lines, maximum) files, such as when you need to include the contents of a file in the middle of an HTML or SET string that you are building.  Name is relative to the CML_Path directory specified in the swebd.conf file.  (See the Caucus installation guide for details.)

If you need to include a large file, or one that contains CML directives, see the "include" directive in section 5.

Evaluate to the entire contents of text file nameName should be the full pathname of a file on the server host.  Whereas $file() is meant as a way to include additional CML code in a page, $readfile() is meant for reading data that will somehow be processed or displayed by a CML page.

$write(name text)
Write text to file with absolute pathname name.  Overwrites previous contents of name, if any.

$append(name text)
Append text to file with absolute pathname name.

Truncates name to the first 8 characters, and replaces all dots (".") with underscores ("_").  Useful when name refers to a file on the client machine.

$copy2lib(file libname)
Copies file (a full pathname) to a new file called libname, in the Caucus file library.  (See the parameters Caucus_Lib and HTTP_Lib in the swebd configuration file swebd.conf for more information about the Caucus file library.)  Libname may contain sub-directory names, and is always treated as relative to the root of the Caucus file library.  Sub-directories are created automatically.  Thus a libname of "demo/xyz" would copy file to a file called "xyz" in a sub-directory "demo" under the Caucus file library, and would automatically create the "demo" directory if needed.

The function evaluates to the full URL of the newly created file, thus making it possible to make the file immediately available on the Web in any subsequently produced HTML.

$open(name perm)
Open a file name for reading (if perm is "r"), for writing (if perm is "w"), or to append to (if perm is "a").  Evaluates to a number which is the file "handle", or to "0" if the file could not be opened.

$readln(handle var)
Read a line from the file open on handle, and put the text into variable var.  Evalutes to "1" if successful, or to "0" on end-of-file.

$writeln(handle text)
Writes text to the file open on handle.  Evaluates to "1" on success, or "0" if handle does not refer to an open file.

Close file open on handle.

$rename(a b)
Rename file a to file b.

Delete file a.  Must use full pathname of file.

$file_data(name bytes range...)
Checks the first bytes characters of file name to see if its contents fit within certain byte-value ranges.  (A bytes value of -1 means "check the entire file".)

Range is one or more byte values or byte value ranges, expressed as decimal numbers.  For example "32" is the decimal code for a "blank" character, and the range "65-90" covers the codes for the upper-case letters A through Z.

$file_data() evaluates to 1 if the first bytes characters of name are included in the range values, and 0 otherwise.  Thus, for example, $file_data(name 500 32 65-90) would evaluate to 1 if the first 500 characters were either blanks or the letters A-Z, and 0 otherwise. 

A good use of $file_data() is to determine if a file contains only "plain text", or is some other kind of file (word processor file, image file, etc.)  If $file_data (name -1 9-26 32-126) is 1, name is most likely a text file.

$dirlist(format dir)
If format is 0, evaluates to a space-separated list of the files (and directories) in directory dir.  If format is 1, each filename is immediately followed by a space and the size of the file in bytes.

$output(name mask)
Normally, CML lines that begin with a double-quote (") are interpreted and sent directly to the user's browser.  The $output() function redirects this text, and writes it to a file name, instead.  Mask is the numeric Unix file permission mask, e.g. a value of "644" means read/write owner, read group, and read world.

The redirection takes effect on all quoted lines that follow the use of $output().  Another call to $output(), with no arguments, returns subsequent output from quoted lines to the browser, in effect "closing" the file.