Apple II SAFE2 Reference Manual GS

Document technical information

Format pdf
Size 746.2 kB
First found Jun 9, 2017

Document content analysis

Language
English
Type
not defined
Concepts
no text concepts found

Persons

Organizations

Places

Transcript

Apple® IIGS
SAFE2 Reference Manual
1
Dedicated to the memories of Joe Kohn 1947-2010
and Ryan Suenega 1967-2011
SAFE2 is Freeware and Copyright © 2006-2014 Ewen Wannop
SAFE2 and its supporting documentation may not be printed,
copied, or distributed for profit.
Distributing and/or archiving is restricted while in an electronic form.
Any “free” distribution must be given permission by Ewen Wannop
in advance -- please contact via email by sending mail to:
[email protected]
There is no guarantee that the right to redistribute this material
will be granted. The contents of this document may not be
reprinted in part or in whole.
Credits
My thanks go to all who have helped me develop SAFE2,
and especially for their extensive beta testing, many suggestions,
and error corrections: David Finnigan and Andrew Roughan
2
Contents
Preface
!
!
Welcome & Background
Introduction!
4
5
SAFE2 File Transfer
!
Requirements
Installation
Legal
6
7
8
The Menus! !
!
!
Apple & File !
Edit
!
Settings !
11
12
13
Working with SAFE2
!
!
The Main Window
Transferring Files
Managing Favourites
Setting Preferences
Log File!
15
22
28
30
33
Balloon™
Balloon™ Support
36
Extras
!
!
Help
Problems
Other Information
37
37
37
3
Preface
Welcome to SAFE2
Welcome
The Internet has advanced rapidly over the years, and the IIgs has at times
struggled to keep up. With the introduction of SIS back in 1997, we entered the
battle in earnest. SIS is still a force to be reckoned with, but sadly web pages are
often now so complicated, that SIS struggles to even display them at all.
The Internet is more than just the web, and most of us will also be emailing, or
even transferring files using FTP. Over the years, I have written various
applications, with SAM2 handling your email, SNAP handling Usenet and
newsgroup access, and SAFE2 accessing FTP servers. My earlier application
Spectrum™, is still a viable and useful tool, as it supports Marinetti™, and can
handle Telnet connections.
Background
Some years ago, I wrote the SAFE script set for Spectrum™. SAFE gave simple
File Transfer Protocol access to hosts such as Syndicomm, or your ISPs web
servers. SAFE worked fairly well, but because it was written in Spectrum™
scripting language, was desperately slow in operation.
Having recently embraced Ethernet access to my local LAN using an Uthernet™
card in my IIgs, and from there, access to the Internet using ADSL, I needed a
quicker way of getting files easily into and out of my IIgs than the original SAFE
provided.
Thus SAFE2, or Son Of SAFE was born. Those familiar with the original SAFE
will feel at home with its interface, though they will find some welcome changes.
4
The main difference, apart from the new found speed, is that SAFE2 is a
standalone application, so does not require Spectrum™ to run.
With emulators now beginning to be able to access the outside world through
Ethernet connections, SAFE2 is even more important as the easy way of getting
files directly into your IIgs environment.
Introduction
SAFE2 uses a simple metaphor for FTP file transfers. Once you have logged into
a host, your local files appear in the window on the left, and the host files appear
on the window on the right. To copy files back and forth, just select the files and
folders that you want to copy, and then click the relevant Transfer button. The
files, and or folders, will then be automatically transferred from one window to
the other.
In addition, SAFE2 has a number of useful functions that simplifies accessing
your favourite hosts, and that allows you to manage the files and folders at both
ends.
SAFE2 is a stand alone application, and requires a minimum of 1Mb of free
memory.
SAFE2 requires a TCP/IP connection through Marinetti 3.0 or later. Marinetti
must be configured to access either your LAN, or the Internet, through one of the
available Link Layers. Refer to the Marinetti instructions on how to get the
appropriate Link Layer working for your preferred access.
Check out some of my other contributions to the IIgs world on my web site:
http://www.wannop.info/speccie/
SAFE2 is Freeware and Copyright © 2006-2014 Ewen Wannop
5
Setup
SAFE2 FTP File Transfer
Requirements
SAFE2 is a stand alone application, and requires a minimum of 1Mb of free
memory.
SAFE2 requires a TCP/IP connection through Marinetti 3.0 or later. Marinetti
must be configured to access either your LAN, or the Internet, through one of the
available Link Layers. Refer to the Marinetti instructions on how to get the
appropriate Link Layer working for your preferred access.
It is recommended that you get the very latest version of Marinetti, as it is still in
development, and bug fixes may have been made.
As of SAFE2 2.1.8, the Time Zone tool by Geoff Weiss is also required. This has
been included with this archive in case you do not yet have it installed.
To obtain SAFE2, the HTML Tool, the Uthernet Link Layer, and any of my other
software::
http://www.wannop.info/speccie
To obtain the latest version of the Marinetti TCP/IP stack:
!
http://www.apple2.org/marinetti/
To find out about, and order an Uthernet card:
http://www.a2retrosystems.com/
6
Installation
This is simplicity itself.
1. From the Archive folder, copy the SAFE2 file to a working folder of your
choice.
2. Copy the SAFE.8 font to the Fonts folder in the System folder of your boot
disk. Usually dragging and dropping the file to the System folder icon will suffice.
Note: A copy of Shaston.16 is also supplied. This has been used in the
documentation, so if you do not already have it installed, please copy this font
over as well.
3. From the TimeZone folder, copy the TimeZone CDev to the CDevs folder in
your System folder, and Tool056 to the Tools folder.
4. For those using the Uthernet card, an v1.0.1b2 update to the Link Layer has
been provided. This gives better compatibility, and will let you gain control, if for
any reason your Ethernet link becomes broken. Copy the Uthernet Link Layer
file to the TCPIP folder in your System folder, replacing the existing file, and
reboot.
5. Go to the TimeZone CDev in the Apple Menu, and select your time zone from
the menu. Now go to the Time CDev, and set either Auto daylight savings if you
are in a time zone that respects standard daylight saving, or if it does not, to
Standard or Daylight Time depending on what is currently being observed.
6. You are now ready to go. Fire up SAFE2, and start transferring those files!
The first time you start SAFE2, two folders will be automatically created in the
folder that you placed SAFE2. A default Downloads folder, and a SAFE2.Data
folder. Inside the data folder, preference files, favourites files, and log files will
automatically be created.
Note: If you are updating from SAFE2 v2.1.0bx, you may find you need to reset
your preferences, as the original settings get overwritten.
7
7. Optionally, you can install online Help for SAFE2...
If you do not already have !Help! installed on your IIgs, copy the Help NDA, and
the entire Help.Files folder, from the Help folder in the Archive, to the Desk.Accs
folder in the System folder.
If you already have !Help! installed, then just copy the SAFE2 folder from the
Help.Files folder in the Archive, to the Help.Files folder in the Desk.Accs folder.
If you already have !Help! installed, just copy yhe SAFE2 folder to the existing
Help.Files folder.
Note: These files are updated in each release of SAFE2.
Note: If you are running SAFE2 under the Sweet16 IIgs emulator on a
Macintosh running OSX 10.7 or later, and wish to FTP into the Macintosh, you
will need to first turn on 'File Sharing' in the Sharing Preferences dialog, making
sure that the share for the account you wish to use is set to 'Read & Write'. Only
after that has been done, you must then turn on the FTP server on the Mac,
which by default is turned off.
Issue this command from Terminal:
sudo -s launchctl load -w /System/Library/LaunchDaemons/ftp.plist
To stop the FTP server, it's the same command, but with 'unload'. If you ever
turn off 'File Sharing', you will need to reissue the load command again in
Terminal, after File Sharing has been turned back on.
In addition...
SAFE2 supports both SideClick by Eric Shepherd, and Balloon™ 2.0 by Josef
W. Wankerl.
You will find Keybd.Extender by Bill Tudor in the Extras folder. This useful Init
gives you a true Delete key in place of the IIgs Backspace key.
8
Legal
SAFE2 is Freeware, and may be distributed freely, provided the archive stays
intact, no alterations are made to it, and full attribution is always made to the
author Ewen Wannop. SAFE2 may not be sold in any form, but may be included
in other distributed archives, provided you first seek my permission.
Contact
For any communication relating to SAFE2, for bug reports, or for technical
support, please contact:
[email protected]
For my Home Pages, Spectrum updates, Spectrum itself, and all my other
software:
http://homepage.mac.com/speccie/
9
Menus
SAFE2 Quick Reference
!
!
The Menus
Apple Menu
!
About SAFE2
Set System Clock
File Menu
!
Connect TCP/IP
Disconnect TCP/IP
Synchronise Folders
Download Linked File
Quit
Edit Menu
!
!
!
!
!
!
Undo
Cut
Copy
Paste
Select All
Only Send Text Files
Settings Menu
!
Add Current to Favourites
Edit Favourites
Set Preferences
Set Default User
View SAFE Log
10
Apple Menu
About SAFE2
This opens a small window showing the SAFE2 Version number.
Set System Clock
If you have correctly set the Time Zone CDev to your time zone, and have set the
Time CDev to auto daylight, daylight, or standard time, depending on what your
time zone observes, this command will set the IIgs system clock to the correct day
and the nearest second.
Note: If the IIgs system time was not within the correct day, this may result in a
one hour difference from the correct time, depending on whether you are
currently observing daylight time or not. To fix this problem, open and close the
Time CDev, and then call this command a second time. As long as the system
time is within the correct day, opening and closing the Time CDev will set the
'daylight' time flag in the system BRam, and as a result, this call will set the clock
correctly.
File Menu
Connect TCP/IP & Disconnect TCP/IP
The state of these two menu items will depend on whether Marinetti is currently
connected or not.
If you have a permanent connection to a LAN, or the Internet, then you will
probably have already configured the Link Layer in Marinetti to connect at boot.
If however you are using a dialup connection using the PPP or SLIP Link
Layers, then you will have probably told Marinetti to only connect on demand.
At any time, you can toggle your TCP/IP connection with these two menu items.
If you are currently connected to a host, you will be asked to confirm that you
wish to disconnect from the host before TCP/IP can be disconnected.
As SAFE2 will automatically connect TCP/IP when needed, and as additionally
you can tell SAFE2 in its preferences dialog to always disconnect TCP/IP when
you close a host connection, you may not ever need to use these two menu items.
11
Synchronise Folder
Opens a dialog where you can choose to either synchronise up or down between
the currently displayed Home and Away folders. See the section below for more
details.
Download Linked File
Opens a dialog where you can enter a URL link to manually download a file from
an FTP server or a web site. The link must be a valid and full link to an existing
file, and must start with either ftp:// or http://.
This feature is useful for downloading program and other files to the IIgs directly
from Apple II web or ftp archives.
Optionally you can add a port number to the web URL in this fashion:
http://www.somewhere.com/a_file.bxy:8080
Optionally you can add a user name and password, and an ASCII or Binary
download type, to the FTP URL:
ftp://name:[email protected]/home/a_file.bxy;type=a(i)
Quit
When you are finished transferring files, this will close all open connections,
optionally disconnect TCP/IP, then quit SAFE2, and return to the Finder.
Edit Menu
Undo, Cut, Copy, Paste, Clear & Select All
These commands are provided mainly for use within Desk Accessories. They are
however active in most of the LineEdit controls that are used for setting up
Favourite entries, or in the other dialogs.
Only Send Text Files
As binary files can normally only be sent as raw binary data by FTP, and thus any
filetypes and resource forks would be lost, you may only want to send text files.
12
If you tick this menu item, only files of file type $04 will be sent. If it is not
ticked, then all files will be sent, but only the data fork of a forked file will be
sent.
Note: Refer to the section on Preparing files for Transfer to see how to deal with
sending forked files.
Note: If you have checked the upload 'Encode' box, regardless of this setting, all
files will be sent. This is because automatic encoding will allow any kind of file to
be sent, preserving both the filetype and the resource fork.
Settings Menu
Add Current to Favourites
This will open a dialog window allowing you to save details of the currently
connected host to the Favourites list. The host path, username, and password, will
be used for the new entry, and you can optionally edit the current directory path.
Enter a unique name to identify the new item in the Favourites list.
Edit Favourites
This opens a dialog allowing you to manage and edit your Favourites. Refer to the
section on Managing Favourites for more details.
Set Preferences
This opens a dialog allowing you to manage and edit the SAFE2 Preferences.
Refer to the section on Setting Preferences for more details.
Set Default User
This opens a dialog allowing you to enter a default username and password. If
the User Name field in a Favourites dialog, or Connect dialog, is empty, then the
defaults set here will be used instead. Many public systems accept 'anonymous'
as the User Name, and a valid email address as the password.
If the Default User has not been set, or has not been entered in Favourites, or in
the Manual Download URL, then at login time, you will be prompted for any
missing Username and Password.
13
View SAFE Log
SAFE2 keeps a running log file showing all the events that you have activated
during a session. You can view this file at any time, and especially, you can refer to
this log if you have had any problems with file transfers. You can copy text out of
the window, but you cannot edit the text itself. Refer to the section on the 'Log
File' for an explanation of what it might show.
The log file is reset on the first day of each month, with the older file being
renamed to show the month and year when it was created. The log files are kept
in the SAFE2.Data folder. You can optionally decide not to keep the log file
automatically updated from the Preferences Dialog.
If the log file has grown large over time, only the last 64K of the file will be
displayed.
Close the Log View window with OA-W, the Escape or Return key, or by clicking
on the 'OK' button. You can also ‘Quit’ SAFE2 from here if you wish.
SideClick
If you have SideClick by Eric Shepherd installed, you can change the settings of
the ‘Force ASCII’ and ‘PASV Mode’ values, by right clicking from the main
display. The changes will take effect immediately.
You can also add the URL, file name, or path name, of any selected files in the
Home or Away lists to the clipboard, or Edit a Favourite item. This is context
sensitive, so not all options may show depending on which list is selected.
14
Basics
Working with SAFE2
The Main Window
The Transfer window consists of three main interactive areas, the Home folder on
the left, the Away folder on the right, and a row of buttons and button icons. In
addition, there is a title bar, three information strips, and a progress thermometer.
If you are not yet connected to a host, the Away folder will display a list of any
Favourites you may have defined.
15
Home folder
Navigate by double clicking directories to tunnel down, and double click the
[Previous Directory] item to go back up one directory. If you go back up from the
top folder in the current disk, you will see a list of all the disks that are mounted.
You can also see this list by clicking the Disks button. Double click a disk entry to
open that disk. You can multi select files for transfer or deletion.
Symbols to the left of the filename indicate what kind of file it is:
Open diamond = text file
Closed Diamond = binary file
Open Cross = Forked file
Folder = Subdirectory
Return = Previous Directory
Note: Hidden files are never displayed.
Note: If you have checked the upload 'Encode' box, the size of both forks of a
forked file will be displayed, otherwise, only the size of the data fork is displayed.
Away Folder
This will show all the files that are available at your access level in the host
folder. Navigate in the same way as with the Home folder. You can return to the
Home or starting folder at any time by clicking the Home icon. You can multiselect files and folders for transfer or deletion.
Symbols that show to the left of the filename will indicate access levels to a file:
No Symbol = Read and Write access
Up Arrow = Write Only
Down Arrow = Read Only
Cross = No read or write access
Folder = Subdirectory
Folder = Write only (Drop Box)
Folder = Read Only
Folder = No access
Return = Previous Directory
16
Note: If you are at top level, there will not be a [Previous Directory] item
showing at the top of the list.
Note: Please read the section on permissions for more details.
Title Bar
When first connected to a host, this will display the first line of the welcome
message sent by the host. As you navigate down and back up any folders on the
host, it will show the name of the current directory. If necessary, it will truncate
the middle of the path to fit the Title bar.
Top Message
This will display various messages, depending at what point in a session you may
be. For most of the session, it will display details of the host System.
Bottom Message
This will display various progress messages, and will keep you informed as to
what the current state of your session may be.
Thermometer Bar & Transfer Report
During a file transfer, the thermometer will show how far into the transfer you
have got. If you are resuming transfer of a file, this will start at the point the
transfer was resumed.
To the left of the thermometer, the B/s or KB/s transmission speed is shown,
along with how many bytes have currently been transferred for that file.
Note: If you are running SAFE2 under a fast emulator, it is possible that SAFE2
is able to send out data faster than the emulator can process it. In such cases,
SAFE2 will allow the send queue to reach a fixed size before it pauses and waits
for it to clear. If you are sending a large file, this may result in the progress
thermometer rapidly increasing, then apparently stalling for long periods of time.
Be patient!
Buttons and button icons
Note: The state of these buttons and icons will change depending on whether
you are connected, disconnected, transferring files, or listing directories.
17
The buttons reading from left to right:
Trash icon button
Will delete a file, files, or folders, from the Home folder. Confirmation will be
asked. Any enclosed hierarchical directories, and their contents will also be
deleted. If there are any locked files within a folder, then those files will not be
deleted, along with their enclosing folders.
Note: Be careful, as you can easily delete a large number of files and directories
with this command.
Balloon icon button
This icon will be grey unless you have Balloon™ installed, when it will be grey
when offline, and when online, will turn red when inactive, or green when active.
Disks icon button
Displays all the disks that are currently mounted. Double click a disk entry to
open and display the top directory of that disk.
New Folder button
Opens a dialog asking for the name for a new folder to be created within the
current Home folder. If you enter an empty value, no folder will be created. Once
the folder has been created, it will be opened, and its empty directory will be
displayed in the Home folder. Invalid folder names will be automatically
corrected to suit the current filing system.
Transfer-=> button
If you are connected to a host, and have selected one or more files or folders
from the Home folder, this will transfer these files to the directory currently listed
in the Away folder. Once all the files have been transferred, the Away folder will
be relisted to show the files that you have transferred.
Note: If you have selected a folder, the entire hierarchical contents of the folder
will be transferred, creating folders on the host as necessary. Be careful, as you
can easily transfer more files than you realise!
18
Upload Encode checkbox
This is the top box of the pair, and becomes active when you are connected to a
host. If it is checked, all files transmitted will be encoded in the AppleSingle
format. You can check this box to change the setting of the 'Encode' flag on the
fly. See the 'Setting Preferences', and 'Encoding' sections, for more details.
Download Decode checkbox
This is the bottom box of the pair, and becomes active when you are connected to
a host. If it is checked, all files received will be decoded if a recognised encoding
format is found in their headers. You can check this box to change the setting of
the 'Decode' flag on the fly. See the Setting Preferences, and Encoding sections,
for more details.
<=-Transfer button
If you are connected to a host, and have selected one or more files or folders
from the Away folder, this will transfer these files into the directory listed in the
Home folder. Once all the files have been transferred, the Home folder will be
relisted to show the files that you have transferred. Any invalid directory, or file
names, will be changed if necessary to conform with the local file system.
Note: If you select a folder, the entire hierarchical contents of the folder will be
transferred, creating any new folders as necessary. Be careful, as you can easily
transfer more files than you realise!
Note: A check will be made to see that enough space is available for each file that
is transferred to the Home folder. If SAFE2 thinks that there is not enough space
to receive the file, you will be asked for confirmation of what to do next. If you are
resuming a file, this check may indicate there is not enough space, when you
know there is sufficient space for the download. In this case, proceed with
caution, or the transfer may fail!
Note: If you have automatic decoding checked, and an encoded file is seen, it will
be decoded if possible after it has been received. For a large file, this may take
some time, so be patient. If there is insufficient space to decode the file, or any
other checks fail during the decoding, the raw downloaded file will be left
untouched. The log file will report any files that were decoded, and show what
kind of decoding was used (see the section on decoding for further details).
19
New Folder button
Opens a dialog asking for the name for a new folder to be created within the
Away folder. If you enter an empty name, or an invalid name, no folder will be
created. If you want to transfer files into the new folder, you will need to first
open the folder by double clicking its entry.
New Name icon button
Opens a dialog that lets you change the name of a file or directory in the Away
folder, and then redraws the list.
Note: If you do not have access permissions to change the name, or the name you
give is not acceptable by the host, this function will fail.
Trash icon button
Will delete a file, files, or folders, from the Away folder. Confirmation will be
asked. Any enclosed hierarchical directories, and their contents will also be
deleted. If there are any locked files within a folder, then those files will not be
deleted, along with their enclosing folders. Read only folders cannot be deleted.
Note: Be careful, as you can easily delete a large number of files and directories
with this command.
Home Icon button
Will open the default directory that was first shown when you connected to the
current host.
Stop icon button
This is your panic button for emergencies! If for any reason, you wish to stop a
transfer, a host 'sticks', or you cannot get a host to respond, click the red button
to stop the current action. It may take a few clicks to stop, so be patient!
Note: Depending on exactly when the Stop icon is pressed, it may automatically
disconnect you from the host. At other times, it may ask if you wish to
disconnect. Reconnect to the host if you have not yet finished transferring files.
Connect/New Server/Disconnect button
This button will be named according to whether you are currently connected to a
host or not.
20
New Server - Opens a dialog asking for the access information to a host. You
should normally fill in all the fields, though the Name field is optional. If you
leave the User Name and Password fields empty, you must have already entered
valid entries for the default user name and password. See 'Set Default User' for
how to do that. The dialog will be primed with the details of the last server you
accessed.
Connect - Opens a dialog primed with details from the selected item in the
Favourites list.
Note: The entries you make here will be later used if you select 'Add Current to
Favourites'. The Name field will be used in that dialog, but if you have left it
empty, you will get a chance to enter a new one at that time.
Disconnect - Asks for confirmation, then closes your connection with the host,
displaying the Favourites list once more.
In Addition...
The Home folder
If you double click a file entry in the Home folder, it will send an IPC message
out to any NDAs that are listening, and might be able to handle the file. For
instance, Hermes™ will open any text files, and display their contents in an
editable window, and Balloon™ will open any ShrinkIt archives so you can
unpack them.
The Away folder
If you double click a file entry in the Away folder, it will open an Info window
showing the Filename, and Path on the host folder for that file. You will also see
the permissions flags for that file.
Note: If you have SideClick installed, you can copy a file name or names, or the
full paths, of entries from the active list to the Clipboard. In the same way, you
can also copy the file name or path from the File Info window. This can be useful
for sending names or paths to files in an email.
Note: If you hover over an un-named icon, you will see its function displayed.
21
Transfers
Transferring Files
The prime function of SAFE2 is to transfer files between the local computer and
a host computer by means of the FTP protocol. It can send either a single file, or
many files, depending on how many files or folders you select in the appropriate
folder listing.
If the filename of a received file is unacceptable to the home file system, it will be
automatically renamed, and you will be prompted to either accept the new name,
or to change it a new one. The log file will show the name of the original file, and
the new name it was saved under. With long filenames, or names that include
spaces, saving to an HFS partition may prove to be more suitable, as HFS is more
forgiving of long or unusual names.
If you wish to stop the transfer of a large file, click the red Stop button. As long
as you do not modify the file in any way, or you were not automatically encoding
or decoding, you should be able to resume its transfer later.
SAFE2 will attempt to set the 'file modified' date to that of the file on the host
server, respecting time zone differences. If the host server is observing a different
daylight time to you, this may result in a file with a one hour difference.
Note: If the Previous Directory entry is selected, it will be ignored.
Note: Marinetti can handle around 48 open ports at any one time. It can take
some seconds for a port to be cleared after it has been closed, so as a result, if
you are batch transferring a large amount of small files within a short time, you
may find there are times when you have to wait till a port is available. If this
happens, you will see a screen message telling you the transfer is waiting for a
free port.
22
Permissions
FTP follows the Unix structure for read and write permissions. Files in the away
window may be marked with an icon to the left of the file name to show if they
are read or write only, and though directories will normally show a directory
icon, they may show specific read and write only icons instead. Some files and
folders may even show a no access hour glass icon.
You cannot transfer a write only file from the Away folder, and you cannot
rename or delete a read only file. Both read only and write only directories may
be opened, and copied, but any files in a write only folder will be invisible, and
will not be copied. If you write files to a write only folder, they will not show in
the directory listing.
If you copy a folder from the away directory that has write only folders within,
you will not receive any files that they may contain.
Wherever possible, the home and away Transfer buttons will be dimmed, to
reflect the permissions of the target folder.
There are two main modes used to transfer files with FTP, Binary and ASCII:
Binary Mode
This will transfer the file. making an identical copy at the other end, and is the
default setting. Received files are saved locally as binary files (filetype = $06). This
method will always be used when the relevant encoding or decoding box is
checked.
Note: Local filetypes or auxtypes are not preserved on transfer to a host, and so
resource forks in local files will be lost. See 'Preparing files for Transfer', or the
'Encoding' section, for details on how to deal with such files.
ASCII Mode
If the 'Prefer ASCII mode for Text files' option has been set in the 'Preferences'
dialog, any text files that are sent will have their EOL (End Of Line) sequences
changed during the actual transfer:
CR => CR/LF pair
CR/LF => CR/LF pair
LF => CR/LF pair
23
If SAFE2 receives a file in ASCII mode, it will then strip any LFs, replacing them
with CRs if necessary, and then save as a text file (filetype $04). This conforms to
normal Apple II format, where a CR is used as an EOL marker.
When a host receives a file in ASCII mode, it will do a similar processing,
adjusting the CR/LF pair to its own requirements.
SAFE2 uses the suffix of files it sees on the host to determine whether it is a text
file or not. Unless you have invoked Force ASCII mode, you cannot force SAFE2
to consider a file to be a text file, so if necessary, you may need to post process a
file, changing its filetype, or editing and saving as a text file.
The text suffixes recognised by SAFE2 are these:
cgi, hqx, htm, html, java, php, php3, shtml, txt, uu and uue
Note: As the length of file that will be saved in ASCII mode will usually be
different to the size of the original file on the host, you will be unable to Resume
the transfer of text files.
Note: If a file has been transmitted or received in ASCII mode, its entry in the
Log file will show a bullet against its name.
Note: If you set Force ASCII for a Favourite entry, or invoke it by SideClick, then
this will force ALL files to be received in ASCII mode, not just text files.
Resume
Binary files that are only partially transferred may be resumed, if the host
supports this function. Most Unix hosts do allow resumption of a transfer.
Depending on the settings of the flags in the 'Preferences' dialog, this will either
take place automatically, or you will be prompted. See 'Setting Preferences' for
more details.
Be sure that you are resuming the transfer of the same file, as no checks are made
to see that it is the same file! The only check made is to see whether the source
file is longer than the target file that is being resumed.
Note: If you have the relevant encoding or decoding boxes checked, you will not
be able to resume the transfer of a file.
24
Synchronise Folder
The synchronise folder feature allows you to quickly replace files that are newer
than those in the currently selected folder. It will leave any 'orphan' files intact,
only change files that already exist in both folders, and will dig down into any
nested folders.
Checks are only made on the modifed date of the two files, the size of the files
being ignored. Older files will always be overwritten, and you will get no prompts
if a file name has to be changed to suit the IIgs file system.
As the IIgs does not report seconds for a file saved under GS/OS, the comparison
is made to the nearest minute. SAFE2 will attempt to make the comparison using
UTC time, to avoid problems over local time differences.
Select the direction you wish to synchronise, and if you have write permissions
on the host, check the 'Determine server time automatically' box. If you do not
check that box, you must enter the offset of the server from your time.
Click OK to start the synchronising of the folders. If you are keeping a Log file,
you can check the file for what actually happened, and which files were copied or
skipped.
25
Preparing files for Transfer
Only the data fork of a file may normally be transferred from a file in your home
folder, and filetypes and auxtypes are not preserved by an FTP transfer. If you
wish to transfer a forked file, either send it by using the automatic encoding
process, or alternatively, you can preserve its filetype and auxtype, by first
archiving the file or files using GSHK. Any archive files can then be transferred
as binary files, and can be stored on any kind of host system. During retrieval,
they can then be automatically decoded if the encoding method is recognised by
SAFE2, or after retrieval, they can then be unpacked back to their original
format.
There are many archiving formats, such as BINSCII, or MacBinary, that can
optionally be used to do the same kind of thing as GSHK.
You may wish to simplify filenames to suit the host that you are sending the files
to, though most Unix systems can accommodate filenames with all but the '/'
symbol.
Note: SAFE2 has an optional automatic encoding feature, that sends a file using
the AppleSingle format. This preserves both forks of a file, its filetype and
auxtype, and the creation and modification dates.
Encoding and Decoding
Because host libraries can only hold simple binary or text files, the local file
information, such as its native name, the creation and modification dates, file and
auxiliary types, and the resource fork, cannot usually be directly stored. The
AppleSingle encoding format preserves all this information in a flat file, that can
be stored on any system that can receive binary files. SAFE2 can optionally
encode every file it sends with this format. By this means, you can easily store or
send ProDOS or GS/OS files, and be able to recreate them in their original
format when they are subsequently downloaded.
Note: An '.as' suffix will be added to all files uploaded using AppleSingle
encoding.
As there are many other encoding formats that you might come across, SAFE2
can optionally automatically decode some other formats when you download
26
files. Some of these formats will preserve file information, and resource forks,
others will not. If you have checked the download decode box, then the decoding
process takes place automatically, examining each file for a recognised header. If
successful, the Log File will add a message ' x Decoded as: ', showing the name
that the decoded file was saved under. The 'x' as shown in the log file, is a number
that refers to the encoding format that was found:
1
2
3
4
5
6
7
Encoding type Library format Preserved data
AppleSingle BinSCII Binary II BinHEX 4.0 MacBinary UUencode Base64 (MIME) Binary file Text file Binary file Text file Binary file Text file
Text file Dates filetypes forks
Dates filetypes
Dates filetypes
Dates filetypes forks
Dates filetypes forks
Dates filetypes forks
Note: SAFE2 will attempt to save the decoded file under any native name it finds
within the encoding. If this name is unsuitable, or already exists, it will be
changed to a unique name compatible with the local file system. By downloading
files to an HFS volume, it may mean that longer, or more obscure filenames, can
be preserved.
Note: A Binary II encoded file can hold multiple files, and can also hold
subdirectory information. If necessary, any required subdirectories will be
created by SAFE2, and the decoded files placed in their correct directory. Check
the Log File to see any directories that were created, and which files were placed
where.
Note: Files are decoded after downloading, and so may take time to decode
depending on their size. If the decoding fails for any reason, the raw file will be
left exactly as it was downloaded.
Note: You cannot resume the sending or receiving of files if the relevant box for
upload encoding, or download decoding, has been checked.
Note: Multiple segmented part files, for some of the encoding formats, cannot be
decoded, as only single part files are supported by SAFE2. These files can be
generated by programs such as Spectrum, so if you are using Spectrum to encode
files, make sure that it has been set to produce a single output file, rather than
multiple parts.
27
Managing Favourites
You are not expected to remember all the URLs, names, and passwords, used to
access your favourite hosts, and as you will want to minimise the use of the
manual Connect dialog, SAFE2 lets you keep all these details as a 'Favourites'
entry.
Any Favourites you have defined, will show in the Away list, and by double
clicking an entry, you can quickly access and log into that host.
When you select Edit Favourites from the Settings Menu, a window opens to
show a list of all your current Favourites.
You can enter new entries, delete old ones, move entries within the list, sort the
list, and of course edit an entry. Holding down the Option key while clicking
‘New’, will copy the settings from a selected item in the list.
Note: Double clicking an item in Edit Favourites will open its edit window.
The New or Edit window has various fields:
Sorting - Alphabetically sorts the entries. There is no 'Undo', so be careful!
28
Move - To Move an entry, first select the entry you want to move, and click the
Move button. Move with the Arrow keys, and press Return to ‘fix’ it in its new
position, or Double-click where you want to move the item to.
Editing Entries:
Name - This is only used locally to identify the entry in the list window. If you
check the box by the Favourite Name, it will auto-open that server at boot.
FTP Host - This must have a valid entry to an FTP host, for example,
ftp.asimov.com. No checks are made to see if this name is valid. It can be either a
dotted address, or a full URL.
User Name - This is the name that this hosts knows you by. If you leave this field
empty, the default username will be used instead.
Password - This is the password linked to your User Name. If the Name field was
left empty, the default password will be used instead.
Note: For your security, passwords are never shown in the clear within SAFE2,
and are also saved in an encrypted format within the SAFE2.Favs file.
Directory - This should point to the directory you wish to first access when you
have logged in to a host. Most times this will be the default directory '/', and so
this is set for you with each new entry.
Downloads - If a folder path is supplied, then the related Home folder will be
opened when the Favourite is selected. This field can be left empty.
PASV Mode - If the host, or your firewall, requires PASV Mode, click this
checkbox. See 'Setting Preferences' for more details.
Force ASCII - This forces all downloads to be saved as Text files. This overrides
the Prefer ASCII Mode, which only applies to files with standard suffixes.
Keep Alive - By setting a value in this box, SAFE2 will send regular prompts to
the host in an attempt to stop it from timing out and disconnecting you. This may
or may not work, depending on how the host has been configured. The value you
enter will be multiplied by 30 to give the seconds delay between prompts. A value
of 0 will give no prompts.
29
Once you have completed editing your Favourites, click the 'Close' button to save
your changes and exit.
Use Balloon - If Balloon™ 2.0 is installed, this checkbox will display, and let you
select whether for this server, valid files will be unshrunk as they are received.
Note - If you have SideClick installed, you will be able to change the state of the
Force ASCII and PASV mode flags by right-clicking.
Setting Preferences
Here you can customise the behaviour of SAFE2:
Prefer ASCII Mode for Text files - This turns on a flag which will automatically
process text files during transmission or after receiving. See Transferring Files for
details of how this is done.
Note: If this flag is set, you will not be able to resume the transfer of text files.
Prefer passive mode (PASV) - FTP transfers involve opening two ports, a
command port and a data port. The command port (21) is used to handle all
command transactions, and remains open during the entire session to a host. A
30
random port is then opened for the data channel, and this is closed down as soon
as data has been transferred.
SAFE2 can either request a data port from the host (PASV mode), or tell the host
which port on your IIgs to use (Active port). SAFE2 uses Active ports within the
range 32767-65534. If a port fails to open during a transfer, SAFE will
automatically disconnect, and display the Favourites list once more. Check the
Log file to see what occurred, and if necessary, correct the problem before
reconnecting and trying again. Note: Even though you have logged into a host, an Active or a Passive port may
fail to open if you have a Firewall that blocks these ports. If you get any
connection problems, first check that your Firewall is open for port 21
(Command Port), and the range 32767-65534 (Data Ports).
Some host firewalls are fussy about which ports they let open, and may require
you to use Active mode rather than Passive (PASV) mode. Your own local firewall,
in a router for instance, may also be fussy, and require you to specifically open
ports within the range that SAFE2 uses.
If you have set PASV mode for a host, and this is rejected, if possible it will fall
back to use Active mode for that session.
Setting this PASV flag only changes the prompt for the PASV checkbox in the
Connect and New Favourites dialog. It does not actually change the behaviour of
SAFE2.
Note: If you are using the Sweet16 emulator to run SAFE2, as Active Ports are
not supported, the PASV checkboxes will all show as set, and be inactive.
Hang up on Disconnect - If you are connecting to the Internet through a LAN,
or an otherwise 'always on' connection, you will probably have told Marinetti to
connect at boot. In that case you will not wish SAFE2 to disconnect TCP/IP. If
however you are using a dialup connection, you will wish to disconnect TCP/IP
every time you disconnect from a host, to save possible phone charges. Checking
this box means that SAFE2 will always disconnect TCP/IP on disconnect.
31
Keep Logfile - SAFE2 will always create and open a log file. By checking this
box, SAFE2 will then keep it up to date with a record of all file transfers and
other actions.
When a file exists - The popup menu may be set to four options:
Ask
Overwrite
Resume
Skip
Ask - When a file name already exists, a dialog opens asking whether you wish to
Overwrite, Resume or Skip the file. Alternatively, you can enter a new name and
then click OK.
Overwrite - When a file name already exists, the existing file will be deleted, and
the complete file will be transmitted or received once more.
Resume - The file will be resumed if possible. If the transmitting size is equal or
smaller than the target file, no action will be taken.
Note: If you are transferring a text file in ASCII mode, or you have the relevant
'Encode' or 'Decode' box checked, the Resume option will be dimmed in the
dialog, and the file can only be overwritten.
Note: When sending a file, if the host cannot resume transmission of files, then
the target file will automatically be overwritten.
Skip - No action will be taken, and the file will be ignored if it has the same name
as an existing file
32
Decode and Encode files when:
'Receiving Files'
'Sending Files'
These two settings control the default settings at startup, of the upload
'Encoding' and download 'Decoding' check boxes on the main screen. You can
subsequently override these default settings at any time from the main window.
Default Download Folder - The Default Download Folder checkbox has a dual
purpose. If checked, this will be the default Home folder at boot, and if not
otherwise specified, will be the default Home folder whenever a server is
connected. If the checkbox is not checked, then the existing Home folder will be
displayed. Either enter the path directly, or click the 'Choose' button, and
navigate to the target folder. Press Select to confirm your choice.
Note: This folder setting will be overridden if a download folder has been set in a
Favourite entry, and that entry used to go online.
NIST - This is the address of the time server that SAFE2 uses to set the system
clock, and to determine the correct time for the Synchronise folder command.
Only change this address if this server is no longer available. You can read more
about NIST, and get a link to other time servers, on this web page:
http://www.nist.gov/pml/div688/grp40/its.cfm
33
Log File
As a default, the Log File keeps a record of all file transfers and other online
actions. It also reports any failures that may occur.
Each month, any existing log file will be renamed to show the month and year it
was created, and a new file will be opened. You may want to periodically clean the
SAFE2.Data folder of any old log files you no longer require.
If it does not exist, a log file will always be created, but you can optionally tell it
not to update itself from within the Preferences dialog.
When you view the log file, it will always scroll to the bottom, so you will see the
most recent events displayed.
Optionally, you can delete the current log file while viewing it. This will cause a
new blank file to be created, and the original contents will be lost.
This is what a typical Log File may contain, and a breakdown of what it is showing:
*** SAFE2 Logfile for Dec 2006 ***
1)
2)
3)
4)
Session Startup at 3/12/06 6:37:44 pm
Connecting to: www.a2central.com <75.35.59.6>
Home Directory: /
Received file: A long name that does not fit ProDOS.txt
34
5) File saved as: A.very...OS.txt
6) Sent file: A.File
7) Opening Directory: A.Folder
8) Sent file: A.File
9) Back to Directory: /Top/Files/Documents
10) Sent encoded file: A.File.as
11) Received file: A.File.as
12) 1 Decoded as: A.File
13) Deleting host file: A.File.as
14) Directory created: New.Folder
15) Deleting host file: A long name that does not fit ProDOS.txt
16) Renaming file: Another.File
17) To: New.Name.File
18) File Transfer stopped: A.Second.shk
19) Appended file: A.Second.shk
20) File Transfer stopped: A.Second.shk
21) Resumed file: A.Second.shk
22) Disconnecting from: www.a2central.com <75.35.59.6>
Analysis:
Title: Showing the date the Log File was created.
1: Each time you connect to a new host, a session time stamp is written.
2: Shows the URL and dotted address of the host that you are connecting to.
3: Displays the Home directory at login. Often this will be just '/'.
4: A file was received from the host.
5: The file was renamed to fit the local file system.
6: A file was sent to the host.
7: A folder was opened or created on the host.
8: A file was sent to the host, and saved in the directory from Line 7.
9: The target path was moved back one directory.
10: A file was sent encoded as AppleSingle.
11: A file was received from the host.
12: The file was decoded from AppleSingle (1).
13: A file was deleted on the host.
14: A new directory was manually created on the host.
15: Another file was deleted on the host.
16: A file on the host was renamed from 'Another.File'...
17: ...to 'New.Name.File'.
18: A file transfer was stopped by the red button.
19: The transfer was resumed to the host (Appended).
20: A file transfer was stopped by the red button.
21: The transfer was resumed from the host (Resumed).
22: The host was disconnected, and a session time stamp was written.
35
Balloon™ Support
Balloon™ is an NDA that gives ShrinkIt file support to the IIgs desktop. SAFE2
supports Balloon™ if it is installed and active. You can turn on the Balloon
unshrink support, either by clicking the Balloon icon on the main screen, or presetting its state in a server connect dialog, or a favourite entry.
When Balloon™ is installed, and you are online, the Balloon icon will show red
while inactive, and green if active. While active, if a valid file is downloaded, it will
be added to a queue. When all the transfers are finished, if there are more than
three files in the queue, you will be presented with a list of the files. Choose the
ones you want Balloon™ to unshrink, and click the Unshrink button. You will
then be presented with a Balloon™ dialog for each file in turn. If three or less
valid files have been downloaded, they will be passed to Balloon™ directly.
Before you use the Balloon support feature, you need to open the Balloon™
NDA, and make sure that you have set its Preferences correctly. For instance, a
BXY file has a wrapper, and so will not be unshrunk, unless the ‘Look in Files
(Slower)’ option is checked.
Note: If the Decode option is active, and it results in extracted ShrinkIt files,
these files will not be added to the queue.
Note: The Balloon support feature is not active while Synchronising files or
folders.
36
Extras
Help
Online Help is available if you have installed the optional !Help! desk accessory,
and its Help files, to the Desk.Accs folder.
Problems
Hopefully you will have none, but if you do, and they cannot be answered by
reading these notes, please contact me on:
[email protected]
Other information
Check for the latest version of Marinetti:
http://www.apple2.org/marinetti/
If you do not already know about Spectrum™, please drop by my home pages,
and read more. Apart from all the other wonderful things it does, Spectrum™
offers many useful tools for processing files, such as post processing text files that
you have received, that may have obstinate formatting.
Spectrum™ is now Freeware, and amongst my other applications, is now available
from my web site:
http://homepage.mac.com/speccie/
Someone once said to me, 'Spectrum™ does everything!'
SAFE2 © 2006-14 Ewen Wannop
37

Similar documents

×

Report this document