6. File Transfer ________________________________________________________________ dataComet documentation. (Rev. 2/20/2010) Copyright 1997, 2010 databeast, Inc. All Rights Reserved. This document has information on (select and use "Find..." to go to the section): File transfer overview File transfer menu options AutoLaunch and Internet Config "File Mappings" File transfer with IBM hosts using IND$FILE Using the "IND$FILE..." command dialog The "IND$FILE" Preferences panel File transfer with SSH hosts using SCP Using the "SCP..." command dialog The "SCP" Preferences panel Using Z-Modem Using X-Modem The "ZModem" Preferences panel "Z-Modem" "X/Y-Modem" "Transfer" Preferences panel options "ASCII Default" "Download": Options affecting downloads "Upload": Options affecting uploads File transfer progress dialog ___________________________________________________ File transfer overview ___________________________________________________ The folder in which the session document is located is the default folder for up- and down-loading, unless "Comet Default" is the document being used, in which case the default download folder is the application's home directory. To switch folders you can use the File menu commands "Set download directory" or "Type file name at cursor" (the latter also inserts a file name at the cursor position). These commands use the standard file interface. When you create a new file by saving text or downloading a file, the file is set by default to be a dataComet document; you can cause files to be saved with a different document type by using the "Set default file type..." dialog before you download the file. Alternatively, when SCP, IND$FILE, or Z-Modem downloads are performed, the type may be set using MacBinary or BinHex document information, or Internet Config may be used to map file extensions to a document creator. When files are downloaded, dataComet checks the file name, and processes filenames with certain suffixes in special ways. (The suffix is the portion of a filename at the end which is preceded by a '.') These suffixes are: ".rename" Offers the user a chance to rename the file. ".edit" When you do a file download to a file with the same name as a session's .edit window, the downloaded text will be automatically appended to the window. Likewise, an upload using a session's .edit window name will cause dataComet to save the window before the upload is performed. (E.g., this is performed when a session is named "theory", and you download a file named "theory.edit".) You can automatically add or delete carriage returns in your text using options in the "Session" Preferences panel dialog, so that you can more conveniently use the TextEdit text wrapping on your Mac and have the paragraphs reformatted properly for your host. AutoLaunch and automatic wrapping options in the "Transfer" Preferences panel provide an alternative to using the ".edit" feature when Z-Modem is used for file transfer. When using Z-Modem, filenames ending in ".bin" and ".hqx" will be decoded using MacBinary and BinHex protocols, respectively. ___________________________________________________ AutoLaunch and Internet Config "File Mappings" ___________________________________________________ If Internet Config is installed and IC suffix-file mappings are enabled, binary mode will be selected automatically for both uploads and downloads according to the settings in the Internet Config "File Mappings"--i.e., the "Binary" setting and "Not for incoming"/"Not for outgoing" settings for that file type. For IC downloads the document's file type and creator are set to those specified for the file's extension in the Internet Config "File Mappings" (e.g., ".doc" is set as an MSWord document; ".txt" is set as a TextEdit document). For IC uploads filenames have appropriate extensions (e.g., ".jpg") added automatically. This is off by default. Unfortunately Internet Config is no longer fully supported under MacOS X. You can change the Internet Config "File Mappings" by launching Internet Explorer; Internet Explorer's "Preferences..." "Protocol Helpers" and "File Helpers" dialogs allows you to control these mappings. If Internet Config is NOT installed, MacBinary and BinHex files are set to the type and creator specified in the original document. Text files are set to type 'TEXT', using the creator you're specified for this session in the File menu item "Set default file type...". Files containing a ".sit" extension will be opened using StuffIt Expander. ___________________________________________________ File transfer menu options ___________________________________________________ This list contains the file transfer options in the menu which are not duplicated exactly in the File transfer dialog (see below). "Type file name at cursor...": Brings up a directory dialog box for you to select a file whose name you want to type on the dataComet screen. The download directory is set to the last directory you use. "Download - Set directory...": Bring up a Macintosh Standard File dialog which allows you to choose a default download directory. (You need to select a file in the directory to get it to select a directory, otherwise the Standard File dialog opens the directory selected in the listÉ a "Set Directory" button will eventually be added to this dialog by dataComet to address this Standard File defect.) "Upload...": Presents a dialog to select a document to upload using the default file transfer Protocol selected in the "File Transfer" dialog. If the current window is an edit window, the edit document is saved and uploaded automatically without a dialog. If Internet Config is installed, dataComet appends file suffixes appropriate for that document (e.g., TextEdit documents will have ".txt" appended). When using an IBM host and the IND$FILE protocol, the IND$FILE dialog will come up to allow you to select the host file name. If you are connected to an ASCII host, the "rz" or "rx" program is automatically invoked on the host, with appropriate parameters depending upon whether the file is a text or binary file. (To avoid automatic host program invocation, you can use "Option-Upload"; you will then need to type the host command yourself). Uploading folders: When Z-Modem is used, you can upload all the documents in a folder using the "Upload..." dialog by clicking on the "Transmit" button with the mouse (pressing the Return key when a document is selected will upload the document; for folders, however, pressing the Return key opens the folder rather than uploading it). To make maintaining remote directories quick and easy, Z-Modem "Newer" mode is set for folder uploads, so existing files are uploaded only if they are updated versions. To guarantee that a file is uploaded even when it's not newer, you can upload only one document at a time; for single documents dataComet Z-Modem uploads always overwrite the destination file. NOTE that after uploading a file to a host, you may need to change file permissions in order to make a file publically accessible if the file is part of a web page or is to be retrieved from an FTP server. (E.g., under UNIX the file permissions need to be set using "chmod 644 filename"; likewise new directories may need to be made readable using "chmod 755 directoryname". Other operating systems have similar security features, so if network file accesses fail check the permissions on the file or directory.) "Download...": Accepts a download from the host using the default protocol. "Compuserve QuickB...": NOT CURRENTLY SUPPORTED. Presents a dialog to perform a QuickB file transfer. "X-Modem Transmit", "Receive": Performs an upload or download using X-Modem rather than the default protocol. "Y-Modem Transmit", "Receive": Performs an upload or download using Y-Modem rather than the default protocol. "Z-Modem Transmit", "Receive": Performs an upload or download using Z-Modem rather than the default protocol. ___________________________________________________ File transfer with IBM hosts using IND$FILE ___________________________________________________ The IND$FILE file transfer protocol can also be used to transfer files between the Macintosh and an IBM mainframe. You can enter the file transfer command directly in the host screen, or use the "IND$FILE" dialog to compose the command. You can bring up this dialog using the "Upload..." command (Command-U) in the File menu "Transfer" submenu. Files may be transferred in either ASCII or Binary mode. In ASCII mode characters are translated between IBM's EBCDIC character encoding and ASCII character encoding by the mainframe, and spaces are stripped from the ends of lines by the host when a download to the Mac is performed. One can also add "CRLF" to specify translation of Carriage Returns. The IBM host adds a Carriage Return and LineFeed to the end of each record; dataComet's IND$FILE will convert the CR/LF pairs to the Macintosh CR standard line terminator or vice-versa. You can specify automatic wrapping or unwrapping of lines for uploads and downloads, respectively, using the options in the "Transfer" Preferences panel, along with other encoding options such as MacBinary or BinHex. Normally you will use either "ASCII CRLF" or plain Binary to perform a file transfer. ___________________________________________________ Using the "IND$FILE..." command dialog ___________________________________________________ This dialog helps you construct a valid host command to perform a file tranfer with an IBM host using the IND$FILE protocol. The dialog will try to automatically construct a plausible target file name if you enter a name and then use the Tab key to enter a name field which is not yet set. Pressing the "Get/Put" button or the Return key will execute the transfer (you may need to enter a Clear or PA2 to continue the transfer after the command is entered if the host goes into a HOLDING state). If you need to add options not available in the dialog, you can hold down the Shift key while OK'ing the dialog, and the command will be typed on the 3270 screen without being Entered. "Folder...": Presents the standard file dialog to allow you to select an upload/download folder. "Mac file...": This button brings up the standard file dialog so you can select a Macintosh file. If a host name is not yet specified, a plausible target host file name, transfer options, and file encoding (e.g., BinHex) will be automatically selected; you can change the name and Options if you wish. "Host file": This field contains the name of the host file, which must be in the form of a valid IBM file specification (normally, this file specification is of the form "NAME TYPE VOLUME" where the NAME and TYPE are limited to 8 letters, and the VOLUME specifies the logical disk to be used (by default the "A" drive). Options: "ASCII CRLF": ASCII with CR/LF interpretation. "ASCII": ASCII without CR/LF interpretation. "Binary CRLF": Binary with CR/LF interpretation. "Binary": Binary. "Overwrite": Erase the target file before the transfer. "Append": Append the file being transferred to the target file. "Protect": Disallow over-writing of existing Mac files on download. "Put to host": Make a PUT command to upload a file from the Mac. "Get from host": Make a GET command to download a file to the Mac. "Transfer...": Brings up the "Transfer" Preferences panel, which allows you to select general options controlling the transfer, for example, automatic text wrapping and unwrapping. "IND$FILE...": Brings up the IND$FILE configuration dialog, which allows you to select more options for controlling the transfer. ___________________________________________________ The "IND$FILE" Preferences panel ___________________________________________________ "IND$FILE command": Enter an alternative command name if the host does not use "IND$FILE" to execute the file transfer. "Host OS": The Operating System on the IBM host determines the format and options applicable for the command string. "TSO": "CICS": "VM/CMS": "Record Type": Selects host record type and length. (Applies only to uploads to some OS types.) "Default": "Fixed": "Variable": "Undefined": "Logical Length": "Block Size": "Allocation": Selects host file allocation variables. (Applies only to uploads to some OS types.) "Default": "Tracks": "Cylinders": "AVBlock": "Primary": "Secondary": ___________________________________________________ File transfer with SSH hosts using SCP ___________________________________________________ The SCP (Secure Copy) file transfer protocol can be used to transfer files and folders over Secure Shell connections made with dataComet-Secure. To start a file transfer, you can use the "SCPÉ" dialog, which will help you construct an SCP command that will perform the transfer. SCP may make error reports. These include "filename: not a regular file", which indicates that a directory specified as a target was skipped, and "ambiguous target" which indicates that multiple file or directory names were used in the SCP command in an amiguous fashion. Other reports, such as "protocol error:" "unexpected ", "lost connection", or "expected control record", indicate that an internal error has occurred. ___________________________________________________ Using the "SCP..." command dialog ___________________________________________________ "Folder...": Selects a Mac folder as a source for uploads or target for downloads. "Mac File...": This button brings up the standard file dialog so you can select a Macintosh file. You can also enter a filename directly in the field; you can use '*' and '?" in the name as wild card characters to transfer multiple files. "SCP Directory": Specifies a host directory, used for directory and sub-directory transfers. "SCP File": Specifies the host file(s) to transfer (primarily for downloads). "Copy sub-directories": Allows transfers of all files and directories in the selected directory. NOTE that if you leave all the text fields empty, the contents of the folder (or directory) will be transferred, including sub-directories and their contents if "Copy sub-directories" is on. Options: "Automatic", "Binary", "ASCII": Allows selection of file transfer types; files transferred in ASCII mode may be extensively reformatted, while files transferred using Binary mode are not modified in any way. Selections made in the "Transfer" Preferences panel controlling CR mapping, text wrapping, document launching, etc. may also apply, depending on the transfer mode. "Overwrite": Erase the target file before the transfer. "Append": Append the file being transferred to the target file. "Protect": Disallow over-writing of existing Mac files on download. "Put to host": Make an SCP command to do uploads from the Mac. "Get from host": Make an SCP command to do downloads to the Mac. "Transfer...": Brings up the "Transfer" Preferences panel, which allows you to select general options controlling the transfer, for example, automatic text wrapping and unwrapping. NOTE that only one SCP file transfer can be executed at a time. ___________________________________________________ The "SCP" Preferences panel ___________________________________________________ "OS": In the future these radio buttons will allow selecting a default SCP command for different operating systems. Currently only systems that allow excecution of the "UNIX": shell command are directly supported; "DOS": is not. You may be able to use the Customized SCP command option described below to make an SCP file transfer. "Default SCP command:": Shows the default SCP command. dataComet's implementation of SCP allows the SCP file transfers with the context of a normal terminal session, rather than requiring a separate SSH session to perform a download. Doing this requires that dataComet issue a command to the host, executing a separate shell, turning off interpretation of special characters, entering the "scp" command, and finally restoring the original terminal settings. "Use RCP command": Use the "rcp" command to execute file transfers on the host command line, for cases where the host does not have SCP installed. "Use customized SCP command:": allows you to issue a customized command if the default command does not work properly with a host. "File modes":, "Directory modes": These arrays of check boxes allow you to set the permissions which will be set on files and/or folders which are uploaded to the host. By default, dataComet saves the host mode flags in the "last backup date" field in the file or folder's file description when they are downloaded. If the "File modes" or "Directory modes" check boxes are on, the selected modes are used; if they are turned off, the mode flags saved in the "last backup date" field will be sent to the host, allowing preservation of the UNIX file permissions. ___________________________________________________ Using Z-Modem ___________________________________________________ If you're doing file transfers, Z-Modem is the best protocol to use if it is available on your host. Here are some suggestions for using Z-Modem with dataComet with its default settings for file transfer... To download text files using dataComet's Z-Modem, you can use sz mytextfile without specifying the '-a' to transmit text files, since by default newlines are automatically converted to Macintosh CR format (see below for the dialog option which allows you to change this setting). To download a file which is a binary when this automatic text translation option is on, you can use sz -b mybinaryfile which will turn off the text translation option. When the download has completed, dataComet will convert MacBinary (.bin) and BinHex files (.hqx), and then AutoLaunch the resulting document with the selected helper application. You can use the "Upload..." menu item (Command-U) to select a file or folder to upload; the "rz" command will be automatically run on the host (you can hold down the Option key to suppress automatic "rz" command invocation). If you use the "Upload..." command when a dataComet edit window is frontmost, the edit window will be saved and uploaded to the next frontmost host session. (Note that this is not the case if this is a session's .edit window, in which case the dialog is still displayed). NOTE that only one Z-Modem or X-Modem file transfer can be executed at a time. You can still do work in other windows during a file transfer, including emulator sessions, but you cannot perform Z-Modem or X-Modem downloads using another session until the current file transfer is complete. ___________________________________________________ Using X-Modem ___________________________________________________ If you're using X-Modem, note that you download a file the file extension you append when prompted for a filename will be used to determine the filetype for transfer character mapping, CR conversion, and other options; if no suffix is appended to the filename (i.e., ".txt"), downloaded files will be transferred in binary mode. ___________________________________________________ The "ZModem" Preferences panel ___________________________________________________ _____________________________________________ "Z-Modem" _____________________________________________ "Timeout (seconds)": Number of seconds to wait before performing a retry (default 10). "Maximum retries": Number of retries to perform before giving up on a file transfer (default 10). "Receive Buffer size": Allows you to specify the size of the buffer; zero is the default, which automatically selects a size appropriate to the type of connection. "Transmit:": The following options affect Uploads. "Sub-packet length": Allows you to limit the size of sub-packets to help compensate for bad connections (default 1024). You should use a shorter sub-packet length if you find that transfers are performing numerous retries due to errors. "Window limit": Allows you to set a limit on how many bytes are sent to the receiving end at one time (default 4096). Setting the Window limit to 0 (zero) may speed uploads; the default is 4096 because in some cases hosts may not be able to handle input processing quickly enough. "ZCRCQ spacing": Allows you to require periodic ZAKS (acknowledgments that data has been received) from the receiving end (default 0, which implies that ZAKS are not required). "Escape all control characters": Allows you to escape all control characters over connections which use them for connection control purposes. Try this if you find that connections fail mysteriously. _____________________________________________ "X/Y-Modem": _____________________________________________ "1K": "Off":, "Auto":, "CRC-1K": Selects the packet size (128 vs. 1024 bytes/packet). "CRC-1K" will attempt to negotiate 1K blocks with the host; "Auto" mode will accept 1K blocks if selected by the host YModem program. "Batch": "Off":, "On":, "RR": Selects Y-Modem batch mode. "RR" is supposed to be compatible with the "Red Ryder" (a/k/a "White Knight") implementation of Y-Modem. "Timeout": " 5":, "10":, "15": Selects a timeout value in seconds (default 10). "Use CRC": Use a CRC (Cyclical Redundancy Check) to ensure that data is not garbled in transmission. ___________________________________________________ "Transfer" Preferences panel options ___________________________________________________ "Folder...": Selects a target folder for downloading. This is automatically saved as a string in the session document. "Options...": Opens the dialog which allows you to select options for controlling X/Y/Z-Modem file transfers. "IBM IND$FILE...": Opens the dialog which allows you to select options for controlling IBM IND$FILE transfers. "Translate TEXT": Enables translation of characters from the Macintosh character set to host character set and vice versa, using the table selected for the session with the "Control Translation" menu. (Note: this option does not apply to IND$FILE transfers, since the host performs the ASCII translation.) _____________________________________________ "ASCII Default": _____________________________________________ "Z-Modem":, "X/Y-Modem":, "SCP": Selects a default protocol to use for file transfer. "Options": Brings up a dialog which allows you to fine-tune X/Y/Z-Modem settings... _____________________________________________ "Download": Options affecting downloads _____________________________________________ "AutoReceive": Automatically receive Z-Modem downloads. Incoming data from the host is scanned for the Z-Modem string which prefaces a download, and automatically accepts the file, so that you don't need to execute a "Download..." menu item after entering the host command "sz filename". "AutoLaunch": Automatically launch a downloaded document after performing MacBinary or BinHex decoding. The "File Mappings" settings from Internet Config are used if IC has been installed. E.g., if you download a correctly-named GIF file, "whatever.gif", the GIF image will automatically be displayed by JPEGView; if you download "index.html", the web page will be displayed by your browser. "AutoDecode": Allows you to disable automatic decoding of BinHex and MacBinary transfers. "CR/LF -> CR": Automatically detect and convert text files to Macintosh format. DOS uses CR/LF pairs, and UNIX uses LF (LineFeed) characters to indicate the end of a line rather than a single CR (Carriage Return), which is used on the Mac to start a new line. This is on by default. "UnWrap Paragraph": Automatically unwrap downloaded text files into Mac TEXT format (Carriage Returns appear only at the end of paragraphs; CRs or LFs denoting the end of lines are stripped). "IC Suffix -> Type": Turns on Internet Config suffix mapping on downloads, so that file types are derived from the IC "File Mappings" settings, rather than the options below: "TEXT App": The default helper application for TEXT files when IC is not used. This is '????' by default, so that the system will use the file suffix to determine the application to use. "BIN App": The default helper application for BINARY files when IC is not used. This is '????' by default. "BIN Type": The default file type for BINARY files when IC is not used. This is '????' by default. IC file mappings supersede information in MacBinary and BinHex headers on downloads, allowing you to use an application different from the original document's creator. IC file mappings are also used to determine whether a file should be uploaded as a text or binary file. _____________________________________________ "Upload": Options affecting uploads _____________________________________________ "No Encoding": Disable file encoding when uploading. "MacBinary": Use MacBinary protocol to encode files when uploading. This preserves a document as a Macintosh format file. "BinHex": Use BinHex protocol when uploading. This preserves a document as a Macintosh format file; BinHex is less efficient than MacBinary, however, files encoded using BinHex can be transferred over connections which can only transmit 7-bit characters, so it is still the standard for the distribution of binary files. "Encode TEXT": Encodes 'TEXT' documents when uploading, in addition to other documents, which are always encoded when MacBinary or BinHex is selected. "Wrap @": ____: Wraps outgoing TEXT at the specified column. "DeTab": Expands tabs to spaces. The edit field allows you to select the tab stop to which a TAB will be expanded. (Currently applies only to IBM IND$FILE transfers.) "IC Type -> Suffix": Toggles Internet Config suffix mapping on uploads, so that file suffixes are derived from the IC "File Mappings" type/creator settings, rather than: "TEXT suffix": A suffix which is appended to uploaded TEXT files when IC is not used. ___________________________________________________ File transfer progress dialog ___________________________________________________ "Total": The total number of bytes in the file to be transferred. "Done": The number of bytes transferred. "Remaining": The number of bytes remaining to transfer. "Bytes/sec": An estimate of the number of bytes per second transferred. "Blocksize:": The Z-Modem block size (or in X-Modem, the block number). "Errors": The number of errors seen transmitting the current packet. "Time": Beneath this label the "Time Done" is displayed to show the total elapsed time for the file transfer. Further down the "Time Remaining" is displayed to provide an estimate of how much time remains before the transfer is completed. Transfer labels: "BinHex": The file being transferred is a BinHex file, downloaded files will be decoded automatically. "MacBinary I": "MacBinary II": The file is a MacBinary file; downloaded files will be decoded automatically. "CR -> NL": The TEXT file being uploaded is being converted. "NL -> CR": The TEXT file being downloaded is being converted. "Wrap": The TEXT file being transferred is having its lines wrapped to or from Macintosh format. "Launch": The downloaded file will be opened automatically. Z-Modem States: "ZRINIT": A file download is being negotiated. "ZCHALLENGE": Responding to file download request. "ZRQINIT": A file download is being requested. "->ZNAK": A ZNAK has been sent to request a packet resend. "ZFILE error": An error occurred transmitting a File header. "ZSINIT ok": File upload negotiation OK. "ZSINIT error": An error occurred negotiating an upload. "ZFREECNT": The space available on your disk was requested. "hdr-ZNAK": A ZNAK has been sent to request a header resend. "hdr-ZFILE": A File transfer Name/Header is being transmitted. "hdr-ZEOF": The End-Of-File for a transfer has been seen. "hdr-ZSKIP": The receiver wants to skip the file. "hdr-ZDATA": Data transmission is starting. "data-TIMEOUT": A timeout has occurred while waiting for data. "data-ERROR": An error occurred receiving a data packet. "data-ZCRCW": A data packet was received with a frame end and an ACK request. "data-ZCRCQ": A data packet was received with an ACK request. "data-ZCRCG": A data packet was received. "data-ZCRCE": A data packet was received with a frame end. "hdr-TIMEOUT": A timeout has occurred while trying to transmit a header. "hdr-ERROR": An error has occurred while trying to transmit a header. ___________________________________________________ ________________________________________________________________