@database DOS&FileControl.guide
@remark ENGLISH VERSION
@author Eddie Churchill
@(c) "Copyright © 1993 Inovatronics, Inc."
@$VER: DOS&FileControl.guide 2.5 (06/01/93)
@wordwrap
@font topaz.font 8
@index "CanDo_LexiconIndex"

@node "CanDo_DOS & File Control_Index" "DOS & File Control Commands, Functions and Variables"
@toc "CanDo_LexiconMain"
@{fg highlight}Available Topics...@{fg text}

  Function @{" =AskForFileName()              " link "CanDo_AskForFileName"}
  Function @{" =AskForHelp()                  " link "CanDo_AskForHelp"}
  Function @{" =AskForResponse()              " link "CanDo_AskForResponse"}
  Command  @{" Close                          " link "CanDo_Close"}
  Command  @{" Dos                            " link "CanDo_Dos"}
  Command  @{" Echo                           " link "CanDo_Echo"}
  Function @{" =Exists()                      " link "CanDo_Exists"}
  Function @{" =FileOf()                      " link "CanDo_FileOf"}
  Command  @{" FileReadChars                  " link "CanDo_FileReadChars"}
  Command  @{" FileReadLine                   " link "CanDo_FileReadLine"}
  Function @{" =FileSize()                    " link "CanDo_FileSize"}
  Function @{" =FileType()                    " link "CanDo_FileType"}
  Command  @{" FileWriteChars                 " link "CanDo_FileWriteChars"}
  Command  @{" FileWriteLine                  " link "CanDo_FileWriteLine"}
  Command  @{" GetDiskInfo                    " link "CanDo_GetDiskInfo"}
  Command  @{" GetFileInfo                    " link "CanDo_GetFileInfo"}
  Command  @{" InsertDeviceList               " link "CanDo_InsertDeviceList"}
  Command  @{" InsertDirectoryList            " link "CanDo_InsertDirectoryList"}
  Command  @{" OpenFile                       " link "CanDo_OpenFile"}
  Function @{" =ParentOf()                    " link "CanDo_ParentOf"}
  Function @{" =PathAndFile()                 " link "CanDo_PathAndFile"}
  Function @{" =PathOf()                      " link "CanDo_PathOf"}
  Command  @{" SetCurrentDirectory            " link "CanDo_SetCurrentDirectory"}
  Command  @{" SetFileBufferSize              " link "CanDo_SetFileBufferSize"}
  Command  @{" SetFileRequestMode             " link "CanDo_SetFileRequestMode"}
  Command  @{" SetFileRequestPattern          " link "CanDo_SetFileRequestPattern"}
  Command  @{" SetStandardOut                 " link "CanDo_SetStandardOut"}
  Command  @{" SetSystemRequesterTo           " link "CanDo_SetSystemRequesterTo"}
  Variable @{" =TheCurrentDirectory           " link "CanDo_TheCurrentDirectory"}
  Variable @{" =TheOriginDirectory            " link "CanDo_TheOriginDirectory"}
@endnode

@node "CanDo_askforfilename" "Let {name}=AskForFileName({def} [,{title} [,{x} [,{y} [,{w} [,{h}]]]])"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {name}=AskForFileName({def} [,{title} [,{x} [,{y} [,{w} [,{h}]]]])

@{fg highlight}Parameters...@{fg text}

      def = the default file or directory to select
    title = the requesters window title
        x = the left position of the requester
        y = the top positoin of the requester
        w = the width of the requester
        h = the height of the requester

@{fg highlight}Returns...@{fg text}

  A string containing the selected files or directories.

@{fg highlight}Description...@{fg text}

  Brings up the File Requester provided in the Amiga's asl.library,
allowing your application to ask users for a file name which they can
locate.  The default file name must be specified, with an optional window
title, positioning, and sizing.

  Unless the MULTISELECT option is chosen using the @{" SetFileRequestMode " link "CanDo_SetFileRequestMode"}
command, this function returns a single file or directory name in a string,
or an empty string ("") if no files are selected or if CANCEL is pressed.

  If the MULTISELECT Mode is set using @{" SetFileRequestMode " link "CanDo_SetFileRequestMode"}, a single
string is still returned, but with each selected file or directory
separated by a line feed (CHAR(10)) character.  It is therefore easy to
@{" Type " link "CanDo_Type"} the string into a Document Buffer to have each entry appear on a
separated line, or you can separate the individual selections using the
@{" GetWord " link "CanDo_GetWord"} function, using CHAR(10) as the word delimeter.  For example:

  SetFileRequestMode MULTISELECT,NONE
  Let I = AskForFileName("Workbench:","Select Files")
  If NumberOfWords(I,CHAR(10))>1
    Let Second = GetWord(I,2,CHAR(10))
  EndIf

When this script is finished, the variable Second will be set to the second
selected file (if more than one was selected).

  SEE ALSO: @{" SetFileRequestMode    " link "CanDo_SetFileRequestMode"}
            @{" SetFileRequestPattern " link "CanDo_SetFileRequestPattern"}.

@endnode

@node "CanDo_askforresponse" "Let {select}=AskForResponse({message} [,{title} [,{choices}]])"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {select}=AskForResponse({message} [,{title} [,{choices}]])

@{fg highlight}Parameters...@{fg text}

  message = the message to display (string may have
            linefeed characers).

    title = the window title for the requester

  choices = the options that the user may select (the string is
            a series of options separated by the "|" character, e.g.
            "Okay|Cancel").

@{fg highlight}Returns...@{fg text}

  The number of the selection.  If the choices where "Okay|Cancel", and a
user pressed the "Cancel" butten, this function would return 2; if they
pressed the "Okay" button, it will return 1.

@{fg highlight}Description...@{fg text}

  This function is useful for presenting a user with choices.  It will open
up a requester and wait for a response from the user before continuing to
execute the current script.

@endnode

@node "CanDo_askforhelp" "Let {error}=AskForHelp({filename} [,{nodename}])"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {error}=AskForHelp({filename} [,{nodename}])

@{fg highlight}Parameters...@{fg text}

  filename = the file name of the amigaguide file to use.
  nodename = the node name within the amigaguide file to start with.

@{fg highlight}Returns...@{fg text}

  Currently a Null string.  In the future, this may return the last read
Node Name.

@{fg highlight}Description...@{fg text}

  This function opens up an AmigaGuide help window based on the filename
and the node name.  The filename must refer to a file following the rules
of the Amiga's amigaguide.library.  The current script will pause until the
user closes the help window.

@endnode

@node "CanDo_close" "Close {BufferName}"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Close {BufferName}

@{fg highlight}Description...@{fg text}

  Functionally the same as the @{" Flush " link "CanDo_Flush"} command.

@endnode

@node "CanDo_dos" "Dos {DOS command line} [,<STDOUT>]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Dos {DOS command line} [,<STDOUT>]

@{fg highlight}Description...@{fg text}

  Executes the string specified in "DOS Command" as an AmigaDOS command.
It works as though the command were typed from a CLI Window.  The STDOUT
flag tells the Dos command to use the current CLI or Shell for its output.

@endnode

@node "CanDo_echo" "Echo [{String} [,<NOLINE>]]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Echo [{String} [,<NOLINE>]]

@{fg highlight}Description...@{fg text}

  This simply echoes out some stuff to the console, if there is one.
  
  SEE ALSO: @{" SetStandardOut " link "CanDo_SetStandardOut"}.

@endnode

@node "CanDo_exists" "Let {Logical}=Exists({FilePath})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {Logical}=Exists({FilePath})

@{fg highlight}Description...@{fg text}

  This returns TRUE if the specified filepath exists.

@endnode

@node "CanDo_fileof" "Let {FileName}=FileOf({FilePath})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {FileName}=FileOf({FilePath})

@{fg highlight}Description...@{fg text}

  Extracts the filename from a complete file path specification.  For
example:

    Let MyFileName = FileOf("DF0:Tools/Test")

MyFileName will equal "Test".
  
  SEE ALSO: @{" PathOf " link "CanDo_PathOf"}.

@endnode

@node "CanDo_filereadchars" "FileReadChars {FileReadBufferName}, <VarName>, {Count} [,<HEX>]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  FileReadChars {FileReadBufferName}, <VarName>, {Count} [,<HEX>]

@{fg highlight}Description...@{fg text}

  Reads in {Count} characters from the file associated with the buffer
specified.  The characters read in are put into the given variable.

  If the HEX flag is given, the incoming characters are converted into
a hex string.  You can use the @{" HexToChars " link "CanDo_HexToChars"}, @{" CharsToHex " link "CanDo_CharsToHex"}, @{" HexToInteger " link "CanDo_HexToInteger"}
and @{" IntegerToHex " link "CanDo_IntegerToHex"} functions to manipulate this string.

  SEE ALSO: @{" FileReadLine " link "CanDo_FileReadLine"} and @{" FileWriteChars " link "CanDo_FileWriteChars"}.

@endnode

@node "CanDo_filereadline" "FileReadLine {FileReadBufferName}, <VarName>"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  FileReadLine {FileReadBufferName}, <VarName>

@{fg highlight}Description...@{fg text}

  Reads a line from the file associated with the buffer specified.  The
lines read in are put into the given variable.
  
  SEE ALSO: @{" FileReadChars " link "CanDo_FileReadChars"} and @{" FileWriteLine " link "CanDo_FileWriteLine"}.

@endnode

@node "CanDo_filesize" "Let {Integer}=FileSize({FilePath})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {Integer}=FileSize({FilePath})

@{fg highlight}Description...@{fg text}

  Returns the size, in bytes, of the specified file.
  
  SEE ALSO: @{" GetFileInfo " link "CanDo_GetFileInfo"}.

@endnode

@node "CanDo_filetype" "Let {String}=FileType({FilePath})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {String}=FileType({FilePath})

@{fg highlight}Description...@{fg text}

  This will try to figure out the file type of the specifed file.  If the
file type is not known then this function will return the string "Unknown".
  
  SEE ALSO: @{" GetFileInfo " link "CanDo_GetFileInfo"}.

@endnode

@node "CanDo_filewritechars" "FileWriteChars {FileWriteBufferName}, {String} [,{Count} [,<HEX>]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  FileWriteChars {FileWriteBufferName}, {String} [,{Count} [,<HEX>]

@{fg highlight}Description...@{fg text}

  Writes the string to the file associated with the buffer specified.  If a
count is given then only that many characters will be written.
  
  If the HEX flag is given, the outgoing string is assummed to be a hex
string and will be converted back into raw binary data.
  
  SEE ALSO: @{" FileWriteLine " link "CanDo_FileWriteLine"} and @{" FileReadChars " link "CanDo_FileReadChars"}.

@endnode

@node "CanDo_filewriteline" "FileWriteLine {FileWriteBufferName}, {String}"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  FileWriteLine {FileWriteBufferName}, {String}

@{fg highlight}Description...@{fg text}

  Writes the given string to the file associated with the buffer specified.
This command will write a newline character after writing the given string.
  
  SEE ALSO: @{" FileWriteChars " link "CanDo_FileWriteChars"} and @{" FileReadLine " link "CanDo_FileReadLine"}.

@endnode

@node "CanDo_getdiskinfo" "GetDiskInfo {FilePath}, <NumberOfBlocksVar> [,<NumberUsedVar> [,<BytesPerBlockVar>]]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  GetDiskInfo {FilePath}, <NumberOfBlocksVar> [,<NumberUsedVar> [,<BytesPerBlockVar>]]

@{fg highlight}Description...@{fg text}

  This command will allow you to retrieve information about the specified
disk.  See the manual for a full description of this command.
  
  SEE ALSO: @{" GetFileInfo " link "CanDo_GetFileInfo"}.

@endnode

@node "CanDo_getfileinfo" "GetFileInfo {FilePath}, <SizeInBytesVar> [,<NumberOfBlocksVar> [,<AttributesVar> [,<DateVar> [,<TimeVar> [,<CommentVar>]]]]]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  GetFileInfo {FilePath}, <SizeInBytesVar> [,<NumberOfBlocksVar> [,<AttributesVar> [,<DateVar> [,<TimeVar> [,<CommentVar>]]]]]

@{fg highlight}Description...@{fg text}

  This command will allow you to retrieve info about the specified file or
directory.  See the manual for a full description of this command.
  
  SEE ALSO: @{" GetDiskInfo " link "CanDo_GetDiskInfo"}, @{" FileType " link "CanDo_FileType"} and @{" FileSize " link "CanDo_FileSize"}.

@endnode

@node "CanDo_insertdevicelist" "InsertDeviceList [<flags>]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  InsertDeviceList [<flags>]

@{fg highlight}Description...@{fg text}

  Types the list of Devices into the current document.  See the manual for
a full description of this command.

@endnode

@node "CanDo_insertdirectorylist" "InsertDirectoryList [<flags>]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  InsertDirectoryList [<flags>]

@{fg highlight}Description...@{fg text}

  Types the current directory's list of files and/or directories into the
current document.  See the manual for a full description of this command.

@endnode

@node "CanDo_openfile" "OpenFile {FilePath}, {FileIOBufferName}, <IOflags>, <AccessFlags>"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  OpenFile {FilePath}, {FileIOBufferName}, <IOflags>, <AccessFlags>

@{fg highlight}Description...@{fg text}

  Opens a file for input/output purposes.  You can have as many files open
as memory permits.  See the manual for a full description of this command.
  
  SEE ALSO:  @{" FileWriteLine " link "CanDo_FileWriteLine"}, @{" FileWriteChars " link "CanDo_FileWriteChars"}, @{" FileReadLine " link "CanDo_FileReadLine"},
             @{" FileReadChars " link "CanDo_FileReadChars"} and @{" Close " link "CanDo_Close"}.

@endnode

@node "CanDo_parentof" "Let {PathName}=ParentOf({PathName})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {PathName}=ParentOf({PathName})

@{fg highlight}Description...@{fg text}

  This returns the parent directory to the directory pathname given.
  
  SEE ALSO: @{" PathOf " link "CanDo_PathOf"}.

@endnode

@node "CanDo_pathandfile" "Let {FilePath}=PathAndFile({PathName}, {FileName})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {FilePath}=PathAndFile({PathName}, {FileName})

@{fg highlight}Description...@{fg text}

  This combines and returns the pathname and filename given.
  
  SEE ALSO: @{" PathOf " link "CanDo_PathOf"} and @{" FileOf " link "CanDo_FileOf"}.

@endnode

@node "CanDo_pathof" "Let {PathName}=PathOf({FilePath})"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {PathName}=PathOf({FilePath})

@{fg highlight}Description...@{fg text}

  Extracts the pathname from a complete file path specification.  For
example:

    Let MyPathName = PathOf("DF0:Tools/Test")

MyFileName will equal "DF0:Tools/".
  
  SEE ALSO: @{" FileOf " link "CanDo_FileOf"} and @{" ParentOf " link "CanDo_ParentOf"}.

@endnode

@node "CanDo_setcurrentdirectory" "SetCurrentDirectory {PathName}"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  SetCurrentDirectory {PathName}

@{fg highlight}Description...@{fg text}

  This sets the deck's current directory.  See the manual for a full
description of this command.

@endnode

@node "CanDo_setfilebuffersize" "SetFileBufferSize {KiloBytes}"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  SetFileBufferSize {KiloBytes}

@{fg highlight}Description...@{fg text}

  Sets the file input/output buffer size in kilobytes.  The default is 4
kilobytes.  It only applies to buffers opened after this command is used.
  
  SEE ALSO: @{" OpenFile " link "CanDo_OpenFile"}.

@endnode

@node "CanDo_setfilerequestmode" "SetFileRequestMode <type>,<flags>"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  SetFileRequestMode <type>,<flags>

@{fg highlight}Parameters...@{fg text}

  type  = REGULARMODE | SAVEFILEMODE | MULTISELECTMODE
  flags = NONE | FILTERDRAWERS DRAWERSONLY REJECTICONS PATTERNFIELD

@{fg highlight}Description...@{fg text}

  This command sets the modes for the File Requester used by
@{" AskForFileName " link "CanDo_AskForFileName"}.  In SAVEFILEMODE the list of files is displayed in
inverse (so that users can easily detect that they are about to SAVE a
file).  MULTISELECTMODE will allow mutlple file names to be returned on an
@{" AskForFileName " link "CanDo_AskForFileName"} (all in one string, separated by the line-feed character).
The flags specify filtering options available in the File Requester.
REJECTICONS hides .info files from the list; DRAWERSONLY only displays
drawers in the list; PATTERNFIELD provides a field for users to enter a DOS
pattern to apply to the list of file names; and FILTERDRAWERS tells ASL to
use the pattern not only to filter files, but to filter drawers as well.

  SEE ALSO: @{" SetFileRequestPattern " link "CanDo_SetFileRequestPattern"}.

@endnode

@node "CanDo_setfilerequestpattern" "SetFilePattern {Initial} [,{Accept} [,{Reject}]]"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  SetFilePattern {Initial} [,{Accept} [,{Reject}]]

@{fg highlight}Parameters...@{fg text}

  Initial = The First Pattern to use in the Pattern field of the File
            requester.

  Accept  = The pattern which specifies files to be displayed in
            the requester.  (The Initial pattern, and patterns entered
            by the user, apply only to the remaining files.)

  Reject  = Like the Accept pattern, except this pattern indicates
            the files NOT to display in the file list.

@{fg highlight}Description...@{fg text}

  Establishes the filtering patterns to be used by the File Requester which
opens when AskForFileName is used.
  
  SEE ALSO: @{" SetFileRequestMode " link "CanDo_SetFileRequestMode"}.

@endnode

@node "CanDo_setstandardout" "SetStandardOut {FileWriteBufferName}"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  SetStandardOut {FileWriteBufferName}

@{fg highlight}Description...@{fg text}

  Redirects the output of the @{" Echo " link "CanDo_Echo"} command to a file.  The buffer must
first be opened with the @{" OpenFile " link "CanDo_OpenFile"} command.

@endnode

@node "CanDo_setsystemrequesterto" "SetSystemRequesterTo <WINDOW | WORKBENCH | NOWHERE>"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  SetSystemRequesterTo <WINDOW | WORKBENCH | NOWHERE>

@{fg highlight}Description...@{fg text}

  This redirects dos autorequesters to the current WINDOW's screen,
WORKBENCH (default) or to NOWHERE (no requesters at all).  In the case of
NOWHERE, all requesters act as if the user pressed cancel on them.

@endnode

@node "CanDo_thecurrentdirectory" "Let {PathName}=TheCurrentDirectory"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {PathName}=TheCurrentDirectory

@{fg highlight}Description...@{fg text}

  This returns the pathname of the deck's current directory.
  
  SEE ALSO: @{" SetCurrentDirectory " link "CanDo_SetCurrentDirectory"} and @{" TheOriginDirectory " link "CanDo_TheOriginDirectory"}.

@endnode

@node "CanDo_theorigindirectory" "Let {PathName}=TheOriginDirectory"
@toc "CanDo_DOS & File Control_Index"
@{fg highlight}Command...@{fg text}

  Let {PathName}=TheOriginDirectory

@{fg highlight}Description...@{fg text}

  This returns the pathname of the deck's original, startup directory.
See the manual for a full description of this system variable.
  
  SEE ALSO: @{" TheCurrentDirectory " link "CanDo_TheCurrentDirectory"}.

@endnode