--------------------------
write_file_text() FUNCTION
--------------------------

  ------------
  USAGE FORMAT
  ------------

    Where $rv is the numeric return value:

    $rv = &write_file_text($file, $text);

  -----------
  DESCRIPTION
  -----------

    The write_file_text() function opens the requested file and
    writes/overwrites it's text contents with the requested text.

  ---------
  ARGUMENTS
  ---------

    $file

      REQUIRED
      
      The path/name of the file to be opened. This path may be either the
      absolute system path, or the path relative to the location of the calling
      PTM script file.

    $text

      REQUIRED

      The text to write to the file. If this field is left blank, no text is
      written.

  -------
  RETURNS
  -------

    1 if successful.
    0 if not successful.

  --------------
  USAGE EXAMPLES
  --------------

    ----------------------------------------------------
    Example 1: Writing "Test" to a File Named "Test.txt"
    ----------------------------------------------------

      <? &write_file_text('Text.txt', 'Test'); ?>

  --------
  SEE ALSO
  --------

    TAGS

      DO

    FUNCTIONS

      append_file_text(), get_file_text()