Sound Sensations!/sound_sensations.iso/miditool/sysex/sysex.doc

Text File | 1991-05-01 | 12KB | 346 lines

=================================================================
                   SYSEX -Yet Another Sysex Program
=================================================================

This  is yet  another program  that sends/receives  SYSEX data. I
wrote it because I feel it  offers some capabilities not found in
other similar programs. It has  proved very usefull while working
with my YAMAHA TG55, for which I dont have a patch editor yet.

This software is public domain. Use  it or change it as you wish.
I am uploading the source (Turbo pascal 5) for anybody interested
to modify it. If you have  any problems, I would be interested to
hear about them, and, possibly, to suggest a solution. In fact,if
anybody  finds it  usefull, PLEASE   drop me  a note.  This would
encourage  me to  upload other   programs I  will develop  in the
future. Future versions of this program will appear if, and when,
I will  receive  any  problem   reports  and/or  suggestions  for
extensions.

(Note that I am uploading from  Greece, which means that it costs
me about  1$ per minute...  So, I would  like to know  whether my
uploads are helpfull  to anybody, or are just  falling in a black
hole.)

Overview
--------

SYSEX is  a program that can  send and receive SYSEX  data to any
synthesizer. Its main features include the capability to create
interactive  dump  request  files,  the  automatic calculation of
checksums, and the ability to work with human-readable files.

System requirements are :

 1. IBM clone with at least 256K.
 2.  MPU-401  compatible  interface,  standard configuration
     (IRQ 2, Base 330h).


Program operation
-----------------

The command format is : SYSEX <Filename1> [<filename2>] /options

Depending  on the  required  mode,  filename2 and/or  options are
optional. If  the names have  no extension, an  extension of .SYX
will be assumed.

If SYSEX  is typed with  no parameters, a  breif help message  is
displayed.

There are 4 main modes of operation :

1. Send a file to the synth
---------------------------

   Format  : SYSEX <filename1>
   Options : None

The main use of this mode is  to send bulk data (like voice info)
to the synth.

The  file is  assumed (and  checked) to  be a  series of properly
formatted  sysex  messages,  i.e  any  number  of blocks with the
format : <SYSEXSTART> data bytes <SYSEXEND>.
 where sysexstart is F0h, and sysexend is F7h.
The  blocks  must  be  consecutive,  without  any  intervening or
missing bytes, for example :

F0 dd dd dd F7 F0 dd dd dd dd dd F7

Missing or superflous start/end bytes will be reported as errors.

If  there are  more than  one blocks,  the program  will insert a
delay of at least 110  milliseconds between transmissions of each
block. This  is required by  some synths. If  this number is  not
enough, recompile  the program changing the  values in the <WAIT>
routine..


2. Send a dump request , and receive a sysex dump
-------------------------------------------------

   Format : SYSEX <filename1> <filename2>

For <filename1>, all comments for mode 1 apply. The program will:

a. transmit the first file, as in mode 1
b. wait for sysex data to come in.
c. Store the received bytes in <filename2>

Since  there is  no reliable  way to  know when  a sysex dump has
finished, (as it may consist of more than one blocks),the program
will  continue  receiving  and  storing  bytes  until  any key is
pressed. To help you know when a sysex dump has finished, it will
display a  receive bytes count. While  this number is increasing,
the synth is  sending data. When this number  is stable, you know
that the synth has finished transmission, and you can hit any key
to end the receive and store the data.

3. Receive a bulk dump started manually from the synth pannel
-------------------------------------------------------------

   Format :SYSEX <Filename1> /m

 The  program works  like mode  2, but  skips the  first step  of
 sending a file. It waits for the  data to come in, and the saves
 them in filename1.

4. Convert between file formats
-------------------------------

   Format SYSEX <filename1> <filename2> /c

In this mode, the program reads-in  the first file, and stores it
in the second file. No interaction is done with the synth at all.

This mode  is usefull for converting  between file formats, since
the input  and output formats  can be different.  See notes about
file formats.

File formats
------------

The program recognises and generates two file formats, depending
on the file name suffix:

if a  suffix of .TXT  is given, the  program assumes TXT  (Ascii)
format.

if any other suffix is  given, the program assumes sysex (binary)
format.

If no suffix  is given, the program assumes  .SYX, and interprets
the file as binary (same as above).

Format Description
------------------

a. SYSEX files.
--------------
These are  standard SYSEX (or  MIDIEX, as some  call them) files,
which are an exact binary  image of the sent/received data. There
are no headers or any other extra bytes. These "pure" sysex files
can  be handled  by most  sequencers. While  usefull, they do not
offer  any extra  capabilities. When  using this  kind of  files,
SYSEX works like any other sysex-exchange program.

b. TXT files
------------

This format is peculiar to  the SYSEX program. Conceptually it is
the same with format (a), but with two  major differences :

 1. The  data are stored in  ASCII format, which means  that they
    can be created/edited with any ascii word prossesor/editor.
    Therefore, if you loaded the  file with a standard editor,you
    would see something like :

     F0 10 11 13 F7

    (In contrast,  if you loaded  a format(a) file  in an editor,
    you would see "garbage", like smiling faces etc)

    Values are  delimited by any  number of spaces,  and the line
    length  is limited  to 254  chars. There  should be  no blank
    lines, since  this will terminate  file input. (This  feature
    can be  used to add a  large block of comments  at the end of
    the file, by  separating the comments from the  data with one
    or more blank lines. Make  sure that any blank lines inserted
    for this  purpose are REALLY  blank, i.e zero  length, and do
    not  include any  spaces. Remember  that a  zero length  line
    LOOKS the same as one that consists of spaces only).

    The  error checking  is  rather  rudimentary, so  be carefull
    about the data format...

 2. When a file in this  format is TRANSMITTED, there is a number
    of special constructions that SYSEX will recognise. These can
    be embedded in the text,  and make all the difference between
    using  this TXT  format and  the standard  sysex format  (a).
    These are :

     1. 'any text'.

        If  any text  is  put  between quotes,  the corresponding
        ascii values will be sent.  This helps you put ascii data
        like voice names in the  text, without reverting to ascii
        tables and such.

        e.g. : F0 43 20 'AB' 20 21 22 F7 actually is sent as :
                         ││
                         │└┐
               F0 43 20 41 42 20 21 22 F7

     2. ;any text.

         A  semicolon makes  SYSEX ignore  the rest  of the line.
         Usefull for comments.

     3. | xx xx.

        The  bar (|)  will send  the logical  OR of  the next two
        values. This is especially usefull with the ? construct
        (see below).

         E.g  F0 | 01 02 F7 =  F0 03 F7  (03= OR of 01 and 02)


     4. ?Prompt

         You will be prompted for  a value, and this will replace
         this  construct.  Usefull  for  making  parametric  dump
         request files.  For example, let's  say that your  synth
         sends  a particular  part data  with the  following dump
         request :

          F0 43 01 2n F7 , where n is the part required.

         Combining  constructs ?  and |  , you  would create the
         following dump request file :

          F0 43 01 | 20 ?Part F7

         This line would result in the program asking :

          Part :

         After  you type  in the  part value (n),  this will be ORed
         with 20h to give the required 2n.

         Hint : If you want to type in the value in hex , precede
         it by a $ sign. For example : $3F

     5.  @,#  pair.  These  constructs  are  used  to  make SYSEX
         calculate  7-bit  checksum  values  for  you (which some
         synths require). When @ appears, the checksum counter is
         zeroed. From this point onward, each byte transmitted is
         calculated in the checksum, until  a # appears, which is
         then replaced  by the 2's complement  of the checksum. I
         have tested  this with ROLAND  and YAMAHA synths  and it
         works fine, saving all the work of calculating checksums
         by hand...  Remember, not ALL  bytes in a  sysex message
         take  part in  the checksum,   thus the  need for  the @
         character  to   signify  the  starting   point  for  the
         calculation. This capability was the main reason I wrote
         this program...

         Example : F0 43 20 @ 01 02 03 # F7
                            └─ start   └── checksum
                                      ┌───────┘
         results : F0 43 20 01 02 03 7A F7


Tips about using TXT files
--------------------------

1.  Since each  file name  in  a  command can  be in  a different
    format, you can use SYSEX  to do format conversions. Also, if
    you  want to  check your  parametric dump  files, you can use
    SYSEX to see what exactly will be transmitted. For example,if
    you have created a file  DUMP.TXT that has special constructs
    in it, you can use the command :

    SYSEX DUMP.TXT DEBUG.TXT /c

    If you then  edit the resulting DEBUG.TXT file,  it will show
    the  exact sequence  sent to  the synth,  with all constructs
    replaced.

2.  It is  best to  keep your  dump request  files in TXT format,
    since  it is  easier to  edit/maintain them.  Synth-generated
    bulk dump files,  on the other hand, should  be kept in sysex
    format, since there are probably no usefull substitutions you
    would  want to  make during  uploading such  a file,  and the
    sysex format works MUCH faster. In any case, you can convert
    between formats with the /C option at any time..


Examples of usage:
-----------------

1. send file sounds1.syx to the synth

 SYSEX SOUNDS1  or SYSEX SOUNDS1.SYX  (.SYX is default)

2. receive a bulk dump. Bulk request is in TXT format, save dump in
   sysex format :

   SYSEX REQUEST.TXT SAVED or
   SYSEX REQUEST.TXT SAVED.VOI (any  suffix but TXT, means binary
                               file)

3. receive a manual-started  bulk dump, save in TXT :

    SYSEX SAVED.TXT /m

4. convert between TXT and sysex formats :

    SYSEX REQUEST.TXT REQUEST.BIN /c or
    SYSEX REQUEST.BIN REQUEST.TXT /c



Limitations
-----------

The  maximum  buffer  size  is  currently  50,000 bytes, so files
larger than this cannot be sent/received.

Error messages
--------------

Input file not found
  the program cannot find the file

File too large
 buffer limit exceeded for input file

Too many data in
 received data exceed buffer limit

Format error, missing Start of Exclusive
 Blocks are not correctly formatted, see notes about transmitting
 files to the synth

Cannot create dest
 Error while opening  output file. Error in name,  or no space on
 disk

Acknowledgments
---------------

I have used a unit downloaded from CIS, originally named MPU401,
with heavy modifications. It is quoted as created by John Sloan.
My thanks to him.

The idea of macro constructs, and the .SYX suffix come from
Greg Hendershott's fine CAKEWALK program. Special thanks.



Mike Cariotoglou,Greece

CIS 10012,1767
BIX avoreadis