     -----------------------------------------------------------------
    |                                                                 |
    |                    QX FILE  V. 1.1                              |
    |                                                                 |
     -----------------------------------------------------------------


------------------------ SHORT DESCRIPTION -------------------------------

Filer program for the Yamaha QX5 MIDI sequencer.


-------------------------- INTRODUCTION ----------------------------------

QX File facilitates the transfer of Yamaha QX5 sequencer data
between the sequencer and an Atari ST computer. It is designed to be
user-friendly and intuitive in use. Considering that it was written in
compiled BASIC (all I could cope with on the ST when I started the program)
rather than C or machine code, I believe it copes pretty well with its job
provided you don't expect too much for nothing and follow the suggestions
which follow.

The program has not been tested with the more advanced QX5FD model, but it
is unlikely that users of that model would find the program of much use
anyway. Users of other Yamaha sequencers may wish to try the program,
however: if your sequencer uses the NSEQ format (i.e. if it has 8 tracks of
MIDI data) rather than the ESEQ format (which is used by 16-track Yamaha
sequencers), then you might well be able to make use of this program.


----------------- SYSTEM REQUIREMENTS & COMPATIBILITY --------------------

The program has been designed to run in high resolution or medium
resolution. Text displayed in medium resolution is perfectly legible, but
you will find that sometimes text appears slightly too high in
the text edit boxes. If this really bothers you, refresh the screen by
pressing the escape key. The chances are that you'll hardly notice,
however.

The program has been tested on various versions of TOS up to version 2.06.
Multitasking versions of TOS will probably present problems, but I don't
know.

Other than your ST and Yamaha sequencer, the only other pieces of
equipment you need are two MIDI leads. The MIDI Out socket from the
sequencer should be connected to the MIDI In socket of the ST, and the
MIDI Out socket of the ST should be connected to the MIDI In socket of
the sequencer.

It is recommended that no other MIDI equipment be connected between the
ST and the sequencer, as QX File is incapable of filtering out irrelevant
MIDI data. Experiment with more elaborate signal routing later (at your
own risk), once you are used to the operation of QX File.

IMPORTANT: certain programs or desk accessories which access the ST's system
vectors may prevent QX File from working properly; QX File, like most other
MIDI programs, is timing-critical. If QX File has to compete with other
programs for vectors, incoming MIDI data may be corrupted and the program
may even lock up. To prevent this, remove any suspect desk accessories and
auto-booting programs from your boot disk before running QX File. When you
are sufficiently acquainted with QX File, try adding these programs and
accessories back one at a time to find out which ones, if any, cause a
problem with the reception of data. In the event of a program proving to be
incompatible with QX File, it may be possible to tailor the  conflicting
program rather than removing it. For example, users of the desk accessory
Harlekin will probably need to either remove Harlekin or alternatively use
that program's facility to switch vector interrupts off (Harlekin should not
be allowed to access the 200Hz interrupt, but the VBL interrupt should work
provided that the Macro facility is disabled).

QX File is incompatible with C-Lab's Softlink and probably all other
switcher programs or multitasking environments. Also, it uses its own
format when saving files, not Standard MIDI Files, so you will not be
able to directly exchange data with other MIDI programs.


---------------------- RUNNING THE PROGRAM -------------------------------

If your copy of the program came with a file called QXFILE.DAT, delete
that file or keep it in a separate directory from the copy of the program
you are about to run. You don't need it. A file of this name may be
created by the program later on in order to store YOUR preferences, but
more on that later.

Make sure that you have saved any data from other programs before trying
out QX File. If a mistake is made while trying out the program, you may have
to reset the computer, so play it safe.

Double-click on the icon QXFILE.PRG. Once the program has loaded, the main
screen will appear.


-------------------- AN EXAMPLE OF QX FILE IN USE ------------------------

The first thing to try out is the Receive function. This receives MIDI
data dumps from the sequencer.

Make sure that the device number of the sequencer is set to 1 (refer to
your sequencer's manual if you are not sure how to do this).

Select "Receive" from the "Transfer" menu, or press "R" on the
keyboard (keyboard shortcuts exist for most functions).

An alert box will appear, checking that you want to receive a sequencer
dump. Click on the "OK" button, or press "Return" or "Enter". (Note that
with this program, it is assumed that you probably do know what you are
doing, so the default option - selected by "Return" - is always the option
which confirms your request).

Set up the sequencer to transmit (see page 36 of the QX5 manual) and press
the sequencer's Start button. The sequence data is now being sent to the ST.

At the end of the transfer, QX File will display an alert box confirming
successful reception of the dump. If this alert box does not appear, and
the sequencer has finished transmitting, a problem has occurred in the
dump; check your MIDI connections, reset your ST, reload QX File and try
again. Such problems should be very rare if the system is set up correctly.

It is possible to abort the transmission of a dump by selecting 'Reset' on
the sequencer.

Now that a dump has been received by the ST, we can add some descriptive
text. For instance, to enter a song's title, click in the "Title" box, or
press "T" on the ST's keyboard. A cursor will appear, and the title may be
typed in. Press the "Return" or "Enter" key to end the inputting of text.
To enter details of track 1, click inside the "Track 1" box or type "1";
you can then type in "Bass followed by strings" or whatever is applicable
to the track. To add a note about the song (e.g. date of composition or
whatever), click inside the "Note" box or press "N".

Note that text can be freely edited; if you want to change the title, for
instance, press "T" as before or just click on the part of the title to
be edited. Experiment with the left and right cursor keys, the Escape key
and the Undo key, and of course Backspace and Delete.

Text boxes for macros are also available. Select "Display Macro Text" from
the "Text" menu or press "M" on the keyboard. A window will appear with
text boxes for all 32 macros. Editing is very similar to that in the main
screen. You can click on the box which you want to edit, or enter the
macro's number. Note that each macro requires two digits to be input for
its number. So to edit macro 3, type "0" followed by "3". Invalid input
(such as letters) following a digit will cause the input to be ignored.
For instance, typing "0" followed by "R" followed by "3" will result in
the "0" and the "R" being ignored, with the program waiting for another
digit to follow the "3". Muck around with this kind of input and you'll
quickly get the idea.

As usual, press the "Return" or "Enter" key to end the editing of a text
field. Pressing the key again will select the "OK" button at the bottom of
the window and return you to the main screen. You may of course click on
the "OK" box instead. (Please note however that it isn't a true GEM button
and may occasionally cause a small bug; you may find that you have to click
once with the mouse before you can access the menus the first time after
returning from the macro window. No great problem.)

Once you are happy with the descriptive text, you can proceed to save the
dump along with the text. Select "Save..." from the "File" menu or press
the "S" key. The file selector will appear and you can type in a suitable
file name. The file will be given the extension ".QXF" automatically. You
can override this by typing in your own extension if you wish (for example,
typing "MYSONG" will save the file as "MYSONG.QXF", but typing "MYSONG.1"
will save the file as "MYSONG.1"). It is recommended that you keep the
".QXF" extension however as this is what the program will expect when
subsequently called upon to reload the file.

The final function to try in this example is Transmit. Press "Track" on
your sequencer to ensure that it is ready to receive a dump. Select
"Transmit" from QX File's "Transfer" menu or press the "X" key. An alert
box will appear asking you for confirmation that you want to send a dump
Select "OK" and avoid pressing any further keys (if you press any keys,
you are telling the program to abort the dump).


------------------------------- COMMANDS ----------------------------------

I hope that the tutorial above will have given you a feel for QX File.
Now let's look at the commands available within the program, most of
which are obvious in use. There are keyboard shortcuts for many commands,
and these may be typed in upper or lower case. Shortcuts are noted in
brackets after the command name in the list which follows.

The "File" menu:-

 "Load..." (L)   brings up the file selector in the usual ST fashion, so
                 that a QX file can be easily selected. Besides directories
                 (folders), the selector will show only files with the
                 extension ".QXF". You can of course edit "*.QXF" to read
                 "*.*" if you need to load a file which does not have this
                 extension. Only valid QX File files will be loaded.

 "Save..." (S)   also brings up the file selector. Choose a valid
                 directory, type in a suitable filename and the file will
                 be saved. So no great surprises there!
                 Note that if no file extender is typed in, the file will
                 be given the extender ".QXF".

 "Delete..." (D) calls up the file selector so that a file can be selected
                 for deletion from the disk. The program will ask for
                 confirmation before deleting the specified file.

 "Save set-up"   saves the following options: auto-save on/off,
                 auto-receive on/off, auto-transmit on/off and device
                 number.

 "Auto-Save"     Click on this menu entry to activate/deactivate auto-save.
                 If auto-save is activated, a tick will appear against the
                 menu entry.
                 When auto-save is activated, as soon as a dump is received
                 from the sequencer, the file selector will appear; input
                 a filename in the normal way and the file will be saved.
                 Obviously any text will have to be edited BEFORE dump
                 reception is attempted to make proper use of the auto-save
                 option.

 "Quit" (Q)      quits the program. An alert box will appear asking you to
                 confirm the quit command. The default is "QUIT!". (This is
                 how it should be! Why is it so difficult to persuade some
                 programs that you want to quit?!). Be sure that you have
                 saved all important data, of course.

The "Transfer" menu:-

 "Receive"
        (R)      calls up an alert box asking you to confirm
                 to receive a dump from your sequencer. To proceed, select
                 "OK", make sure that the sequencer is set to the correct
                 device number (see page 45 of the QX5 manual) and then set
                 up the sequencer ready to transmit (manual page 36). Press
                 "Start" on the sequencer and the dump will be sent.
                 QX File will display an alert box upon successful
                 reception of a dump.
                 Dump transmission can often be aborted by selecting
                 "Reset" on the sequencer.
                 Unfortunately if something goes wrong in the transmission
                 of the data, and the alert box does not appear at the end
                 of the dump, you have no option but to reset your ST,
                 check your MIDI connections and start again. This should
                 happen only rarely however, if ever!

 "Transmit"
         (X)     calls up an alert box asking you to confirm that you want
                 to transmit a dump from the ST to the QX5 (this is of
                 course only an option if do in fact have a dump to
                 send!).
                 To proceed with the dump transmisson, FIRST press the
                 "Track" button on your sequencer; this readies the
                 sequencer for dump reception. THEN select "OK" from the
                 alert box.
                 It is possible to abort transmission of a dump by pressing
                 any alphabetical or numerical key on the ST's keyboard. If
                 you do abort transmission, the sequencer will warn you
                 that the dump is of an invalid format. All this means in
                 this case is that the dump was ended unexpectedly; just
                 select "Track" or "Reset" on the sequencer.

 "Auto-
 Transmit"       If this menu entry is checked, a dump will be transmitted
                 to the sequencer as soon as it has been loaded from disk.
                 Click on this menu entry with the mouse to check or
                 uncheck it.
 "Auto-
 Receive"        If this menu entry is checked, QX File will automatically
                 receive any incoming dump without you having to select
                 "Receive".
                 Click on this menu entry with the mouse to check or
                 uncheck it.

"Text" menu:-

 "Erase all
 text" (E)       A box will appear asking for confirmation that you want
                 to erase all text. Upon confirmation, all text information
                 (for title, tracks, note and macros) will be cleared from
                 the text boxes.

 "Display Macro
 text" (M)       accesses the Macro text screen. See the section "An
                 example of QX File in use" above for an explanation of
                 how to edit text boxes.


"Device" menu:-  Click on the required device number. The device number
                 should be set to the same value as that set in your
                 sequencer (see page 45 of the QX5 manual).


------------------- TIPS AND MISCELLANEOUS INFORMATION -------------

* If the memory of the QX5 is nearly full, it may be necessary to clear
  some of the tracks before it will accept a dump.

* The functions "Load...", "Save..." and "Delete..." use the standard ST
  file selector, but display an additional box above the file selector to
  state the selected function. The program will also work with A&D
  Software's Universal Item Selector III (and, no doubt, other substitute
  file selectors), but you may wish to lower the on-screen position of
  UIS III so that the additional information box remains visible (see
  your UIS III manual for details of how to do this).

* If the screen display should become corrupted for any reason, pressing
  the escape key at any time other than while editing text or executing
  a transfer will redraw it.

* Pressing Alternate + Help gives a screen dump to a suitable printer.
  However, do not attempt to do this while transmitting or receiving a
  MIDI dump, as data will be lost and the ST will have to be reset.

* QX File does not transmit or respond to QX5 dump request messages.
  Remedying this omission would be a priority for a future version if one
  were to be written.

* If you save a QX file as "AUTO.QXF" in the same directory as QXFILE.PRG,
  this file will be loaded automatically when the program is next run.

* DON'T FORGET! CERTAIN ACCESSORY PROGRAMS CAN CAUSE TIMIMG PROBLEMS.
  If you keep getting corrupted or incomplete data during transfers,
  try removing all the desk accessory programs temporarily, and add
  them back one at a time until the culprit is found.


------------------------- ERROR MESSAGES ------------------------------

The following error messages may occur when using disk functions (Save,
Load etc.):-

"A write error has occurred"
"Disk error" - This covers disk errors not covered elsewhere. This error
will occur if an attempt is made to delete a write-protected file.
"GEMDOS range error - seek wrong?" - This appears to be a fatal TOS error,
outside the control of this program. I saw it occur once when I attempted
to load a file which was 0 bytes long!
"Insufficient disk space" - The disk is full. Use another disk (or hard
disk partition).
"Path not found!" - The directory you have specified does not exist.
"The disk is write-protected" - Remove the write-protection and try again.


---------------- THANKS, DISCLAIMERS AND LEGAL MATTERS -------------------

This program is copyright 1992 & 1993 Kevin Busby. It may be used, copied
and distributed free of charge, but only subject to the following
conditions:-

 (1) The file QXFILE.PRG may not be distributed without the file README.TXT.

 (2) The contents of QXFILE.PRG nor README.TXT may be altered in any way
     (compression and/or encoding is allowed, provided that it is applied to
     both files).

 (3) No liability may be assumed for the suitability of this program for
     any purpose, or for any consequences of using the program. You use
     the program entirely at your own risk, on the understanding that any
     damage or loss resulting from use of the program is your problem and
     no-one else's.

(4) The program may not be sold. So-called "Public Domain" services and
    others may charge a reasonable fee to customers for copying and
    distributing this software, provided that it is made clear to the
    customer or potential customer that no charge is being made for the
    program itself.

(5) The program may not be used for the promotion or marketing of goods or
    services without my express permission.


All trademarks recognised and as credited.

E&OE.

I thank Yamaha-Kemble Music (U.K.) Ltd. for their courtesy and efficiency
in supplying details of the QX5 data format.

But please note:-

This program has no connection with Yamaha-Kemble, Yamaha Corporation or
any other such organisations, so don't trouble them if you have any
queries about the program.


--------------------- AT LAST! THE END! ----------------------------

Please note that I am not offering support for this program, but you can
contact me by email <kevinb@central.sussex.ac.uk> until around the middle
of 1994 to if you want to let me know that you found the program
particularly useful or useless.

I expect QX File to be of limited appeal, and I think it unlikely that
further versions will appear. However, I hope that somebody somewhere
finds the program of use!


Kevin Busby

East Sussex, UK. November 1993.

