   !DataWay  Bernard Veasey 1998-2020 version 0.31 - Manual version 0.14
                         >>> G I F T W A R E <<<
             see Giftware section near the end of this file
                      Email: bernard@bapfish.org.uk
                     Web: http://www.bapfish.org.uk/


MAIN FEATURES
-------------
  A straightforward database.
  A Search facility.
  A Sort facility - including a 'Surname' sort.
  Easy transfer of data to Ovation Pro (>=2.46) in a format that its
   'Auto-linked' frames or 'Mail-Merge' facilities can understand.
  Easy transfer of data to Impression Publisher in a format that its
   'Framethrow' or 'Mail-Merge' facilities can understand.
  Easy export of data in CSV or TEXT files.
  Selected fields can be exported.
  'Searched for' or 'All' records can be exported.
  A Record or Field can be easily dragged out of 'DataWay'.
  An Internet Web Address field can be easily sent to your favourite
   RISC OS browser such as !NetSurf, !Oregano, !WebsterXL, !Browse or
   !Fresco etc...
  An Email address field can be actioned.
  A RISC OS filer object(s) can be accessed or run from a record.
  A Phone Number field can be tone dialled.
  A Post Code field can be sent to RiscOSM to open a map of its position.
  Imports CSV files.
  Merging of 'DataWay' files.


INTRODUCTION
------------
If you are looking for a low cost, easy to use database, 'DataWay' is the
database for you.  It may not have some of the facilites of databases costing
over a hundred pounds or more but it is probably easier to use as a result.

Just enter your data and save your work to disc.

It is assumed that you know the usual RISC OS conventions.
eg. The Mouse Keys - 'select' Left Mouse key.
                     'menu'   Middle Mouse key.
                     'adjust' Right Mouse key.

If the 'adjust' mouse button is clicked on any of the 'DataWay' menu items,
the menu will remain open, as all RISC OS programs should do.


INSTALLING !DATAWAY
-------------------
Just drag it to a drive directory viewer window.

To run, just double-click your installed version.


IN THE MAIN DATAWAY WINDOW
--------------------------
Clicking on the 'DataWay' icon bar icon opens the main window.

Just enter suitable headings and enter or edit your data in the white area.

 _
 ^           'GOTO' last record.


'up' arrow    Next record.

              With SHIFT - forward 10 records.

     'adjust' does opposite.


'down' arrow  Previous record.

              With SHIFT - back 10 records.

     'adjust' does opposite.

 v
 -            'GOTO' first record.

->>           Open the 'GOTO' window.


Information   The 'DataWay' information panel shows:

              <n1>/<n2> - <n3>

        <n1>  After a Search that finds more than one record, this shows the
              current Found Record number.
        <n2>  After a Search that finds more than one record, this shows the
              total number of records that have been found that match the
              search criteria.
        <n3>  The current main Record number.

              This information panel also displays other relevant messages.

Sort          Sorts all the records in alphabetical order.
(A-Z)         Clicking the 'Sort' icon opens the 'Sort' window.
              Choose the field you want to sort by.
              Choose the type of sort.
               o Normal - does a normal A-Z sort.
               o Surname - does an A-Z sort on the last word of the
                           chosen field.
              Choose 'Case Insensitive' if required.
              Sorting with 'Case Insensitive' off sorts upper-case letters
              first, followed by lower-case.

Search        After clicking, enter your Search criteria in any of the fields
              and press RETURN or F4.  Alternatively, clicking the 'Search'
              icon again will initiate the actual search as well as the
              RETURN key. The Search will be acted upon the field you
              entered the Search criteria on.  Searching is case-insensitive.
              
              Use the arrow icons to view the records you have found.
              
              If your search finds more than one record, the 'Subset' icon
              becomes highlighted and the 'DataWay' information panel
              displays the quantity of records that your search has found,
              together with the currently viewed found record number.
              eg. '3/8 - 120'  means that your search has found eight records
              that match your search criteria and that you are viewing the
              third record in the subset.  The 120 shows the matching main
              database record number.  Clicking the 'Subset' icon toggles
              between the subset and the main database.

              If SHIFT is held down when the 'Search' icon is clicked, a
              search of all fields will be initiated.

     'adjust' Cancels and resets the previous 'Search'.

  All         When doing a 'Search', if this icon is set 'on', a search of
              all fields will be initiated rather than just the current
              field.

  Subset      After a Search where more than one record has been found, this
  icon        icon becomes active showing that you can now view a subset of
              records by using the arrow icons.  Clicking this icon toggles
              between the subset and the main database and if 'adjust' is
              clicked, it additionally goes to the first record of the subset
              or database.


Delete        Delete the current record.  You will be asked to confirm this
(Red -)       if the 'Warnings' option is set in the 'DataWay' Options
              window.  See also CTRL X and CTRL V

     'adjust' Nothing.

Add           Add a record - Type in the data and press RETURN or the up and
(Big +)       down arrows.

     'adjust' Cancels.


Replicate     Replicate the current record - This makes a copy of the current
(Small +)     record and places it at the end of all the records.

     'adjust' Nothing.


Save          Open the 'Save' window.
(disc)

     'adjust' Quick Save (if the pathname has been previously setup).


Export        Open the 'Export' window.
(disc/text)

     'adjust' Nothing.


SHIFT         ... A 'Field' opens the 'Field' window ready for editing the
Clicking      field details.

              ... A Card heading opens the 'Field' window ready for editing
              the card heading.


Dragging      A 'Record' can be dragged out of 'DataWay' into most other
              applications or a directory viewer.  Just drag the 'white'
              area.  The number of fields used is as set in the 'Export'
              save window.  Remember that the 'live' part of the RISC OS
              'I' mouse pointer is at the top left of the 'I' symbol -
              except on RISC OS Select when it is in the centre.

              A 'Field' can be dragged out of 'DataWay' into most other
              applications or a directory viewer.  Just drag the field
              heading name - or its icon - of the required field.
              Additionally, 'Fields' can be moved to any of the other
              'DataWay' fields within the same record by dragging a heading
              name - or its icon - to the required field.  If SHIFT is held
              down it will be copied.  If ALT is held down it will be added
              to the destination field.

              Dragging a filer object to a 'Filer_Run' field enters its
              pathname into that field.
              
              Dragging a 'URI' (&F91) or 'URL' (&B28) file to a DataWay 'Web'
              field enters its URL into that field.  If a text file is
              dragged to a 'Web' field, the contents of the first line is
              entered into that field.

              Dragging a NetSurf web address line to a DataWay 'Web' field
              enters its address into that field.

Double
Clicking      ... A field heading or its icon will do:

              o 'Text'      - Open the 'Notes' window.
                   'adjust' - Close the 'Notes' window.
              o 'Phone'     - Tone dial
              o 'Web'       - URIdispatch <url> - Send a web address to
                              Acorn's !Browse application.
              o 'Email'     - URIdispatch mailto:<email address> - Send an
                              Email address to your Email program if your
                              'mailto:' facility is setup correctly.
              o 'Filer_Run' - Filer_Run a Filer object (Files/Directories)
              o 'RiscOSM'   - Send a UK post code to open a map in RiscOSM.
              o 'Date'      - View today's date.
                            - with SHIFT - Enter todays date.
              o 'Money'     - <nothing currently>
              o 'Number'    - <nothing currently>

              depending on what field type is set.


MAIN WINDOW MENU
----------------
Info          Opens the DataWay 'About this file' information window.

Save          Save the current data into a 'DataWay' file.

Export        Export 'all' or a searched for 'selection' of records.

              To revert to ALL records click 'adjust' on the 'Search' icon.

              Choose the fields you want to export by clicking on the
              field icons.

              o 'Auto-Link' - Export into a format that Ovation Pro
                 auto-linked frames can understand.
                 
                 Just drop the icon on the first of a set of Ovation Pro
                 auto-linked frames or just save to a directory viewer.
              
              o 'CSV' - Export into a CSV format file including field
                 headings.

              o 'Text' - Export into a plain text file and if the 'Omit blank
                 field' option is on, blank fields will be omitted and a
                 blank line will be inserted between records.

              o 'Impression' - Export into a format that Impression
                 Publisher's 'Framethrow' facility can understand.


Heading       Enter the database Heading.
or
Field         Enter a Field Heading etc.

Password      Enter a password to protect your data.  A password can be saved
              with each individual 'DataWay' file.  If you want to revert to
              not having a password, enter your current password in 'Old' and
              just press RETURN on a blank 'New'.


IN THE FIELD WINDOW
-------------------
Name          Enter the name you want for the field you clicked on.

Type          Choose the field type you require.

              o 'Text'      - for plain text.
              o 'Phone'     - Tone dial your data
              o 'Web'       - URIdispatch <url>
                           or Send a URL Message to a Web Browser.
              o 'Email'     - URIdispatch mailto:<email address>
              o 'Filer_Run' - Filer_Run a Filer object (Files/Directories)
              o 'RiscOSM'   - Send a UK post code to open a map in RiscOSM.
              o 'Date'      - for dates.
              o 'Money'     - Converts to 2 decimal places.
              o 'Number'    - for numbers.

Formula       This can action a 'formula' on other fields with a numerical
              content.
          eg. <f2>*1.175          Gives a VAT inclusive price to field 2
              <f2>*1.175+0.00001  <ditto> but rounds half p's up.
              <f2>+<f3>+<f5>      Adds the contents of fields 2, 3 and 5

              A field descriptor can either be entered manually in the form
              <f1> for field one or the field heading icon from the main
              'DataWay' window can be dragged into the 'Formula' icon to
              enter the field descriptor.

              The usual arithmetical symbols apply.
              eg. * is multiply, - is minus, + is plus and / is divide.

              It currently gives the result to two decimal places.

              This 'formula' feature is only in its infancy at the moment and
              is liable to change and improve in the future.

Cancel        Cancel the operation.

OK            Proceed with your choices.  If the 'adjust' mouse button is
              clicked the 'Field' window remains open.  A field icon is only
              displayed in the main 'DataWay' window if there is a field
              heading.

When the 'DataWay' Field window is open, clicking on any of the data fields
or heading in the main window will change to that particular field within the
'DataWay' Field window.


IN THE SORT WINDOW
------------------
Name          Choose the name of the field you want to sort by.

Type          Choose the type of sort.
              o Normal - does a normal A-Z sort.
              o Surname - does an A-Z sort on the last word of the chosen
                field.

Tick box      'Case Insensitive' option on/off.

Cancel        Cancel the operation.

OK            Activates sort on your chosen criteria.  If the 'adjust' mouse
              button is clicked the 'Sort' window remains open.

The 'Sort' details are stored within a 'DataWay' file, so each file can have
its own sort criteria loaded automatically when 'DataWay files are loaded.


ICON BAR MENU
-------------
Info          About this program.

New           Clears all the current records and headings leaving a NEW blank
              window ready for starting a 'new' database.

Options       Opens 'Options' window.

Quit          Quit this Application.


THE NOTES WINDOW
----------------
This is opened by double-clicking any 'text' field heading with 'select' and
closed by double-clicking with 'adjust'.  It contains the contents of the
field that has been clicked.  This is useful for displaying a field that
can't be totally seen in the main 'DataWay' window.  The current state of
whether the window is open or not and the field it relates to is saved with
each 'DataWay' file.


THE OPTIONS WINDOW
------------------
CSV Import - Headings       If set, imported CSV files must include
                            headings in the first line.

Warnings                    If set, you will be warned when:
                            o  Deleting a Record.

Omit blank field - Export   If set, when exporting 'Auto-link', 'Text', and
                           'Impression' formats, any blank fields will be
                            omitted.

                            If not set, any blank fields will be preserved
                            and there will be no space line between records
                            when using 'Text' format.

OK            Proceed without saving.
Cancel        Cancel.
Save          Saves the current Options as the default.


DATAWAY FILE OPTIONS
--------------------
When a 'DataWay' file is saved, as well as the actual data, the following
options are saved with it:

Current 'Sort' options    The 'Sort' options as displayed in the 'Sort'
                          window.

Current 'Export' format   The 'Export' format as displayed in the 'Export'
                          save window.

These options are re-engaged when a 'DataWay' file is re-loaded.


KEYS
----
When 'DataWay' has the input-focus, shown by the title bar of the 'DataWay'
window turning pale yellow, the following key commands are available:

F1            Opens the DataWay 'About this file' information window.

CTRL-F2       Close the 'DataWay' main window.

F3            Open the 'Save' window.

SHIFT-F3      Open Export window.

F4            Enter Search mode.

F5            Open the 'GOTO' window.

F6            Open the 'Sort' window.

CTRL X        Cut current record and store on clipboard.

CTRL C        Store current record on clipboard.

CTRL V        Paste record on clipboard to a new record.

CTRL D        Enter today's date in a 'Date' field.

Page up       Next record.

Page down     Previous record.


GENERAL INFORMATION
-------------------
To load a previously saved 'DataWay' or 'CSV' file into 'DataWay':

  o  Double-click a 'DataWay' file. - If !DataWay has been 'seen' or 'Booted'
  o  Drag a 'DataWay' file to the 'DataWay' icon bar icon.
  o  Drag a 'DataWay' file to a non-white area of the main 'DataWay' window.
  o  Drag a 'CSV' file containing up to 12 fields to 'DataWay'.

If a 'DataWay' file has been password protected, the password window will be
diaplayed, inviting you to enter the password for that particular file.  If
the correct password is not entered within 5 attempts, the password window
stops further input until !DataWay is re-run.

A 'DataWay' file can be merged with a current database by SHIFT/dragging it
to a non-white area of the main 'DataWay' window.


TECHNICAL SPECIFICATION
-----------------------
Records - 'DataWay' usually supports up to 2000
           If you require more let me know.

Fields  -  Supports 12 fields.


********************
*  ABOUT GIFTWARE  *
********************

This program is giftware, not public domain.  Giftware means that if you
use this program regularly you are asked to send the author a 'gift'.

By sending a gift, your support helps to provide updates to this program
and an incentive for other RISC OS software to be developed.

To make a gift
--------------
You can make a secure on-line donation using PayPal from my website
by clicking the 'Donate' icon on my software page.
http://www.bapfish.org.uk/software.htm

Upgrades
--------
The current site to obtain the latest version is from:

    http://www.bapfish.org.uk/


End-User licence conditions
---------------------------
You may give a copy of this software to a friend but you may only
distribute this software from your web site or on a CD-ROM or similar
device in bulk with the express permission of the author.
In the event of my death, this software will become open-sourced.

Disclaimer of liability
-----------------------
1. The software is supplied 'as is' the Author makes no warranty, whether
   express or implied, as to the merchantability of this software or its
   fitness for any particular purpose.

2. In no circumstances will the Author be liable for any damage, loss of
   profits, goodwill or for any indirect or consequential loss arising out of
   your use of the Software, or inability to use the Software, even if the
   Author has been advised of the possibility of such loss.

3. The author reserves the right to change the specification of this program
   without notice.


Bug Reports and Suggestions
---------------------------
Bug reports and suggestions will be welcome from all users, even if you have
not made a gift (yet).

Please enclose the following information:

    Computer:

    RISC OS version:

    Software version: 

    Problem/Suggestion:

    Any other relevant information:

and contact me by Email at:

    bernard@bapfish.org.uk
    ~~~~~~~~~~~~~~~~~~~~~~

Other Software by Bernard can be found at:

    http://www.bapfish.org.uk/
    ~~~~~~~~~~~~~~~~~~~~~~~~~~





                Versions up to 0.10 tested with RISC OS 3.70
                 Versions 0.17 - 0.20 tested with RISC OS 4.02
             Version 0.20 and higher tested with RISC OS 4.02 and 5
             Version 0.30 and higher tested with RISC OS 5.25
