

        REQUESTFILE (3.x only) (Location in C:)

   NAME
            Requestfile - To allow the use of the standard ASL 
        file requestor in an AmigaDos or AREXX script. The ASL 
        requestor is the interactive window that displays a list 
        of filenames and directories and lets the user chose one.

   SYNOPSIS
        REQUESTFILE [DRAWER DIR] [FILE filename] [PATTERN pat]
                    [TITLE titletext] [POSITIVE postext]
                    [NEGATIVE negtext] [ACCEPTPATTERN pat]
                    [REJECTPATTERN pat] [SAVEMODE] [DRAWERSONLY]
                    [MULTISELECT] [NOICONS] [PUBSCREEN screenname]


   DESCRIPTION
            After the user selects the file, the name of the file 
        chosen is returned, surrounded by double quotes.  If 
        multiple files are selected, each file is printed to the 
        console seperated by spaces and exits the file requestor 
        with a return code of zero. If 'CANCEL' or the close 
        gadget is chosen, the program ends with a return code of 
        5. The return code 5 can be detected if the "IF WARN" 
        statement is used. 

   KEYWORDS
            Even though there seems to be many of these, all of 
        them are optional. If you issue the REQUESTFILE command 
        without any keywords, a standard ASL requestor will open 
        up that any user can figure out.

     DRAWER dir
            The first directory listing will be the specified 
        'dir', and this path will appear in the drawer gadget of 
        the file requestor.

     FILE filename
            The 'filename' will be the selected default file. If 
        this file is not in the root directory, you must use the 
        DRAWER keyword to specify its directory.

     PATTERN pat
            This keyword causes only the files which match that 
        pattern you specify to show up. The user can, however, 
        enter any file he desires by simply entering the filename 
        or by changing the pattern. If you wish the user to not 
        be allowed to change the file pattern then use the 
        ACCEPTPATTERN keyword instead.

     TITLE titletext
            This allows you to enter the text string that will 
        appear in the title bar of the window. This should be 
        limited to 30 characters because anything text over 30 
        letters will be cut off by the edge of the requestor. It 
        is also a good idea for this text to hint the user on 
        what file he should select.

     POSITIVE postext
            This lets you change the button text on the leftmost 
        button. The function of that button always allows the 
        user to select that file. The default is labeled 'OK'. 
        For instance, let's say you wanted to load that file, you 
        could name that button 'Load'. Or, if you wanted to 
        delete that file you could name that button 'Delete'.

     NEGATIVE negtext
            This lets you change the text of the rightmost 
        button, which is defaultly named 'CANCEL'. You could 
        change the name to something more meaningful, such as 
        'Skip' or 'Abort'.

     ACCEPTPATTERN pat
            Allows you to limit the file display to those 
        filenames which match the pattern you specify. This 
        keyword does not give the user a chance to change the 
        pattern. If you want to leave the user that flexibility, 
        you should use the PATTERN keyword instead. For instance, 
        if you specify 'pat' as "#?.info", the user will only be 
        allowed to enter or select icons and only icons will be
        displayed.

     REJECTPATTERN pat
            This lets you exluce from the display all the files 
        that match the pattern you specify. This is the opposite 
        of ACCEPTPATTERN. Like ACCEPTPATTERN, there is no way for 
        the user to change the pattern.  For instance, if 'pat' 
        is "#?.info" then there is absolutly no chance for the 
        user to select an icon or for one to be displayed.

     SAVEMODE
            This is where the user is presented with a display 
        window that is black with grey letters instead of the 
        gray and black letters, and the multiselect option is 
        disabled.

     DRAWERSONLY
            Will not show any filenames, only the directory 
        names.

     MULTISELECT
            Lets the user select multiple files by holding down 
        the shift key and clicking on as many files as they want. 
        These files will be outputed to the console device, 
        seperated by spaces, when the 'OK' button is selected.

     NOICONS
            This will keep the icon files from showing up in the 
        file reqestor. This can also be accomplished by using the 
        "REJECTPATTERN #?.info" keyword statement.

     PUBSCREEN screenname
            This is where you can chose which screen you want the 
        requestor to show up on. 



     EXAMPLES:

            1. To have the user select a directory within a 
        script, and to store that directory in the local 
        environment variable dirname:


      UNSET dirname
      SET dirname 'REQUESTFILE DRAWERSONLY'
      IF "$dirname" EQ "*$dirname"
      ECHO "You didn't choose a directory name"
      ELSE
      ECHO "The directory you chose was $dirname"
      ENDIF
      UNSET dirname

            The Cancel button is tested for by checking for the 
        "$dirname" (which is replaced by the contents of the 
        environment variable) is equal to the literal string 
        "$dirname". The asterisk means that the IF command will 
        interpret the dollar sign as a dollar sign, not as the 
        contents of an environment variable. You could not use 
        the IF WARN test because you only get the return code 
        from the SET command, not the REQUESTFILE command this it 
        contains.



