
                              ====================
                              !Split  Version 2.12
                              ====================

 ****************************** Copyright Notice ******************************
 *                                                                            *
 *   This application is copyright Adam Hamilton.                             *
 *   Permission to use, copy, and distribute !Split, for non-commercial       *
 *   purposes, is hereby granted, provided:-                                  *
 *                                                                            *
 *      No charge is made other than to cover the cost of the medium.        *
 *                                                                            *
 *      All files and documents are included in the distribution unaltered.  *
 *                                                                            *
 *   You may upload this software to a Bulletin Board, or include it in       *
 *   your Public Domain library. If you do this, please try and let me        *
 *   know, so I can keep you up to date with any future changes.              *
 *   The authors permission must be obtained before this application is       *
 *   included on any magazine disk, or with any other software.               *
 *                                                                            *
 *   You may not sell this software, or use it otherwise for personal gain.   *
 *                                                                            *
 *   If you change any part of this software, you must obtain permission      *
 *   from the author, before distribution.                                    *
 *                                                                            *
 *   This program is supplied 'as is' with no guarantee of its suitability    *
 *   for any purpose. I will not be held responsible for any damage arising   *
 *   from the use or misuse of this software.                                 *
 *                                                                            *
 *   I reserve the right to change these terms and conditions at any time.    *
 *                                                                            *
 ******************************************************************************


Contacting The Author
~~~~~~~~~~~~~~~~~~~~~

   Bug reports, and comments may be sent to me, the author,
   at this address :-

             Adam Hamilton,
   E-Mail:   split@qualsar.co.uk


================================================================================

1  Introduction

   !Split was written to ease the transportation of large files from one
   computer to another. No attempt to compress the file is made, as it is
   assumed this has already been done. !Split will split a file into a number
   of smaller files, and will join them again when required.



2  How To Use !Split

   !Split can be started either by running the application directly or via
   a double click on a split file (see section 2.3, 'Joining Files').


 2.1  The iconbar menu

      Pressing the menu button on the iconbar icon will display a menu.

      Info              This displays information about the program.

      Autoload          When joining files, if this option is selected, !Split
                        will automatically attempt to locate the next part to
                        join.

      Faster            If selected, the multi-tasking window will not be
                        updated with bytes read and written, making the
                        operation faster. A tick will be displayed when this
                        option is selected.

      Single Task       This option will toggle between single and
                        multi-tasking. A tick will be displayed when this option
                        is selected.

      Quit              This will quit the program.


      The default action of Autoload, Faster, and Single Task options may be
      changed (see section 3, 'Customizing').


 2.2  Splitting Files

      The split window can be displayed either by clicking on the iconbar icon
      with select, or by dragging a file to the iconbar icon. Figure 1 shows an
      example of the split window. Please note, you may open and close filer
      windows, or change floppy disks between saving.


                 ---------------------------------------------
                |             -----------------------------   |
                |    Source  |s::IDEDisc5.$.Music.RaveAlert|  |
                |             -----------------------------   |
                |             ----------      -               |
                |  Filesize  |      1423| K  | |              |
                |             ----------      -               |
                |             ----------      -               |
                |  Filename  | RaveAler |    || Single save  |
                |             ----------      -               |
                |        -------            -------           |
                |       | Close |          | Split |          |
                |        -------            -------           |
                 ---------------------------------------------

                           Figure 1: Split window


  2.2.1  Source

         Enter the filename for the file you want to split, or simply drag
         the file to the split window. If you drag, the Filename field will
         automatically get filled in, although you can still change it if you
         wish.


  2.2.2  Filename

         This is the 'base' filename to be used for each part the file is split
         into. Using the example above, the base name is RaveAler so the parts
         will be named RaveAler01, RaveAler02, ... etc.


  2.2.3  Filesize

         This is the maximum file size in K (1024 bytes), that you want each
         part to be saved as. You may either type the size into the text icon,
         or press the select or menu mouse buttons on the menu icon opposite.
         You may then choose from one of the sizes in the menu. The default
         size and the contents of the menu can be customized (see section 3,
         'Customizing').


  2.2.4  Single save

         If this option is set, !Split will automatically save all parts to the
         same directory, only one drag is needed. This option may be switched
         on or off during saving. The default setting for this option may be
         customized (see section 3, 'Customizing').


  2.2.5  Close

         Pressing this button will close the split window. If splitting has
         started, closing the split window will not affect this process.


  2.2.6  Split

         Pressing Split will open the `save as' window, shown in figure 2 below,
         (if all the parameters have been set correctly), prompting you to drag
         the icon to a directory window. If the Single Task option has not been
         selected from the iconbar menu, then a transfer window will be
         displayed and the splitting process will begin (see section 2.4,
         'The Transfer Window'). If you only want to save certain parts, then
         use the Skip button to miss out the current part.


                          -------------------------
                         |          -----          |
                         |         |     |         |
                         |         |     |         |
                         |          -----          |
                         |      -------------      |
                         |     | RaveAler01  |     |
                         |      -------------      |
                         |  --------    --------   |
                         | | Cancel |  |  Skip  |  |
                         |  --------    --------   |
                          -------------------------

                           Figure 2: Saveas window


 2.3  Joining Files

      The join window can be opened either by clicking on the iconbar icon with
      adjust, double clicking or dragging to the iconbar icon, a file of type
      'Split'. If you opened the window with the adjust mouse button, you must
      double click or drag the first file to the join window. If you maximize
      the join window you will see some short hints to help you along. Figure 3
      shows an example of the join window.


           -----------------------------------------------------------
          |   Save as               |   Info                          |
          |          -----          |                                 |
          |         |     |         |  Part 1 of 2.                   |
          |         |     |         |  Drag file to directory window. |
          |          -----          |                                 |
          |      -------------      |                                 |
          |     |  RaveAlert  |     |                                 |
          |      -------------      |                                 |
          |  --------    --------   |  Using buffer size of 192K      |
          | | Cancel |  |  Save  |  |                                 |
          |  --------    --------   |                                 |
           -----------------------------------------------------------

                            Figure 3: Join window


      Once !Split has the first part of the file to join, you need to tell it
      where to save the joined file. To do this, simply drag the file icon to
      the directory where you want it saved, or type the path into the text icon
      and press Save. Pressing Save without a full path in the text icon, will
      save the file in the current directory.

      If the Autoload option is on, !Split will automatically look for the next
      part to join. If it is found, joining will continue, otherwise joining
      will be suspended and you will need to either double click on the next
      part (filetyped as 'Split'), or drag it to the join window or the iconbar
      icon.

      If single tasking is not enabled, the transfer window will be displayed
      (see section 2.4, 'The Transfer Window').

      If Cancel is pressed, joining is aborted and the window closes.


 2.4  The Transfer Window

      The transfer window is displayed when splitting or joining has started
      and multi-tasking is enabled. Figure 4 shows an example of the transfer
      window.


                 -------------------------------------------
                |   -------------------------------------   |
                |  |               Reading               |  |
                |  |sc5.$.!C.Source.Split.test.RaveAler01|  |
                |   -------------------------------------   |
                |               589824 bytes read           |
                |               458752 bytes written        |
                |  -------   --------   --------   -------  |
                | | Abort | | Faster | | S-Task | | Pause | |
                |  -------   --------   --------   -------  |
                 -------------------------------------------

                          Figure 4: Transfer window


      The transfer window shows what the program is doing and on what file, it
      also shows the number of bytes read and written. The function of the
      buttons are outlined below:-

      Abort             This will abort the operation, and close the window.

      Faster/Slower     This will disable/enable the display of information in
                        the window, resulting in slightly faster operation. This
                        lasts for the duration of the current file operation.

      S-Task            This will put the program into single task mode for the
                        duration of this file operation only.

      Pause/Continue    This will pause/resume the transfer operation.


      Please note, once in single task mode, control is removed from the
      transfer window.



3  Customizing

   !Split may be customized is several ways.


 3.1  Changing the buffer size

      The buffer size used to temporarily store data can be changed (this will
      slightly affect the speed of the program). To do this, open the
      application directory by holding down the Shift key and double clicking on
      the !Split icon. Once inside, load the !Run file into your favourite text
      editor.

      To change the maximum buffer size, increase or decrease the value of the
      -max option on the WimpSlot command. For example:-

      WimpSlot -min 96k -max 640k

      Please do not change the -min size.


 3.2  Iconbar menu

      The default status of the Autoload, Faster, and Single Task options in the
      iconbar menu may be set. To do this, load the !Run file into a text editor
      (as above), then add or remove the following commands in the line
      beginning with: Run <Split$Dir>.!RunImage

      -autoload         This will default the Autoload option to on.

      -faster           This will default the Faster option to on.

      -singletask       This will default the Single Task option to on.


      For example, if I want !Split to start up with only the Faster option
      selected, I would have the following line:-

      Run <Split$Dir>.!RunImage -faster %*0


      Please note, as the Faster and Single Task options cannot be on at the
      same time, -singletask would take precedence.


 3.3  Single save

      The default status of the Single save button in the split window may be
      set. Edit the !Run file as above and add or remove -singlesave. For
      example, to have single save on, your Run command may now look like this:-

      Run <Split$Dir>.!RunImage -faster -singlesave %*0


 3.4  Filesize

      To set the default filesize, edit the !Run file as above and add the
      following option to the Run command:-

      -filesize n       Where n is the filesize in K (1024 bytes).


      For example, your Run command may now look like this:-

      Run <Split$Dir>.!RunImage -faster -singlesave -filesize 713 %*0


      The size is now suitable for saving to double density DOS formatted floppy
      disks.


 3.5  Filesize menu

      The filesize menu may also be customized. To do this, open the Resources
      directory, and load the SizeMenu file into a text editor. The file is made
      up of two columns, the first is file size in Kbytes, the second (which is
      optional) is the text which will appear in the filesize menu. If only the
      file size number is used, then that number will appear in the menu.

      The next time you start !Split, it should read in your new menu.



4  History

   Versions 1.xx are command line versions, which are supported along side the
   desktop versions (2.00 and greater).

    Version 1.00-1.08  These were the original command line versions compiled
                        on several different computers.

    Version 1.10       This version has a new file format, a header is put at
                        the beginning of each part, and is used to join files in
                        the correct order. This version is compatible with the
                        desktop version (2.00 and greater).

    Version 1.11       Slightly increased memory allocation for filenames, and
                        added a small check needed for DEC Ultrix compilers.

    Version 1.12       Added -interactive option to allow direct reading and
                        writing of floppy disks. This option enables different
                        paths to be given for each part, removing the need, for
                        example, to load all the parts onto the hard disk before
                        joining.

    Version 1.12c      Supports official Acorn filetype.

    Version 1.13       Modified the Acorn specific bits to speed up file
                        access. Also tidied and commented the code a lot more.
                        NOTE: The only executables changed from version 1.12
                        are the Acorn ones, therefore I have only compiled
                        this version for these machines.



    Version 2.00       First desktop version.

    Version 2.01       Added ability to open join window with the Adjust
                        button, and to drag files to the window. This made it
                        easier to start the joining procedure if the files
                        aren't filetyped as 'Split'. Fixed bug with ArcFS image
                        file system doesn't complain about archives any more.

    Version 2.02       Added filesize menu, fixed a few small bugs.

    Version 2.10       Big jump from 2.02 to 2.10 because I decided to
                        completely re-write the program from scratch without the
                        use of RISC_OSLib functions. This has made the program
                        easier to write, control, modify, and has made the code
                        smaller and it also runs faster.

    Version 2.11       Added multi-tasking option. Fixed a few small bugs.

    Version 2.11c      Fixed menu item height. As of this version, !Split uses
                        an official Acorn filetype.

    Version 2.12       Speeded up file operations. Increased the amount of data
                        transferred each WIMP Poll. More meaningful text in the
                        size menu. Added ability to skip parts when splitting.
                        New option to autoload join parts.



5  Files supplied

   The following files are supplied inside the !Split application directory.

   !Boot
   !Help                  This file.
   HelpPS                 PostScript version of this file.
   !Run
   !RunImage              Main program.
   !Sprites, !Sprites22
   Resources (directory)  Contains ...
     SizeMenu             Definition of the filesize menu (see section 3,
                          'Customizing').
     Toggle3D             Toggles the state of the 3D bit in CMOS RAM.
     ToggleDRAG           Toggles the state of solid dragging bit in CMOS RAM.
     Template2D           2D window templates.
     Template3D           3D window templates, RiscOS 3 or greater.

   The program will automatically select the correct templates file to use.



6  Acknowledgments

   I would like to thank Andrew Sellors for his suggestions and help in testing
   this application.

   Thanks to Sergio Monesi for his suggestion on speeding up file operations.

================================================================================
