Sound Sensations!

home *** CD-ROM | disk | FTP | other *** search

/ Sound Sensations! / sound_sensations.iso / miditool / getit35 / getit.doc < prev next >

Wrap

Text File | 1989-03-05 | 21.3 KB | 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.