Riverwatcher Active Content Environment

RACE Documentation:

Working With Files and Directories
a. Input
b. Output
c. Calling an External Program
d. File and Directory Manipulation



RACE let's you include scripts contained in another file using the include tag. Any RACE code in the included file will executed and the output will be inserted into the current output stream at the point where the include tag was invoked.

<include file="header.race">

The example above will include the script "header.race" that resides in the same directory as the current script. You can include files residing in other directories by specifying the full or relative path. One exception to this is that you will be restricted to within the document root directory when you are running a RACE script as a web server script. This restriction does not apply to shell scripts.

What if you want to include file that does not contain any RACE code and you do not want the interpreter waste time trying to look for RACE code in the included file? You can use the asis attribute of the include tag, e.g.:

<define var="$data" asis><include file="datadir/excel.out"></define>

Now the variable $data contains the content of the file excel.out.


There will be times when you want to write data out to a file for permanent storage and you will want to use the output tag.

<output file="mydata"><$name></output>

The above command will save the content of the variable $name into the file mydata. If the file mydata does not exist, it will be automatically created. If the file already exists, its content will be replaced.

If you do not want to replace the existing content of the file but appending to it, you can use the append attribute of the output tag, e.g.:

<output file="mydata" append><$name></output>

Calling an External Program

While you can do a lot with what is build into RACE, there will be times when you want to call on the help of an external program. To that end, RACE allows you execute an external program and include the output that program in the output stream.

<include cmd="cal" asis>

The above example would execute the UNIX calendar command "cal" and display the output of that command. You can pass command line arguments as well, e.g.:

<include cmd="cal 8 2003" asis>

Some programs take input via the standard in. The include tag allows you to pass data to the standard in of the external program, e.g.:

<include cmd="wc" output>word, words, and more words</include>

In the example above, the output attribute lets RACE interpreter know that you want to output something to the standard in of the external program. You can put any valid RACE code in the body of the include tag and they will be first executed and the result will be passed on to the external program, e.g.:

<include cmd="wc" output asis>
<for key="$name" list="[joe, steve, aaron]">

File and Directory Manipulation

Now that you know how to read from and write to files, what about manipulating them such as renaming a file, deleting a file, or creating a new directory? All these file system related needs can be addressed with the file tag.

To check the existence or status of a file, you can use "get" action of the file tag, e.g.:

<file action="get" property="exist" name="/usr/bin/sh">
<file action="get" property="type" name="/usr/bin">
<file action="get" property="size" name="/usr/local/bin/race">

In the second example above, the get operation would return the value "directory" since "/usr/bin" would be a directory on most UNIX systems. You can get a full list of properties the get operation supports from the RACE Reference.

To rename a file or a directory, you can use the rename action along with the original path and the new path, e.g.:

<file action="rename" from="/tmp/oldfile" to="/tmp/newfile">

To create a directory, you can use the create action and make sure that your path name ends in a slash "/", e.g.:

<file action="create" name="/tmp/newdir">

If there are any problems with the file operation, an error will be reported in both <@system.errors> array and <$system.error>. We will talk more about these two special debugging variables later, in our section on debugging.

RACE Documentation

Copyright 2009 Riverwatcher, Inc. Hosting by Riverwatcher Studios