Next: gethelp() Up: MacAnova Help File Previous: getdata()   Contents

getfilename()

Usage:
name <- getfilename([cancelok:T])
name <- getfilename(type:"data" or type:"restore" [,cancelok:T])
name <- getfilename(fileonly:T ...[,cancelok:T])
name <- getfilename(pathonly:T ...[,cancelok:T])
name <- getfilename(help:T [,fileonly:T  or  pathonly:T])
name <- getfilename(last:T [,fileonly:T  or  pathonly:T])



Keywords: files, input, output
                                  Usage
On windowed versions 

  Cmd> fileName <- getfilename()

brings up a file navigation dialog box in which you can select a file;
the complete path name (file name with directory information) of the
file is saved as a CHARACTER scalar in fileName.  It is an error if the
dialog box is cancelled without selecting a file.

  Cmd> fileName <- getfilename(cancelok:T)

does the same except it is not an error when the dialog box is cancelled
without selecting a file.  It that case, fileName is set to NULL.

There are two usages that are available on any version

  Cmd> fileName <- getfilename(help:T)

returns the name of the current help file.

  Cmd> fileName <- getfilename(last:T)

returns the name of the last file successfully opened by any MacAnova
command, either for reading or for writing.

                                Keywords
fileName <- getfilename(nameonly:T [,last:T or help:T] [,cancelok:T])
does the same, but only the name of the file, excluding the directory
information (path), is returned.

pathName <- getfilename(pathonly:T [,last:T or help:T] [,cancelok:T])
does the same, but only the directory information is returned.

It is an error to use both nameonly:T and pathonly:T as arguments.

On a Mac OS 9, without last:T or help:T, the files displayed in the
file navigation dialog box are limited to text files such as data files
and workspace files created by save().  To further restrict the files
displayed to text files, include keyword phrase type:"text" as an
argument.  Keyword 'type' can be used with 'nameonly:T' and
'pathonly:T'.  It has no effect in non-Macintosh versions.

                               When to use
One use for getfilename() is as an argument to macro addmacrofile():

  Cmd> addmacrofile(getfilename())

allows you interactively to choose a file to be added to the list of
macro files to be searched.

A similar use is as an argument to adddatapath():

  Cmd> adddatapath(getfilename(pathonly:T))

adds to variable DATAPATHS the name of the folder or directory
containing the file selected.  DATAPATHS contains a list of directories
that are searched when a file is not found in the current default
directory.

A use for 'help:T' might be in a macro searching several help files to
enable it to restore the current help file when it was done.

A use for 'last:T' might be in a macro which uses vecread() with
'silent:T' and you want to retrieve the name of the file read.

The following macro fragment should do that:
  @filename <- argvalue($1,"file name","string")
  @x <- vecread(@filename, silent:T)
  print(paste("Reading data from file",getfilename(last:T)))
  . . . .

See topics 'macros' and 'macro_syntax' for information on writing
macros.


Gary Oehlert 2006-01-30