Sound Sensations!/sound_sensations.iso/miditool/getit35/getit.doc

Text File | 1989-03-05 | 22KB | 695 lines

                             GetIt!
                   ShareWare MIDI file utility
                           version 3.5
                         by Aron Nelson
                            3/3/89
                          USERS MANUAL









































                           DESCRIPTION





 GetIt! is a MIDI file utility that can handle system exclusive
transfers between a MIDI device and your IBM computer or strict
compatible.  GetIt! can received MIDI system transfers from
a variety of MIDI devices and save the data to a disk file. This
allows you to have a library of files which contain the data for
all  of  your  MIDI  devices.   GetIt!  can  perform  some   file
manipulations  that  allow you to convert your  system  exclusive
data from one format to another by adding/removing  header/footer
bytes.

FEATURES:

Can receive system exclusive dumps as large as system memory.

System dumps can contain more than one dump.

Can transmit system exclusive dumps as large as system memory.

Can sequence up to 8 tracks of multi-channel music.

Versatile  peek mode with English/Decimal/Hex views  and  Log-to-
disk function.  User defined MIDI transmit strings.

Can  search through a file and find the beginning of  sysex  data
and begin transmitting the sysex data.

Can add sysex header/footer bytes to a binary file.

Can strip (delete) header/footer bytes from a binary file.

Can be automated through the use of script files.

Extensive script commands including CASIO mode and looping.

Can transmit many MIDI messages through built in script commands.












                          GETIT! MODES



1) RECEIVE MODE:  GetIt r

   GetIt! is set up as a device that will wait for any system
exclusive  transfers.  System exclusive  transfers  are  received
"back  to back" in memory and stored as such. This allows you  to
receive  system transfers from a D10 and a Dx7, save them as  one
file, then transmit the whole system file as one.
When a system transfer has ended, GetIt! will display the
transfer status in kilobytes and bytes. The transfer window
will something look like this:

     transfer status -> 43K 640 bytes
     num sysex dumps -> 166

Press <return> only after the numbers stop moving, this will
end the transfer and take you to the file section where you will
be  prompted for a filename. Be patient as large  data  transfers
can  take some time. Because of the large amount of data that  is
being  received, the transfer status numbers only move *after*  a
system message has been received.
  GetIt! checks for an overwrite when saving and will ask you  if
you  wish to overwrite anyway. The RECEIVE MODE is good for  MIDI
devices that can start MIDI transfers from the front panel like a
Dx7,  or  a D10, D20.  If you have a MIDI  device  that  requires
handshaking or prompting, then you must use script mode.


2)  TRANSMIT MODE:  GetIt t [s] <optional file to send>

To transmit a sysex data file that is stored on disk, simply type
GetIt t <file to send>. GetIt! will read the sysex file and
proceed  to send the data after reading the file. If  you
wish to be prompted through the procedure just type "GetIt t" and
GetIt!  will  prompt  you through the procedure.  If  the  second
parameter "s" is included, GetIt! will skip any extraneous header
bytes  and start transmitting the system exclusive file when  the
first  $f0 is found.  GetIt! will then transmit ALL  bytes  until
the  end of file.  Use the "s" command when you have  files  with
extraneous  header bytes before the actual system exclusive  data
starts.   One restriction, the "s" mode can only handle files  as
large  as  64K.  Any files larger than 64K will cause  GetIt!  to
stop  transmission.  As a general rule, anything smaller  than  a
sample  dump is OK. "S" mode is good for librarians such  as  the
one in CAKEWALK.  CAKEWALK adds header bytes to the beginning  of
sysex data files.







3)  PEEK MODE: GetIt p

Peek mode turns GetIt! into a midi terminal.  Incoming midi  data
is  displayed onscreen as (h)ex, (d)ecimal or (l)ine.  Line  mode
is actually english expressions telling you what type of data  is
being  sent and the following bytes associated with the  type  of
message.  The  type  of display can be changed "on  the  fly"  by
simply   typing  the  letter corresponding to  the  display  type
twice.  GetIt!  also  has a transmit mode  which  allows  you  to
transmit  MIDI  messages   to  your  MIDI device  and  view   the
responses   if   any  onscreen.  This is useful if  you  will  be
developing  script  files (mentioned  below).    By  transmitting
MIDI  data,  you  can   see   if  certain  system  commands   are
communicating to the MIDI device.

Note: A "hidden" feature allows you to display incoming clock and
active sensing bytes.  Active sensing and clock bytes disrupt the
diplay  because of the frequency at which they are sent,  however
if   you   wish to display them, just press the letters  "f"   or
"F"  then  press the type of display (D),(H),(L) and  the  active
sensing and clock bytes will be displayed. To stop showing active
sensing  and  clock  bytes, simply repeat the procedure and   the
function will be toggled off.

Version 3.5 adds 2 new features to peek mode:  Event logging  and
transmit libraries.  Event logging allows you to write everything
that  you see on screen to disk.  MIDI data is written to a  disk
file  which  can  be  viewed  with  any  standard  ascii  editor.
To activate event logging, type ALT-L.  GetIt! will prompt for  a
filename to log to.
Transmit  libraries allow you to create MIDI "strings"  that  you
can send to your MIDI device.  Up to 16 strings can be stored  in
any  one file.  Each string is composed of a list of  MIDI  bytes
that  you  would  like to send out the MIDI  port.   To  activate
transmit  mode press 't' while in peek mode.  When the  menu  for
transmit appears, type 'r' to read a .trn file. Once the file
is  read  simple point to the string you wish to  send  with  the
cursor keys and press <enter>.  Escape aborts the procedure.   If
you  would like to create your own transmit strings  simply  type
'e'  for  edit and an edit box will appear.  Type  in  your  MIDI
string  at this point.  To save your MIDI strings, type  's'  for
save  and  a dialog box will appear asking you for a  file  name.
Type in your file name and press enter to continue the save.












4) SCRIPT FILE MODE: GetIt c <script file>

   Script file mode allows you to "talk" to your MIDI devices
if you have the system exclusive documentation at hand. By using
the  script  commands  in  GetIt!  you  can  initiate  a  2   way
communication  between your MIDI device and GetIt!.   The  script
commands and syntax are based loosely on Carter Scholz's MidiSave
script  language.  The  differences  are  that  in  GetIt!,   all
parameters   are preceded  by commands and that the  command  set
has   been   greatly  extended. There must  be  a  space  between
commands  and parameters. To create a script file all you  do  is
use an ascii word processor like Sidekick, and type commands into
a text document.

The commands available to you are:

A  All notes off.
   Sends all notes off on every MIDI channel.

B  Blank (clear) the screen.
   Clears the computer screen.

K  Wait for (IBM) keypress.
   Waits for the user to press a key.  Pauses script file
   execution.

M  Display message following M to (IBM) screen .
   Displays message following M. Must be on a line by itself.

N  <channel> <noteX> <velX> Play note.
   Sends a MIDI note on command to MIDI device.

P  <channel> <patchnumX>     Send patch change.
   Sends a MIDI patch change to MIDI device.

R  <num>  Receive <num> transfers from MIDI device.
   Receives <num> of complete MIDI messages from MIDI device.

S  Send a system message $F0 <messageX> $F7
   Sends a system message.  Must be a complete MIDI message starting
   with $F0 and ending with $f7.

W  <num>  Wait <num> milliseconds.
   Waits (delays) <num> milliseconds - uses Turbo Delay procedure.
   Useful for delays between notes.

Z  Save the MIDI sysex transfers.
   Saves a system exclusive dump.

[  <starting index> Start loop at index.
]  <ending index>   End loop at index.
X  Replace with Loop Index.





/,\,{,},(,),;, are comment markers, follow with any comment.
Variables that end with an X can be replaced with the current
loop index.

NOTE:
The M and comments only work on a *line* basis. You can only place comments
and messages on a line by themselves on this release. I plan improve
on this in later versions. Do not mix commands and message/comments on one
line.


A loop is defined as:
[ <start number>
    <any command>
] <end number>


A WORD ABOUT X VARIABLES:
 X variables allow the user to substitute the LOOP INDEX  anytime
he  puts an X instead of a number.  The X variable ONLY WORKS  IN
LOOPS.  Lets say you want to transmit patch changes  from  1-127.
Create a loop [ 1   ] 127. Put this in the loop:
TR 192 X

Example:  [ 1
            TR 192 X
          ] 127
The  X variable will substitute the loop index 1->127 and put  it
into X, looping through patches 1-127.

EXTENDED COMMANDS  (GetIt 3.5)

These extended commands allow GetIt! to send libraries that are stored
without header information.  Some librarians store just the data portion
of the system exclusive transfer and "throw away" the header info.
These commands will let you put them back in when transmitting the file.
Note:
 They do not alter the files themselves.

TR  <byte..Byte..etc>
    Transmit user defined bytes.
    Sends  arbitrary bytes out the MIDI port.  Useful for  adding
    headers   to   voice  libraries.  The  format   is   TR   xx1
    xx2...xx3...xx4...etc. Cannot accept X variables.

BS  Binary Send.
    Reads any binary file and sends the file as MIDI bytes.  These files
    are  usually  files that do not include the MIDI  header  $f0
    etc.  BS is an unusual script command because it prompts  you
    for a file to send.



SS  Send Binary w/ search.
    Reads  any  binary file and starts transmission  of  file  at
    first  $f0  that it encounters.  Some librarians  prefix  the
    binary with some header information, this command will ignore
    them. SS prompts you     for a file to send just like BS.

IS   Initialize  Sysex buffer.  Use this command when  you  would
     like to disregard the last sysex dump.  This initializes all
     of the sysex variables to 0.  Use this when communicating to
     your  MIDI kbd with the "S" command.  For example,  if  your
     kbd  send an acknowledge message after you prompt it  for  a
     system dump, send  the prompt command with the "S" command,
     use  the  "R  1" command to wait  for  one  system  message,
     initialize the sysex buffer to disgregard the message  after
     receiving it with the "IS" command, then use "R <num>" to
     receive the system dump.

CASIO COMMANDS:
    Casio commands allow you to send and receive any type of MIDI
    data.  Some  casio MIDI devices stop the  transmission  of  a
    system exclusive file right in the middle of transmission and
    require  a  handshake! Casio mode allows you  to  communicate
    to the casio with the commands CT, CW and CR. Casio  commands
    should be within the OPENCASIO and CLOSECASIO statements.

OPENCASIO  Open Casio mode.
    GetIt! 3.5 now supports casio synthesizers. Full  handshaking
    is supported with the CW and CR commands.
    The OPENCASIO command prepares GetIt! for a CASIO script.

CLOSECASIO Close Casio mode.
    This command closes the casio mode.

CT <byteX....byteX....byteX...etc>
    This command tells GetIt! to transmit any bytes following the
    CT command.  The CT command accepts X variables when used  in
    a loop.

CW <num>  Wait for  <num> bytes.  This command will allow  GetIt!
    to  wait for <num> bytes before proceeding to  next  command.
    This allows you to prompt for a file using the CT command and
    then wait for a casio acknowledge using the CW command. The CW
    command  "throws" away <num> bytes - you don't  save  the
    response  anyway.

CR Get CASIO dump.
    This  command  prepares GetIt! for a CASIO dump.   All  bytes
    received  through the MIDI in port are saved.  This  includes
    All  MIDI information so don't press any notes or it will  be
    saved too. Command terminates when it receives $f7.

CS  Save CASIO dump.
    This command saves the CASIO dump that you have received.

NOTE:
Do not mix non-casio commands within the OPENCASIO and CLOSECASIO
parts of your scrips.
CAUTION:
 You need to be very careful in CASIO mode when using the CW  and
CR commands.  In interest of speed, these routines will wait  for
until  they  get what they are expecting. They do not  check  for
keypresses.   When  you set CW to wait for <num> bytes,  it  will
wait there until you send the required number of bytes.  Likewise
with CR mode - it will wait until it gets an $f7.(end of sysex)


5) SEQUENCER MODE: GetIt s

GetIt! is also a simple MIDI sequencer. To start, just type
"GetIt s" on the command line and GetIt! will display an 8  track
sequencer. Type 'h' for help, 'q' to quit.

6)  FILE  PROCESSES  MODE:
GetIt  f  [h,s]  <infile>  <outfile> <strip/header file>

GetIt! can perform processes on binary files, adding or  removing
bytes from the beginning of a file and the end.
Basically, system exclusive data is required to start with a  $f0
and  end  with  an  $f7.  What comes in  between  is  up  to  the
manufacturer  of the MIDI device.  Usually the  system  exclusive
file has $f0 <manufacturers id> <etc.> header bytes *before*  the
actual  voice  data  starts.

Some  librarians remove and store system data without the  header
bytes,  only storing the voice data. When they send the  data  to
the  MIDI device, they add in the headers when sending  the  data
back.  GetIt! usually stores data with the header/footer bytes so
that  sending a file is quick and easy.  Nonetheless, GetIt!  can
convert files between the two standards.



HEADER FILES:

To  add bytes to the beginning of a system file (headers) and  to
add  bytes  to the end (footers), create a header  file  and  run
getit with these parameters:

GetIt f h <infile> <outfile> <header file>

The infile is the system exclusive file without the header/footer
bytes. Outfile is the new file containing the header/footer bytes
that you added. Header file is a ascii file containing two lines.
The first line contains the header bytes to add to the  beginning
of the outfile. The second line contains the footer bytes to  add
to the end of the outfile.



Example:   to add $f0 $43 to the beginning of a system  exclusive
file and $f7 to the end of a system exclusive file:

Create a header file with the two lines.

$f0 $43
$f7

The first line contains the header bytes to add to the  beginning
of  the new file.  The second line contains the footer  bytes  to
add to the end of the new file.

STRIP FILES:

Getit f s <infile> <outfile> <strip file>

GetIt!  can  also strip bytes off of the beginning  and  ends  of
files.  This  command is used to convert plain  system  exclusive
files containing headers to the format that some librarians use -
omitting the header/footer bytes.

To  strip  bytes off of a system exclusive file, create  a  strip
file  with  two  lines.  The first  line  contains  the  starting
position  to write from, the second line contains the  number  of
bytes to truncate off of the end of the file.

Example: To strip off the first byte and last byte of a file:

Create a strip file with these parameters:

2
1

The first line contains the starting byte position to write from,
in  this  case write from the 2nd byte of the file.   The  second
line contains the number of bytes to truncate from the end of the
file, in this case strip one byte off of the end of the file.



To  strip off only the first byte and leave the rest  alone,  use
these parameters:

2
0   <- no bytes stripped out.

To  strip  off only the end and leave the  beginning  alone,  use
these parameters.

1 <- write from first byte - leave alone.
1 <- strip off one byte off end.















ROUTINES FOR GETIT!

GetIt!  uses  the  TurboMIDI  toolkit,  available  from   N-FOCUS
Technologies.  TurboMIDI  allows you to  write  MIDI  librarians,
Simple MIDI sequencers, MIDI mappers, Ear training programs,  and
MIDI  utilities like GetIt!. TurboMIDI requires Turbo Pascal  5.0
from Borland International. The source for several MIDI  programs
are  included  free  with the TurboMIDI toolkit and  an  8  track
simple  sequencer  that  you can use in  your  own  applications.
Source code for TurboMIDI will be available at a future date.

HERE IT COMES:
Yes, GetIt! is a MIDI SHAREWARE utility, and the author <me>
requests that if you like and use GetIt! and find it useful
please send a $20 donation.

Regarding my Shareware thoughts:

 If you like GetIt! (I hope you do), please send the $20 amount.
Almost  anyone should be able to "scrape" up the $20  amount.  If
you  can afford a MIDI device, then you can pay for  GetIt!.   If
you truly cannot pay for GetIt!, then just send me a note telling
me so and you will be added to the registered users list  anyway.
When  you  can pay for GetIt! I will expect  you  to  contribute.
Please do give copies of GetIt! to anyone and everyone! I want to
make  GetIt! a useful utility, let me know what improvements  you
would like to see. GetIt! is *not* public domain and is
not free.


If you donate, you will receive notices of future
updates and additional documentation for future GetIt! versions.
You will also be helping the program progress by making it
possible for me to spend some more time on GetIt!
You also get peace of mind, everytime you receive a system
transfer from your MIDI device :-)
Please send donations to:
                  Aron Nelson
                  N-Focus Technologies
                  1800 Stokes St. #197
                  San Jose,CA 95126














                        Software License




Getit.exe    MIDI Librarian.
Getit20.exe  MIDI Librarian/File utility.
Getit25.exe  MIDI Librarian/File utility.
GetIt30.exe  MIDI Librarian/Peek/Sequencer.
GetIt.exe    version 3.5 MIDI Librarian/Peek/Sequencer.


You are free to use, copy and distribute Getit! for
NONCOMMERCIAL use if:

**  No fee is charged for use, copying or distribution.
**  It is not modified in any way.

Clubs  and  user groups may charge a nominal fee  not  to  exceed
($10) for expenses and handling while distributing Getit!.
Site  licenses and commercial licenses for Getit! are  available.
Write  N-Focus  Technologies  for  more information.























                           DISCLAIMER


N-Focus Technologies hereby disclaims all warranties relating  to
this  software,  whether express or  implied,  including  without
limitation  any implied warranties of merchantability or  fitness
for a particular purpose. N-Focus Technologies will not be liable
for  any special, incidental, consequential, indirect or  similar
damages due to loss of data or any other reason, even if  N-Focus
Technologies or an agent of N-Focus Technologies has been advised
of  the possibility of such damages.  In no event  shall  N-Focus
Technologies's  liability for any damages ever exceed  the  price
paid  for the license to use software, regardless of the form  of
the  claim.  The person using the software bears all risk  as  to
the quality and performance of the software.




Governing Law:


This  state shall be construed, interpreted, and governed by  the
laws of the state of California, as well as those implications
made by the Federal copyright laws.









TradeMarks:


Turbo  Pascal  4.0  and  Turbo Pascal 5.0  are  a  trademarks  of
Borland,  MPU-401  is a trademark of Roland Music, IBM  PC  is  a
trademark of IBM Inc.


















-------------------- CHANGES ------------------------------------


Getit  3.5  adds  extended  commands  to  the  script  language.
Extended commands are 2 letter commands such as TR and BS.
Extended commands  facilitate  sending  libraries   w/o   header
information.


03/04/89
Fixed bug when MIDI system commands were sent while recording.
Disabled Control-C.
Added 8 track sequencer.
Added transmit menu.
Fixed bug when decimal was selected in peek mode.
03/05/89
Added help to 'f' parameter.
Added Log to disk for peek mode.
Changed thanks notice.
Added IO checks for all file IO.
Added  help displays when partial parameters are entered  on  the
command line.
Added 60 character capability to log file string.
Added CASIO mode.
Added transmit modes in script commands.
Removed $ff requirement on transmit.
Changed  name  of  exe back to GetIt so that  the  shell  can  be
used for upcoming version.