Date: Tue, 25 Aug 1992 08:34:32 -0500 From: darnelll@sy2000.cet.fsu.edu Subject: Fetch Help 2.1b4 Text File The great communication program Fetch located in the archives at Sumex in the communication folder has interactive help. I, as well as some of my colleagues, prefer to read this offline in printed form. I copied this help using Resedit from the program itself and take no credit for it but wish to only distribute it so other users may benefit from this. Dartmouth and those that worked on this project deserve all the credit for this wonderful application. ********************************************************************** Larry Darnell (904) 644-4720 406 MCH, B-150 (904) 644-5803 Fax Florida State University Computer Support Specialist Tallahassee, FL 32306-4018 darnelll@sy2000.cet.fsu.edu FETCH HELP About Fetch... Fetch is a Macintosh program for transferring files. It uses the File Transfer Protocol (FTP) and therefore allows a networked Macintosh to transfer files with any connected machine that supports FTP. Fetch requires a Mac 512KE, System 4.1, and either KSP 1.03 or MacTCP. If you have questions or comments about Fetch please send them to Jim Matthews (or to Fetch@Dartmouth.edu). The current version of Fetch is 2.1b4. The information in this help file may not be accurate for other versions. Fetch is Copyright 1992, Trustees of Dartmouth College. Free non-commercial distribution of this software is permitted. Contact the Dartmouth College Grants and Contracts office (Hanover, NH 03755) for information on commercial distribution. Where to start If you are familiar with file transfer and FTP specifically you should start with the "Quick Guide to Fetch" topic. If you are new to file transfer and would like to learn in a step-by-step fashion you should try "A Fetch Tutorial." All of the Fetch commands and screen elements are explained under the "Reference" heading, and most computer terms used in the help screens are defined under "Glossary of Terms." Quick Guide to Fetch Connecting When you start Fetch or press the Open Connection... button you will be prompted with the connection dialog box. You must specifiy the name or IP number of the machine you wish to connect to, either by typing it in or by choosing an item from the Shortcuts pop-up menu. You may enter an user id and password. If you do not enter a user id Fetch will substitute the name "anonymous." If you do not enter a password your default password will be used (the default password is specified in Preferences). So in order to use "anonymous FTP" you only need to enter a machine name. Directories Fetch displays directories roughly the same way that the Macintosh system displays folders. Once you are connected the current directory is displayed as the title of a pop-up menu above the file list. You can change directory in several ways. Double-clicking the name of a directory in the file list (or selecting it and hitting enter) causes Fetch to enter that directory. The pop-up menu above the file lists lets you move to any ancestor of the current directory. Choosing the Change Directory... command from the Directories menu prompts you for a directory name and makes that the current directory. Finally, the bottom of the Directories menu includes every directory you have entered since opening the connection. You may re-enter any one by selecting it from the menu. Getting a File To get a file, double-click on its name or select it and click the Get File... button. If the Automatic radio button is chosen Fetch will try to figure out what kind of file it is from its name, and treat it as a text file if it can't make an educated guess (see Automatic/Text/Binary under Reference). If the Text button is selected the file will be treated as text, and you will have the option of converting any BinHex files embedded in the text file. If the Binary button is selected Fetch will check to see if the file is in MacBinary II, AppleSingle, MacBinary I or MacHost format, and otherwise save it without any formatting or conversion. If you know what kind of file you are getting you should select the appropriate button. Most of the time, however, the Automatic setting will do the right thing. Putting a File To Transfer a file from your Macintosh to another machine click on the Put File... button. You will be asked to pick a file and prompted for the name and format to give the file you are putting. You should choose MacBinary II format if you plan to simply store the file on the other machine, BinHex if you plan to mail it to someone, and either Text, Wrapped Text, or Raw Data if you plan to manipulate the file on the host computer. Text will simply create a text file using the rules of the other system, Wrapped Text will limit lines to a certain length, and Raw Data will not perform any conversions at all. Cancelling and Quitting You may cancel any on-going operation by pressing the Cancel button. Some host computers do not recognize the cancel command and will therefore continue the current operation until it is completed. In that case your only options are to close the connection (by pressing Close Connection) or quitting from Fetch by choosing the Quit command from the File menu. Why Tranfer Files? There are two reasons to transfer files between a Macintosh and another computer. One is to use the other computer as a holding place for Macintosh files. This sort of use can be termed "archiving." In this case it is not important for the file to be in a format understood by the other computers, since it will only be transferred back to a Macintosh. It is important to be able to retrieve the file exactly as it was saved. Fetch supports three file formats that are suitable for archiving Macintosh files: MacBinary II, AppleSingle and BinHex. A file stored in any of these formats can be reconstructed without any loss of information (for instance the file type, icon, and original name will be preserved). This sort of file transfer can be used to distribute software over a large area. There are several large archives of Macintosh programs on the Internet, most notably the Info-Mac archives on sumex-aim.stanford.edu. These archives allow anyone to retrieve files and typically store the files in MacBinary II or BinHex format. The other reason to transfer files between different computers is so that they can be used by programs on each machine. Due to the peculiarities of the Macintosh and its software there are few files that can be shared with other computers this way. The most common type is the text file (see the "Glossary" topic for a definition of text file). Most computers have programs that use text files and most Macintosh word processors allow you to save documents as text. Fetch allows you to move text files to and from other computers, and offers the option of word-wrapping (see "Wrapped Text" and "Filled Paragraphs" under "Reference"). There are a few kinds of non-text files that can be used on a Macintosh and other computers. Examples include compressed text files (created with the Unix compress program or MacCompress) and files created with tar or MacTar. These files can be transferred to a Macintosh with the Binary files option and transferred to other computers in the "Raw Data" format (see "Raw Data" under "Reference"). A Fetch Tutorial The following help items walk you through the process of connecting to a remote computer, navigating around its directories, and moving a file to and from your Macintosh. This tutorial assumes that you are familiar with the Macintosh. Some terms will be defined as we go along, others are defined under the "Glossary" help topic. Connecting and Signing on When you first open Fetch you are presented with the sign-on dialog box; at other times you can press the Open Connection... button in order to see that dialog. The sign-on dialog has fields for entering four pieces of information: the name of the machine you wish to transfer files with (or "host name") the name of your account on that machine (or "user id") the password for that account the name of the starting directory (optional) The sign-on dialog also contains a shortcut mechanism for filling in some or all of these fields. To the right of the word "Shortcuts" there is an icon representing a pop-up menu. Example: Press on the icon to use the menu and select the item titled "Dartvax." (Dartvax is a Unix computer in the Kiewit Computation Center at Dartmouth College). When you release the mouse the machine name, user id, and starting directory fields will be filled in. Note that the user id is "anonymous." Many machines, including Dartvax, allow any user to transfer files with it as a guest, without specifying a password. You may then click the OK button to initiate the connection. Finding Files and Directories Most computers divide their files among directories, which are equivalent to folders on the Macintosh. In order to get a file you should first go to the proper directory. Fetch displays the name of the current directory above the list on the left side of the window. The list contains the names of the files and sub-directories in the current directory. Example: If you have signed on to Dartvax your current directory should be "pub", and there should be some files and folders visible in the file list. However there are few interesting files in this directory, so you will have to change the current directory. You can change directory in several ways. The simplest is to double-click on the name of a sub-directory in the list. You can try this by double-clicking on the name "mac" in the current file list. The current directory will change to "mac" and the file list will show the names in that sub-directory. If you click on the name of the current directory you will see a pop-up menu showing the current directory and its ancestors, in this case "mac," "pub," and "/." Choosing one of these takes us back to that directory. Getting a File You should now be in the directory titled "mac" (its complete pathname is "/pub/mac"). This directory holds Macintosh-related files for downloading. One of the files should be a StuffIt! archive containing this version of Fetch, Fetch_2.1.sit.hqx. In order to move "Fetch_2.1.sit.hqx" from Dartvax to your Macintosh you should double-click its name. Alternatively you may select its name and press either Return, Enter, or the Get File... button. You will be prompted for a name to save these files under; if you click OK the files will quickly be saved on your disk. They will be complete with their own icons and ready to be used. Putting a File [Note: Users outside Dartmouth should not put files on Dartvax; please use a local system.] Dartvax has a special directory where users may drop off files for others to download; the full name of this directory is "/pub/dropoff." To get to this directory from /pub/mac you should choose "pub" from the pop-up menu above the file list. Then double-click on "dropoff" to enter that directory. To put a file onto Dartvax click on the Put File... button. You will be prompted to select the file you wish to send; since this is just a tutorial you can pick any file you wish, though you probably want to avoid very large files. You will then be asked to provide a name to give the file on Dartvax. This dialog box also gives you a chance to pick a file format >From a pop-up menu. Fetch will usually pick an appropriate name and format so you can simply press the OK button. The file will be transferred to Dartvax and you will be able to watch its progress in the status panel on the right side of the Fetch window. When the transfer is complete the name of the file you put will appear in the file name list. Since we do not want to clutter this directory you should select that name and choose Delete directory or file... from the Remote menu. Congratulations -- you have just transferred files to and from your Macintosh! You can learn more about Fetch by consulting the help topics under "Reference." Please send mail to Fetch@dartmouth.edu if you have any comments, questions, or criticisms. Reference The following topics offer more in-depth information about Fetch and its capabilities. There is roughly one topic for each button, menu item, and supported file format. If you can not find some topic here please send electronic mail to Fetch@dartmouth.edu. We appreciate your input. AppleSingle AppleSingle is Apple's official format for representing a Macintosh file on other types of machines. Macintosh files on A/UX (Apple's Unix) systems are usually stored in AppleSingle format. AppleSingle files have no distinguishing filename suffix, so it is usually necessary to select the Binary button in order to download AppleSingle files. Fetch and get and put files in AppleSingle format. Automatic conversion of AppleSingle files can be turned on and off in the Preferences dialog box. Automatic/Text/Binary FTP (the protocol which Fetch uses to transfer files) divides files into two categories: text files and binary (or image) files. Furthermore, the Macintosh uses complex files that can only be represented on other computers with special formats. In order for a file transfer to work these issues must be worked out. Fetch has three buttons that control the way a file is retrieved: they are titled Automatic, Text, and Binary. It would be convenient if Fetch could always tell what sort of file it was getting and treat it in the appropriate way; unfortunately Fetch is not that smart. So some of the time you will have to specify what sort of file you are getting. The three possible settings are explained below. Automatic Fetch starts out with the Automatic button selected, and this setting will be the right one most of the time. When this button is selected Fetch tries to interpret the name of the file you are getting. For instance, most BinHex files end in "hqx," and most GIF (Graphics Interchange Format) files end in "gif." When the Automatic button is selected these clues lead Fetch to download "hqx" files as text files (and ignore the non-BinHex part) and download "gif" files as binary files (with the right icon to be opened by a popular GIF viewing program). These clues are managed by the Suffix Mapping... menu command (see the "Suffix Mapping" help topic). Some file names will not offer any clues, and in that case Fetch will download the files as text files. When Fetch believes a file is in BinHex format it discards all non-BinHex data and only allows you to save the converted file. This is a problem if you want the other data or if the file is only part, and not the first part, of a complete BinHex file (see Multi-Part BinHex Files). When Fetch thinks a file is text it prompts you for a name to give it and allows you to have it converted to filled paragraphs (see the "Filled Paragraphs" topic). The file will be of type TEXT and its file icon can be set in the Preferences dialog box. Fetch will detect the beginning of a BinHex file inside a text file and offer to convert the BinHex information; you have the option of declining this conversion by pressing the Don't Convert button. When Fetch thinks a file is binary information it first checks to see if it is in MacBinary II, AppleSingle, MacBinary I or MacHost format. If it is, it will be saved in its original state; otherwise you will be prompted to supply the type and creator of the file. A pop-up menu with a few popular types is available. The Automatic setting will do the wrong thing if you have a binary file with a name that does not use a standard ending (e.g. "bin", "Z", "sit", "gif", "tar"), a text file with an ending usually used for binary files, or a non-BinHex file with a "hqx" ending to its name. For these situations you must use one of the other two settings. Note: There is one notable exception to these rules for Automatic mode. If Fetch determines that the server machine is a Macintosh running the Macintosh Operating System (i.e. not A/UX or some other Unix) it will try to transfer all files in MacBinary mode. This way all files will appear exactly as they do on the server machine, except that StuffIt! archives may be expanded. Text This setting tells Fetch that the file in question is a text file (or a BinHex file, which is one kind of text file). Since the Automatic setting treats mysterious files as text files this setting is rarely necessary. If, however, a text file has the sort of name usually associated with binary files (i.e. ending in "bin", "Z", "sit", "gif", or "tar") you should choose this setting to override the automatic behavior. Likewise if a filename ends in "hqx" but does not refer to a complete BinHex file or the first part of a complete BinHex file you should choose this setting. Binary This setting is for getting binary (i.e. non-text) files, specifically those files whose names do not identify them as being binary files. If you know that a file is not a text file (e.g. it is in MacBinary or AppleSingle format) choosing this setting will help ensure the proper treatment. When this button is set the file will be checked to see if it is in MacBinary, AppleSingle or MacHost format. If it is then it will be saved just in its original state; otherwise you will be prompted for the type and creator of the file. A pop-up menu with a few popular types is available; more can be added in the "Suffix Mapping" dialog. BinHex BinHex (sometimes called BinHex4) is a format for representing a Macintosh file in text form. The Macintosh file is converted to a series of lines, each made up of letters, numbers, and punctuation. Because BinHex files are simply text they can be sent through most electronic mail systems and stored on most computers. However the conversion to text makes the file larger, so it takes longer to transmit a file in BinHex format than if the file was represented some other way. The suffix ".hqx" usually indicates a BinHex format file. Fetch can get and put files in BinHex format. Conversion of BinHex format files can be turned on and off in the Preferences dialog box. For information on BinHex files in multiple parts, see the Multi-Part BinHex Files entry. Cancel If a time-consuming operation is in progress the Cancel button will appear at the bottom of the status pane, on the right side of the window. You can cancel the current operation by pressing this button or typing Cmd-. Once you have done so the button will go away and the Status line will read "Cancelling ." Most computers support the cancel command and with these machines it will only take a few seconds. But some machines ignore the command and insist on completing the current operation. In these cases the status line will read "Cancelling " for quite a while. The only ways to quickly exit from this situation are to close the connection or quit from Fetch. Change Directory The Change Directory command is found in the Directories menu. It allows you to specify the current directory by typing its name rather than by moving to it one step at a time. This is useful if you know the full name of the directory you wish to see and it is several steps away from the current one. Close Connection The Close Connection button is available whenever you are connected to another computer or in the process of connecting. You may press this button even while file tranfers or other operations are taking place, so it is an escape hatch if things do not seem to be working. When this button is pressed Fetch severs its connection to the other computer and allows you to open a new connection. Create host directory This menu command creates a new directory on the remote computer. You will be prompted for a name to give the directory; unless you specify otherwise the directory will be a sub-directory of the current one. You should only use this command if you have the appropriate privileges and the remote computer supports directories. If either of these conditions are not met you will see an error message. Delete directory or file This menu command allows you to delete files and directories on the host computer. If you select a name from the file list and choose this command you will be asked for confirmation before the file is deleted. If you have selected more than one file and give confirmation, all the files will be deleted. If you have not selected a file you will be asked for the name of the file to delete and then it will be deleted. Note that you must have the necessary privileges to delete the file or files in question. Otherwise you will see an error message and the file or files will remain unchanged. If you select a directory and choose this command Fetch will delete the directory's contents before deleting the directory itself. Directory Menu There are two menus to make moving between directories more convenient: There is a pop-up menu above the file list on the left side of the Fetch window. The title of this menu is the name of the current directory, or "" if Fetch was unable to determine the name of the current directory. This menu includes the current directory and all its ancestors, i.e. the directories that the current directory is in. Choosing one of these directory names makes it the current directory and changes the file list. If you choose the current directory Fetch will refresh the file list. The Directories menu in the menu bar includes the names of every directory on the remote computer that Fetch has visited since opening the connection. Choosing one of these directory names makes it the current directory and changes the file list. Note for experienced users: Fetch remembers the file list from the directories it visits for a period of time (you can adjust that period in the Preferences dialog box). This makes returning to visited directories a quicker operation. If you would like to have the file list reloaded from the remote computer instead of from Fetch's memory you can hold down the option key when you choose a directory name from the pop-up menu. Edit Shortcuts The shortcut pop-up menu in the sign-on dialog box is a convenient way to specify frequently used host machines. The menu comes pre-configured with a few common destinations, but you can customize it to include others and/or to include your own name and password. The Edit Shortcuts command in the Fetch menu brings up a list of the current shortcuts with buttons for creating new shortcuts, changing existing ones, and removing ones that are no longer wanted. The changes you make will be saved to the Fetch Preferences file, and so will be available whenever you run Fetch from that machine. The shortcut marked with a checkmark is special -- it is the "default" shortcut and will be chosen automatically the first time you open a connection. To change the default shortcut, select another shortcut and press the Make Default button. NOTE: If you save a password as part of a shortcut that password will be no more secure than the disk it is saved on. Be certain that others do not have access to your system disk before saving a shortcut that includes a password. File List The file list is the list of file and directory names on the left side of the Fetch window. It works much like the file list in the standard Macintosh "Open" dialog box. Clicking on a name selects it, and many operations (Get file, Delete file or directory, Rename host file, etc.) operate on the selected name. Holding down the Command key allows you to select multiple individual filenames, and holding down the Shift key while clicking selects a range of filenames. You can also select a filename by typing the first few letters of its name or using the up and down arrow keys to step through the list. Double clicking on a name prompts Fetch to change directory to the selected name. If the name refers to a file the change directory command should fail, and Fetch will then download the file. Typing Return or Enter is equivalent to double-clicking. Fetch displays a small icon next to each name. Files and directories are designated with the standard file and folder icons. If Fetch can not determine whether the name refers to a file or folder an icon showing both is displayed. If the name refers to a Unix symbolic link (an alias for a file or directory in a different place) it is displayed in italics (just as the Finder displays the names of System 7.0 aliases on the Macintosh). You may choose to have Fetch display the size and date-modified for each file. This has the side effect of displaying names in a smaller font (to make room for the additional information). If a file name can not be displayed in full selecting it will display as much of the name as possible (rather than displaying the size and date). Note for experienced users: Pressing down arrow while holding down the Command key makes the selected directory name the current directory; pressing Cmd-up arrow moves to the parent directory. Users with Apple Extended Keyboards can use the home, end, page up, and page down keys to scroll the file list. Filled Paragraphs When Fetch prompts you for a name to give a retrieved text file it also displays a check box titled Convert to Filled Paragraphs. If this box is checked many of the line-endings of the file will be removed. This will have the effect of converting many short lines into a few long ones, namely one line per paragraph. This is the format preferred by Macintosh word processors, since it allows them to set the line-endings according to the current margin or window size. This option is only appropriate if the text in question is made up of paragraphs. Tables, computer programs, and other more exotic text files may be garbled by this conversion. Therefore it is usually best not to set this option. Find Fetch can search for information in any of its windows with the Find command. When the Fetch window is frontmost Find searches through the displayed file names for the desired text. When a text window (including the Fetch Transcript window) is in front Find searches the displayed text. When the Fetch Help window is frontmost Find searches through all the help topics. FTP FTP stands for File Transfer Protocol, and is a set of ground rules (a "protocol") that allows two computers to exchange files over a network. FTP was developed in the 1970s by users of the Advanced Research Projects Agency network, or Arpanet. FTP is the official file transfer mechanism of the Internet (Arpanet's larger successor) and therefore is supported by hundreds of thousands of machines. Fetch implements one part of FTP, the "client" side. Therefore it can communicate with any connected machine that has a "server" program. Some of Fetch's features will not be available on certain servers -- this is because the other machine does not support the feature (e.g. not all machines have sub-directories) or because the server program does not implement the complete FTP specification. Get Directories and Files The Get Directories and Files command is used to download multiple files and/or directories with one command. You can select the files or directories you wish to download in the file list; if none are selected you will prompted for a file or directory name. Then you will be prompted for the folder in which to save the files and directories on your Macintosh disk. The names of the downloaded files will be set automatically, based on the names that the files have on the remote computer. All format conversions will also be performed automatically, according to the settings in the Preferences dialog. The progress of the file transfer, including the name of the file being transferred, is shown in the Status panel. You can cancel the transfer by pressing the Cancel button. Help The Fetch Help menu command opens the Fetch Help window (this window) and brings it to the front. You can choose help topics by clicking on the them and scroll through the help information with the scroll bar on the right. You can copy information from this window and print the current topic. Help is only available when the Fetch Help file can be found (it should be placed in the same folder as Fetch or in the System Folder). Balloon help is also available for most of the menus and buttons in Fetch if you are running System 7.0. The Help window can be closed by clicking on its close box or typing Cmd-W. MacBinary II MacBinary II (sometimes simply called MacBinary) is a format for representing all the information in a Macintosh file in one binary file. It is useful for storing a Macintosh file on a non-Macintosh system for later retrieval. Unlike BinHex, MacBinary II is a compact format but can not be passed through most electronic mail systems. MacBinary II files typically have names ending in ".bin". Fetch can get and put files in MacBinary II format. Fetch can also get files in MacBinary I format (and earlier version of the MacBinary standard). Automatic conversion of MacBinary I and MacBinary II files can be turned on and off in the Preferences dialog box. Some FTP servers (notably NCSA Telnet, InterCon System Corp's TCP/Connect II, and Peter Lewis's FTPd) recognize MacBinary format. If Fetch determines that it is connected to one of these servers it will try to use MacBinary II for all transfers. MacHost MacHost (also known as Dtmft) is a format used by DarTerminal for representing Macintosh files on non-Macintosh systems. It is similar to MacBinary II but only used at Dartmouth. Fetch can get files in MacHost format and recognizes them automatically if the Binary option is selected. Automatic conversion of MacHost format files can be turned off in the Preferences dialog box. MacTCP MacTCP is a product from Apple Computer, Inc. that allows Macintosh software use the TCP/IP protocols. Fetch will use MacTCP if it is installed; otherwise it will use Dartmouth's own KSP protocol and a special network gateway. A message in the About Fetch... dialog box indicates whether MacTCP or KSP is currently being used. If you have configured MacTCP incorrectly Fetch will not be able to connect or transfer files. You should either fix the configuration problem or remove MacTCP and reboot; then Fetch will use KSP (assuming you are at Dartmouth). MacTCP is available from the Apple Programmer's and Developer's Association. The current version is 1.1, and a number of problems have been observed with earlier versions so it is important to get the latest version. Multi-Part BinHex Files Some archives (notably the Info-Mac archives at sumex-aim) break large BinHex files into several pieces, with names such as file-name-part1.hqx, file-name-part2.hqx, etc. As long as all the parts are in alphabetical order, Fetch will treat a request to get the first part as a request to get the entire file. Fetch will continue to download host files until the local file is complete. If the parts are not in alphabetical order you will want to turn off BinHex conversion in the Preferences dialog box. Then you can download each part separately, and piece them back together using a text editor or a special utility. Open Connection The Open Connection button and menu command bring up the sign-on dialog. There you should enter the name or IP number of the machine you would like to connect to, the name of your account (i.e. the user id), that account's password, and (optionally) the directory you would like to start with. If the account name is omitted the name "anonymous" will be assumed. If the password is omitted the default password set in Preferences will be used. You can fill in some or all of these fields by choosing an item from the Shortcut pop-up menu. Click on the icon at the bottom of the sign-on dialog and the menu will pop-up. It includes the names of several Internet archives. Open Shortcut The Open Shortcut menu lists available shortcuts and allows you to connect to one of the listed machines with one command. Fetch only supports one connection at a time, so if you are currently connected you will be asked if you want to close the current connection. You can add, remove, and change shortcuts with the Edit Shortcuts command. Post-Processing Fetch can automatically "pass-off" downloaded files to other applications; this feature is called post-processing, and is configured in the Post-Processing dialog. [Note: Post-processing requires System 7.0]. In that dialog you can create a list of post-processing actions. An action consists of two pieces of information: the kind of file that the action applies to, and the application that this kind of file should be opened with. The kind of file is specified by type/creator codes, and the application by its signature code. For instance, one action could specify files with the type code of "TEXT" and the creator code of "ttxt", and the application signature of "MSWD." This would mean that TeachText files (which have type "TEXT" and creator "ttxt") should be automatically opened with MicroSoft Word (which has the signature "MSWD"). Alternatively, an action could specify a type of "TEXT" and a creator of "****"; the special code "****" matches anything, so this action would apply to all files of type "TEXT" (i.e. all text files). Finally, the application signature can be left blank. In this case the file will be opened by the application that typically opens it, just as if you double-clicked on the file in the Finder. The codes that Fetch uses to identify files and applications are rather cryptic, so Fetch provides an alternative means for entering them. The "Choose Example..." and "Choose Application..." buttons allow you to select the kind of file or application you are interested in, leaving Fetch to extract the necessary codes. Post-processing actions can be enabled and disabled. This allows you to define actions and turn them off temporarily, without having to re-enter them later. Fetch comes with several post-processing actions defined but disabled; they give some examples of how this feature can be used. Preferences The Preferences menu item brings up a dialog that allows you to configure the way Fetch operates. The settings made in this dialog are saved in a file called "Fetch Preferences" in the current system folder. The following can be adjusted in the Preferences dialog: General Preferences: Default password -- The text entered here will be used as your password whenever you connect as "anonymous." It is customary to supply your e-mail address in this case, so we recommend that you enter your e-mail address here. Display server messages -- Some FTP servers display special information in the client-server dialog, such as hours of operation, use restrictions, and information about the files on the server. If this box is checked Fetch will display these messages in a separate window; otherwise they can be viewed by examining the Fetch Transcript window. Keep connection active -- If this box is checked Fetch will regularly send commands to the remote computer. Some computers terminate connections after a certain period of idleness (usually five to fifteen minutes), and having Fetch send commands regularly evades this policy. Note that it is very impolite to keep a connection open to a public-access FTP server for a long period; many computers limit the total number of connections and your connection may prevent others from using the service. Show file sizes and dates -- If this box is checked Fetch will attempt to display file sizes and dates-last-modified in the file list. This is usually only possible if the remote host is a Unix machine or a Macintosh running Peter Lewis's FTPd server. The file names, sizes, and dates will all be displayed in Geneva 9, in order to fit longer names in the given space. If a name is truncated to make room for the size and date you can select it to show only the name. Downloading Preferences: Download folder -- If this box is checked you will be prompted to choose a folder for saving downloaded files. From that point on Fetch will save downloaded files in the download folder without any further prompting. To disable this feature uncheck the download folder checkbox. Edit text files with -- This pop-up menu allows you to choose which editor's icon will be put on text files retrieved by Fetch. Thus you can have your favorite editor start up when you double-click on the icon of the retrieved file. If your favorite editor is not found in the menu please send an electronic note to Fetch@dartmouth.edu (or edit Fetch's TXTs resource with ResEdit). Default binary type/creator -- The type/creator codes entered here will be used for raw binary files that do not have a type/creator assigned in the Suffix Mapping dialog. This can be useful if you are downloading many binary files that do not have a common suffix. Uploading Preferences: Add file format suffixes -- If this box is checked Fetch will add suffixes to the suggested names of files put on the remote computer. So if the file is being sent in Text format Fetch will suggest a suffix of ".txt"; if it is in BinHex format Fetch will suggest ".hqx"; and if it is MacBinary II format Fetch will append ".bin" to the suggested name. These suffixes are useful when Fetch tries to determine the type of a file when it comes time to retrieve it, and so this box it checked by default. You may want to uncheck it if the system you are connected to requires very short file names. Word wrap margin -- This value will be used as the word-wrapping margin if you put a file in the "Wrapped Text" format. Lines longer than this value will be broken at word boundaries into shorter lines. Format Preferences: Recognize and Interpret -- These checkboxes determine whether Fetch will automatically recognize and convert downloaded files in the given formats (StuffIt!, BinHex4, MacHost, MacBinary I & II, and AppleSingle). If you have trouble downloading a file in one of these formats you may want to turn off the conversion and convert the file with another tool. Miscellaneous Preferences: Refresh file lists older than n minutes -- Fetch remembers file lists from directories you have visited. This value controls how long such a list will be remembered. If you would like to have quicker performance you can increase the value; if you want to make sure that the displayed file list is up to date you can choose a smaller value. Use "TYPE I" to retrieve binary files -- Check this box if you want Fetch to use the "TYPE I" format for binary transfers; this is necessary for proper operation with some IBM mainframe servers, but can cause problems with machines that do not use 8-bit bytes (such as TOPS-20 systems). Omit file names beginning with a period -- Check this box if you do not want Fetch to display names that begin with a period in its file list. This can reduce the clutter when connecting to Unix accounts. Translate ISO characters -- Check this box if you would like Fetch to translate 8-bit ISO characters in text files and file listings to the Mac equivalents, using the 'taBL' resources in Fetch. Put File The Put File button is used to transfer a file from your Macintosh to the host computer. When you press the button you will be prompted for the file you wish to send. Then you will see a dialog box that lets you set the name the file will be given on the other computer and the format it will be stored in. Be sure to pick a name that will be acceptable to the other machine (most systems require file names that are shorter than Macintosh file names and forbid the use of certain characters). Note that if a file of the name you specify already exists on the other computer it will be overwritten without warning. The formats you can use when putting a file are Text, Wrapped Text, MacBinary II, Raw Data, BinHex, and AppleSingle. The first two are only available when putting a text file, but the other four are always available. Fetch assumes that you will usually want to save text files as Text, and other files in MacBinary II format. See the help topics for each format for more information. The progress of the file transfer is shown in the Status panel. You can cancel the transfer by pressing the Cancel button. You can upload multiple files and/or folders by pressing the Put File button with the Option key down. For information see the "Put Folders and Files" help topic. Put Folders and Files The Put Folders and Files command is used to upload multiple files and/or folders with one command. You will be prompted for the files and folders you wish to send. Then you will see a dialog box that lets you choose the formats to be used: one format for all the text files being uploaded, and one format for all other files. The names of the uploaded files will be set automatically, based on the names that the files have on your Macintosh. If you choose to upload a folder Fetch will create a directory on the remote computer and put the contents of the Macintosh folder in that directory. If the folder includes other folders, they too will be created. If the remote computer already has directories with the names of the Macintosh folders those directories will be used. Uploading of folders will not work with remote computers that do not support sub-directories (e.g. CMS). The progress of the file transfer, including the name of the file being transferred, is shown in the Status panel. You can cancel the transfer by pressing the Cancel button. Quit The Quit menu command closes the current connection and quits the program. Any on-going file transfer or other operation will be cancelled. Raw Data Raw Data is one of the formats available for putting files on another computer. If this format is chosen the data part of the Macintosh file will be sent without any interpretation or conversion. Some Macintosh programs create files with all their information in the data part (e.g. Stuffit!, MicroSoft Excel, MicroSoft Word). In these cases using the Raw Data format is a simple way to transfer files. However, if the file includes a resource part that part will be lost. In any case the file type and icon will not be preserved. So the Raw Data format should only be used if the file is strictly a data file that can be used by some other computer (e.g. an IBM PC running the PC version of Excel). If the file will be retrieved by a Macintosh either MacBinary II or BinHex format should be chosen. Rename File This menu item allows you to change the name of a file on the remote computer. If a file is currently selected you will be prompted for the new name; otherwise you will be prompted for the current name and a new name. Try to choose a name that will be acceptable to the other computer: most systems have file name length limits and do not allow certain characters. If you specify an improper name you will get an error message. Send FTP Command... Most file transfer tasks can be handled with Fetch's regular buttons and menu items. But some file transfer servers implement non-standard commands, or require use of standard commands in non-standard situations. If these cases you can send an arbitrary FTP command with the Send FTP Command menu item. It prompts you for a command and passes it along to the other computer without interpretation. The other computer's response to the command will be presented in a dialog box. If you enter a complex command (such as one that starts a file-transfer) it will almost certainly not work and you may have to close the connection. After the command is sent Fetch will refresh the file list, since your command may have changed the current directory. Status Panel The area on the right side of the Fetch window is the Status panel. It contains information about what Fetch is doing at any given time. If a file transfer is in progress it displays the name, format, and approximate size of the file being transferred, the amount of data that has been transferred so far, and the average speed of the transfer so far. If any of these fields are missing it is because the information is unavailable. At the bottom of the status panel there is the Cancel button (if an operation is in progress) and Fetch's version number. StuffIt! StuffIt! is a popular shareware archiving program that allows users to combine multiple files and folders into one compressed file. The StuffIt! format has become a common way to keep Macintosh files on FTP servers, since the compressed files take less room. Fetch can automatically recognize StuffIt! archives and uncompress them as they are downloaded. Fetch can not uncompress encrypted archives, or archives created by StuffIt!'s commercial successor, StuffIt! Deluxe. "Un-stuffing" can be turned on and off in the Preferences dialog box. Suffix Mapping When the Automatic button is selected, Fetch looks for standard filename suffixes in order to decide whether a file is a text file or a binary file. You can modify the list of recognized suffixes with the Suffix Mapping command. When the command is given a dialog box is displayed, showing all the current suffix mappings. A suffix mapping associates a suffix (such as ".hqx") with a file type (either Text, Binary, or BinHex) and optionally with type/creator codes. The "Text" type means that files with the associated suffix should be downloaded as text files; similarly, the "Binary" type means that the files should be downloaded as binary files. The BinHex type means that the file should be downloaded as text (since BinHex files are a kind of text file) but that non-BinHex material should be ignored. If a type/creator pair has been specified text or raw binary files will be given that type and creator. For instance, a file with the ".Z" suffix is usually given the type/creator pair of LZIV/ZIVM (the codes used by MacCompress), since ".Z" is the standard ending for compressed files and MacCompress is a program for reading such files. Suffix mappings are only in force when the Automatic button is selected. And information in the file overrides the application specified in the suffix mapping: if a file is in BinHex, MacBinary, MacHost or AppleSingle format, it will include information about the application it belongs to. View File Use this command to view text files (such as "README" files) without leaving Fetch. Fetch will download the selected text file and display it in a separate window. These text windows support tabs and large files (up to the limit of available memory). You can search for information in text windows with the Find command, print them, and save them as text files. The font and tab width can be changed with the Set Font and Size command. View File List Use this command to view the file list for the current directory in a separate text window. This listing will often include information (such as file permissions) that Fetch can not display in its own file list. You can search for information in text windows with the Find command, print them, and save them as text files. The font and tab width can be changed with the Set Font and Size command. Wrapped Text Wrapped Text is a format that can be chosen when putting text files on another computer. Most Macintosh editors store text files with line-ending characters only at the end of each paragraph. That way line-endings can be recalculated whenever the user changes the margins or resizes the window. However this yields files with what appear to be very long lines, too long for many other computers. In order to make these files usable on the other system Fetch offers the option of word-wrapping text files as they are sent. If this format is chosen no line will be allowed to exceed a certain margin (set in the Preferences dialog). If a line is initially longer than this limit it will be broken on a word boundary so that individual words are kept intact. Troubleshooting The file list includes other information besides the file name, and the Get File button doesn't work. Try refreshing the file list by choosing the current directory from the directory pop-up menu; that will usually fix this problem. Otherwise you can hold down the option key when you press the Get File button and type in the file's name by hand. I can't connect to ftp.apple.com with Fetch but I have no problem connecting from a Unix machine. The server at ftp.apple.com requires that its clients be assigned an official domain name. Your network administrator may not have assigned names to the addresses used by Macintoshes running MacTCP; that would cause connection attempts from your Mac to fail while a Unix machine succeeds. Your network administrator can resolve this problem by assigning names to those addresses. The files I get don't have the right icon. This problem can be caused by a number of factors. First be sure that you are using the right settings -- if you've tried the Automatic setting try Binary. It may also be helpful to read the "Automatic/Text/Binary" help topic under "Reference." If you are using System 4.2 and Finder 6.0 you should upgrade since that system version has a bug that causes files to lose their icons. If you use MultiFinder you should try saving the file to a folder that is not currently open in the Finder. The Finder's Get Info... command sometimes fixes incorrect icons under MultiFinder. If all else fails send mail to Fetch@dartmouth. I get the message "This is not a proper BinHex format file." This means that Fetch could not successfully de-binhex the file. You should try unchecking the BinHex4 Format button in Preferences and downloading again (see the "Preferences" help topic under "Reference"). Then try to de-binhex the file with either BinHex4 or Stuffit!, two Macintosh utilities. If they succeed please send a note to Fetch@dartmouth, since this indicates that Fetch has a bug. Otherwise the problem may be that the BinHex file is incomplete. If it has other pieces you will have to get them the same way and assemble them on your Macintosh before running BinHex4 or Stuffit!. Finally, the file may just be corrupted. In that case contact the source and ask for a new copy. I get the message "This is not a proper MacBinary II file." This message, and other ones about MacBinary I, AppleSingle, StuffIt! and MacHost format files, mean that the file has been corrupted in some way. Contact the source of the file to get a new copy. If the file was created by Fetch send a report to Fetch@dartmouth.edu so we can try to find the bug. The Cancel button doesn't work when I'm connected to a VMS Vax. We have observed problems with Cancel on VMS and CMS systems. We're working on these problems and in the meantime you can cancel a transfer by closing the connection altogether. Fetch can't seem to connect to hosts while NCSA Telnet is running. Some MacTCP versions of NCSA Telnet monopolizes the name-lookup service, so while it is running other programs that use MacTCP (such as Fetch) can't connect to other machines by name. You can work around the problem by quitting from NCSA Telnet or entering the host's IP address in the Open Connection... dialog box. Newer versions of NCSA Telnet may not have this problem. Glossary of Terms anonymous FTP -- the process of connecting to a remote computer that does not require any identification or password. In this case the user name used is either blank or "anonymous" and the password is optional. Several archives of Macintosh software are available to all by anonymous FTP. binary file -- a file that may contain any characters in any format; not a text file. Files in MacBinary II format or MacHost format are binary files. directory -- a collection of files and sub-directories, equivalent to Macintosh folders. Sub-directories are directories within some other directory; the enclosing directory is known as the parent directory. Most systems have a notion of the current directory, the directory whose files your are viewing at that time. Not all systems have directories, and some systems do not permit sub-directories. download -- the operation of moving a file from some other computer to your own. host -- the remote computer you are connected to. This computer runs a program that accepts your connections, and therefore can be seen as your host. Most host computers are minicomputers and mainframes, but a microcomputer can also act as a host. Internet -- a collection of networks (including NSFnet, Milnet, and others) linking universities, commercial sites, and military bases around the world. All Internet machines are required to support FTP for file transfer, and are therefore accessible to Fetch. Dartmouth is connected to the Internet via NEARnet. IP number -- a type of computer address of the form number.number.number.number (e.g. 128.170.48.4). Usually you will refer to machines by their names (e.g. "Dartvax") but Fetch can also connect to machines with just their numeric address. text file -- a file containing lines of letters, numbers, and punctuation. Most word processors can create text files and some editors (such as TeachText and BBEdit) only create text files. A non-text file is a binary file. TCP/IP -- a protocol suite developed for the Department of Defense, and used by many types of computers (particularly machines running the Unix operating system). FTP, the protocol used by Fetch, is part of the TCP/IP family of protocols. Fetch uses TCP/IP services in one of two ways: with the KSP protocol and a translating gateway (such as Dartmouth's AppleTalk-IP gateway), or with Apple's MacTCP product. upload -- the operation of moving a file from your computer to some other one. If you would like to see other terms defined send a note to Fetch@dartmouth.edu. Release Notes This help file should be used with version 2.1 of Fetch. This version has the following new features and bug fixes: Since 2.0.6: There are new commands to view files and file lists in text windows. Fetch can optionally display size and date-last-modified information for files on most Unix servers. Fetch windows can be resized, and Fetch remembers their position between sessions. Fetch Help can be copied and printed. Fetch can be configured to automatically open certain kinds of files, for instance compressed archives, with the appropriate applications. Fetch can optionally save downloaded files to a special folder, without prompting you each time. Fetch now supports Balloon Help and the required Apple Events. The directory pop-up menu is now more Mac-like, showing just the ancestors of the current directory. The Delete command now works with directories that have files or sub-directories in them. Fetch will optionally display informational messages from the host. The network transcript can be conveniently viewed in a separate window. Fetch will now optionally translate between ISO and Mac character sets. Many minor features were added and many bugs were fixed. Since 2.0.5: Changed About box to permit free distribution, updated help. Since 2.0.4: Fixed a bug with certain Unix servers that caused dates to show up in the file list. Always shows icons (if only the file-or-directory icon). Use condensed type to fit more of long file names in the file list. Since 2.0.3: Fixed a bug that caused certain commands to fail if Fetch was run on a system besides System 7.0. Since 2.0.2: Fixed a problem with the FTP server on Northstar IBM RTs. Added an icon for names that might be files or directories. Started displaying the names of Unix links in italics. Fixed a bug that prevented use of the empty password. Changed the Get File button to only download files (and not try to change directory first). Return, Enter, and double-clicking still try to change directory before downloading. Since 2.0.1: Put in explicit support for the NCSA Telnet and TCP/Connect FTP servers. Fixed a problem with the mac.archive.umich.edu FTP server. Fixed a rare bug in BinHex decoding and another in StuffIt! expansion. Fixed a bug with putting a System 7.0 alias to MacTCP in the Control Panels folder. Since 2.0: Fixed a bug that required MacTCP to be installed in both the System Folder and the Control Panels folder under 7.0b4. Fixed a bug that caused problems with spaces in Unix filenames. Improved the algorithm for detecting BinHex lines. Since 1.1.1: Multiple files and folder hierarchies can be uploaded and downloaded. StuffIt! archives can be automatically uncompressed. The file list identifies files and directories with the familiar Macintosh icons for Unix, VMS, and CMS FTP servers. Fetch can be customized to recognize certain file name suffixes and download matching files in the proper mode. Support for uploading and downloading files in AppleSingle format was added. Support for downloading files in MacBinary I format was added. Interpretation of various file formats can be disabled in the Preferences dialog box. Fetch can be told to keep connections alive (by regularly sending "do-nothing" commands to the server). Users can send arbitrary FTP commands to the FTP server (such as the command specifying mini-disk passwords on CMS systems). Performance has been improved. Credits Fetch was written by Jim Matthews. Thanks to: Phil Koch for the idea of an FTP DA and for writing the gateway that made it feasible. Rich Brown and Paul Merchant for the KSP driver. David Gelhar for an FTP server I don't have to kludge around. Carl Pedersen for the idea of an "Automatic" button. Richard Nelson, for the new icon and "running-dog" animation. Andre Pirard and Alain Fontaine, for help making Fetch a better international citizen. All the Dartmouth testers, especially Rick Damon, Espen Koht and Andy Williams, who found such interesting files for Fetch to choke on. All the Internet testers, who found even more bugs and suggested great features. And to Daniel, for being Daniel.