Meeting Pearls 3

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

/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / midi / Editors_and_Tools / OberSuite-1.03 / OberSuite.DOC < prev next >

Wrap

Text File | 1993-01-23 | 24KB | 741 lines

O B E R S U I T E ================= This documentation file was last revised on: January 23, 1993. OberSuite is a set of CLI programs for transferring patches between your Amiga and an Oberheim Xpander or Matrix-12 synthesizer via MIDI. Author: Daniel J. Barrett 62 Summer Street Amherst, MA 01002-1122 E-Mail: Internet: barrett@cs.umass.edu Compuserve: >internet:barrett@cs.umass.edu If you like these programs, you are welcome to send a financial contribution to the author, but it is not necessary. No Copyright: The source code and executable programs for ObGet 1.03, ObPut 1.03, ObExtract 1.03, and ObType 1.03 are all in the PUBLIC DOMAIN. Please share them with other people! You are welcome (and encouraged) to use the source code, in whole or part, in your own programs. If you do, I ask that you please give me credit for my work. This is not necessary, but it is a polite thing to do. Copyright: All versions before 1.00 ARE copyrighted: Copyright 1991 by Daniel J. Barrett. All rights reserved. and MAY NOT BE DISTRIBUTED without the author's WRITTEN permission. These are incomplete, buggy pre-release versions! If you have a copy with version number earlier than 1.00 (for example, 0.85 or 0.9), I encourage you to get a more recent version. Disclaimer: These programs are provided without warranty or guarantee of any kind. Use them at your own risk. The author bears no responsibility for any damage done or data lost due to the use or misuse of these programs. I have used these programs successfully and believe that they are helpful and reliable. Otherwise, I would not distribute them! A QUICK INTRODUCTION FOR EXPERTS -------------------------------- If you are a Amiga MIDI expert, and you don't feel like reading this documentation (yet), here's a quick way to get started. From the CLI, type the name of the program (any of them) followed by a question mark. You will see usage information for that program. The programs are called ObGet, ObPut, ObType, and ObExtract. If your MIDI interface is not connected to your Amiga's internal serial port, read "Using An Alternate MIDI Interface," below. I do recommend that you read this entire document at some point. TABLE OF CONTENTS ----------------- I. What are the programs? II. Features. A. General use B. Getting help C. Examples III. Detailed usage instructions. A. Some Conventions B. Using Command-Line Options C. ObGet D. ObPut E. ObType F. ObExtract G. Using an alternate MIDI interface IV. HELP!!! The programs don't work! V. Technical details about the programs. A. Reliability. B. Programming considerations. C. Source code. VI. Changes from previous versions. WHAT ARE THE PROGRAMS? ---------------------- These are programs for transferring patch data between an Oberheim Xpander/Matrix-12 and a Commodore Amiga. You need a MIDI interface on the Amiga. If you don't have all these things, these programs are probably not useful to you (except perhaps as a C source code example). ObGet: Get patches from an Xpander/Matrix-12 and store them in a file. You can grab: o 1 single patch o 1 multi patch o All single patches (100) o All multi patches (100) ObPut: Send patches from a file to the Xpander/Matrix-12. The "opposite" of ObGet. ObType: Identify the contents of files created by ObGet. ObExtract: Extract individual patches from files created by ObGet, and: o Store them in individual files. o Send them to the Xpander/Matrix-12. o Both of the above. FEATURES -------- GETTING HELP: o Typing the program name by itself prints a short "help" message. For example: 1> obget o Typing the name of the program followed by a QUESTION MARK prints a long, informative "help" message. For example: 1> obput ? o To quit any OberSuite program, type control-C (hold down the CTRL key and press C). In some situations, you might also have to press RETURN afterwards. GENERAL USE: o Programs run from the command-line only, not the Workbench. o Patches may be transferred 1 at a time or 100 at a time. o All programs make no changes to the patch data. Whatever they receive from the Oberheim is exactly what is stored in the file. This makes the files most compatible with other MIDI software, at the expense (perhaps) of greater flexibility within the OberSuite programs. o You don't have to touch the Xpander/Matrix-12 front panel during operation. o The programs automatically distinguish between Xpanders and Matrix-12's and adjust their behavior accordingly. o All programs access the serial port (or other MIDI device) in "shared" mode, so other MIDI programs can be active simultaneously. o By default, the programs assume that your MIDI interface is connected to your Amiga's internal serial port. You may override this by specifying an environment variable (using the AmigaDOS SetEnv command). o Transfer speed can be increased by 25-30% by turning off screen output (-q or -Q options). EXAMPLES The file "EXAMPLES", included with this distribution, contains many samples of using the OberSuite commands. DETAILED USAGE INSTRUCTIONS --------------------------- SOME CONVENTIONS Below, I will explain the syntax of the OberSuite programs. In doing so, I will use the following conventions: o "1>" is the CLI/Shell prompt. o When I want to indicate an OPTIONAL piece of syntax, I will enclose it in square brackets, like this: [optional thing] For example, the syntax description: ObWhatever [Patch] Filename would indicate that the first argument "Patch" is optional. USING COMMAND-LINE OPTIONS All of the OberSuite programs use command-line options to affect their behavior. These options are single letters preceded by a dash. Command-line options may be specified individually, like this: 1> ObWhatever -a -b -c -d ... or together after 1 dash, like this: 1> ObWhatever -abcd ... OBGET ObGet will grab 1 or 100 patches from the Oberheim and save them in a file. Here is an example: 1> obget s45 trumpet This grabs single patch 45 and saves it in a file called "trumpet" in the current directory. If you wanted multi patch 45, the "s" would have been an "m": 1> obget m45 trumpet To grab ALL 100 multi patches and save them in a file called "Hundred-Multis", type: 1> obget m Hundred-Multis The general syntax is: 1> ObGet [options] Patch FileName "Patch" begins with the letter "s" (for single) or "m" (for multi). (You may use upper or lower case letters.) If you follow the letter with a number, ObGet grabs that particular patch. If you omit the number, ObGet grabs ALL 100 patches of that type. Options are: -q Quiet; no screen output except for error messages. -Q COMPLETELY quiet -- not even error messages. -l Long screen output. This is the default. -a Overwrite existing files without asking your permission (as if you had typed "All" at the "Overwrite?" prompt). You may not specify -q, -Q and -l together. "Quiet" transfers are about 25% faster than "long" transfers. If you want "Quiet" to be the default, you can always make an alias: 1> alias ObGet ObGet -q If you attempt to save a patch in a file that already exists, ObGet will ask you if you want to overwrite the existing file. File "trumpet" already exists. OVERWRITE it? [Yes/No/All, RETURN=No]: Any response beginning with capital or small "Y" or "A" ("all") means "yes"; anything else means "no". [The "A" might seem strange, but it useful when multiple files are being created, as in ObExtract, below.] NOTE: You will not be prompted like this if you have specified the "-a" option on the command line. Thus, for a totally quiet (and perhaps dangerous) program, you would specify both the -Q and -a options. OBPUT ObPut is the opposite of ObGet: it sends patch data from a file (presumably created by ObGet) back to the Oberheim. Its syntax is slightly different from that of ObGet: you don't have to specify whether a file is a single patch or a multi patch. (The Oberheim can tell the difference.) Thus, you don't put an "s" or "m" before the patch number. For example, suppose you have a multi patch in the file "Zappo", and you want to send it to patch location 65 in the Oberheim. Type: 1> obput 65 Zappo The general syntax is: 1> ObPut [options] [PatchNumber] FileName Note that the PatchNumber is OPTIONAL. This because every patch file has its ORIGINAL patch number contained inside it. So, if you want to send a patch back to its original patch location, just omit the patch number on the command line: 1> obput Zappo [If you want to see a file's original patch number, use ObType.] If the file contains 100 patches, once again you omit the Patch Number -- it has no meaning. (However, if you accidentally type a number, ObPut will ignore it.) 1> obput HundredPatchFile When ObPut is successful, it prints the name of each patch as it is sent to the synthesizer. Options are mostly the same as in ObGet: -q Quiet; no screen output except for error messages. -Q COMPLETELY quiet -- not even error messages. -l Long output. This is the default. You may not specify -q, -Q and -l together. Using -q or -Q speeds up transfer speed about 25%. OBTYPE ObType identifies the Oberheim patch data contained a file (or several files). The usage is: 1> ObType [options] File1 File2 File3 ... There are 4 different output formats for ObType. I have chosen what I consider to be the "most useful" format as the default. Here are 3 of the 4 formats: -s Short output. -m Medium output. (The default.) -l Long output. SHORT output prints only the patch name(s), one per line. This is most useful, perhaps, when the output of ObType is meant to be processed by another program, or perhaps a Shell script or ARexx script. Example: 1> obtype -s MyFile TRUMPET6 MEDIUM output prints the name and number of each patch in (what the author considers) a "useful" format. If a file contains 1 multi patch, the numbers of its component single patches are printed as well. If a file contains 100 patches, their names and numbers are printed in 20 columns of 10 each (fits on a full-size screen). THIS MODE IS THE DEFAULT. Example: 1> obtype MyFile Xpander/Matrix-12 single patch 12: TRUMPET6 LONG output prints the filename as well as the patch names and numbers. All output is 1-patch-per-line. This mode is most useful when you specify multiple files on 1 command line. 1> obtype -l MyFile AnotherFile File MyFile: Xpander/Matrix-12 single patch 12: TRUMPET6 File AnotherFile: Matrix-12 multi patch 71: BLAATT The fourth format option is: -q Quiet; no screen output except for error messages. Why in the world do you want "no output" from a program that is DESIGNED to do nothing but give output? Simple -- you can use it for verifying the integrity of the data in the file. If the data is OK, then you will see an error message; otherwise, nothing is printed (the data is OK). Note that ObType has no -Q (totally quiet) option -- it really makes no sense to have one. It would cause ObType to have absolutely no function whatsoever. OBEXTRACT Suppose you have a 100-patch dump in one file, and you want to send only SOME of these files to the Oberheim? Or what if you want to save SOME of the patches in individual files? This is the purpose of ObExtract. For example, to send patches 2, 6, 7, 8, 9, and 14 from file HundredPatches to the Oberheim: 1> ObExtract -o 2 6-9 14 HundredPatches Or you could extract these patches and save them in individual files: 1> ObExtract -f 2 6-9 14 HundredPatches In this case, assuming that "HundredPatches" contains multi patches, ObExtract would save the individual patches in files named: HundredPatches.M02 HundredPatches.M06 HundredPatches.M07 HundredPatches.M08 HundredPatches.M09 HundredPatches.M14 If you prefer, you may choose to name these files with the ACTUAL PATCH NAMES contained in the data. In the above example, the file names might have come out like this: trumpets.M02 baboons.M06 string_1.M07 string_2.M08 _drums.M09 squilch.M14 In general, when you use ObExtract, you must answer 3 questions: (a) Which patches do I want to extract? (b) Where do I want them to go -- to the synth, to individual files, or both? (c) If the patches are being extracted to individual files, what should those file names be? We will see below how to answer these questions. The general syntax of ObExtract is: 1> ObExtract [options] PATCH [PATCH...] HundredFileName The MANDATORY options (yes, I know that is paradoxical) are: -f Save data in individual files. -o Send data directly to the Oberheim. You MUST specify at least one of these options. You may even specify both; this sends the data both to the Oberheim and individual files. The other "optional" options are: -a Overwrite existing files without asking your permission (as if you had typed "All" at the "Overwrite?" prompt). May be used ONLY with the -f ("file") option. -r Use "real names" for patch files. May be used ONLY with the -f ("file") option. -q Quiet; no screen output except for error messages. -Q COMPLETELY quiet -- not even error messages. -l Long output. This is the default. Now let's see how to answer the 3 questions (a)-(c) that we described above. (a) Which patches do I want to extract? ------------------------------------------- After the options, you must specify one or more PATCH values. These values can be either: o A single number between 0 and 99, inclusive; or, o A range of numbers like 34-67 or 10-1. Ranges may be increasing (like 1-10) or decreasing (like 10-1), and are allowed to overlap. Even crazy lists of ranges like this are OK: 1> ObExtract -f 2-5 99 17-4 54-54 25-80 HundredPatchFile ObExtract will figure out that you mean patches 2-17, 25-80, and 99. For example, let's send patches 43 to 76 to the Oberheim, using Quiet output. Here are several EQUIVALENT ways to do it: 1> ObExtract -q -o 43-76 MyHundredPatchFile 1> ObExtract -o -q 43-76 MyHundredPatchFile 1> ObExtract -o -q 76-43 MyHundredPatchFile 1> ObExtract -oq 50 75 43 44-76 MyHundredPatchFile Now let's extract all patches to individual file names: 1> ObExtract -f 0-99 MyHundredPatchFile (This may be a very slow operation if you are using floppies.) (b) Do I want them to go to the synth, to files, or both? ------------------------------------------------------------- This question is answered by using either the -f option for files, the -o option for Oberheim, or both. (c) What file names (if any) should be created? --------------------------------------------------- When extracting patches and saving them in individual files (-f option), ObExtract usually creates names for the individual files by concatenating: 1) The name of the 100-patch file; 2) A period; 3) The letter "S" or "M", for single or multi patch data, respectively; 4) The patch number, with a leading zero (like 03) if the patch number is 1 digit long. For example, if you extract single patch 8 from file Hundred, then it will be stored in the file "Hundred.S08". If you prefer, you can use the -r ("real names") option to make ObExtract use the actual patch name instead of the 100-patch-file name. In the above example, if single patch 83 were named "Brazz", then it would be stored in the file "Brazz.S83". When using -r, you should be aware that patch names are not converted exactly into filenames. Some characters that appear in patch names become very inconvenient when used in file names. Some examples are '#' and '?' (AmigaDOS wildcards), ':' (used in volume names), '/' (used for directories), and others. To avoid this problem, ObExtract converts any "unusual" patch name characters into underscore ('_') characters in the file name. Anything that is neither a letter nor a number is considered "unusual." In addition, ObExtract removes blank spaces (if any) from the end of the file name, and converts all letters to lower case. Here's an example of the conversions that -r does. If multi patch 35 has the true name (without the quotes; I include them so you can see the blank spaces at the beginning and end): " $ WOW! " As a file name, this becomes ___wow_.M35 Why? The first 3 characters become underscores, the exclamation point becomes an underscore, and the final space is stripped off. (d) Miscellaneous other facts about ObExtract ------------------------------------------------- If ObExtract is asked to overwrite a file that already exists, it prompts you: File "MyHundredPatchFile.S23" already exists. OVERWRITE it? [Yes/No/All, RETURN=No]: Any response beginning with "y" or "Y" means yes, and the file is overwritten. Any response beginning with "a" or "A" means all, and ObExtract will overwrite any other existing files without asking you first. Any other response means no. NOTE: You will not be prompted like this if you have specified the "-a" option on the command line. Thus, for a totally quiet (and perhaps dangerous) program, you would specify both the -Q and -a options. When -f is used, patches are extracted into your current directory. If you want the files to be created in another directory, first "cd" to that other directory, and then run ObExtract. For example, suppose the file HundredPatches is in RAM:, and you want the files to be extracted into the directory DF1:patches. 1> cd df1:patches 1> obextract -f 0-99 RAM:HundredPatches What happens if you use ObExtract on a file that contains only 1 patch? If you try to extract patch 0, it will work, essentially making a copy of the data. If you try to extract any other patch, ObExtract will print a message that it cannot find enough data. ObExtract can be used evade bad data in a 100-patch dump file. If a patch is bad (use ObType to figure this out), use ObExtract to send all OTHER patches to the Oberheim, and then use ObGet to save the 100 Oberheim patches in a new file. USING AN ALTERNATE MIDI INTERFACE By default, the OberSuite programs assume that your MIDI interface is connected to your Amiga's internal serial port. If this is not the case, you can override this by using an Amiga environment variable and the SetEnv command. (See your Amiga documentation for full details about SetEnv.) The name of the environment variable is OBERHEIM_DEVICE, and its value must be of the following format: 1) The name of the MIDI device driver, located in the DEVS: directory of your system disk. It should be something like "midi.device" or "serial2.device". 2) One colon character (':'). 3) The unit number for the device. If you have only 1 port using the device, your unit number is probably zero. Example: midi.device:2 Suppose you want to set up OberSuite to use unit 3 of the device "AltMidi.device". Type: 1> SetEnv OBERHEIM_DEVICE AltMidi.device:3 To check that the value was set correctly, type: 1> GetEnv OBERHEIM_DEVICE If you are using a MIDI interface attached to your internal serial, port, YOU MAY IGNORE ALL OF THIS STUFF. By default, OberSuite uses unit 0 of the device "serial.device". I cannot guarantee that OberSuite will work with whatever alternate device driver you choose. But I have tested the environment variable mechanism itself, and it works. HELP!!! THE PROGRAMS DON'T WORK! --------------------------------- I have tested these programs fairly well on my own equipment: Amiga 1000 running Kickstart/Workbench 1.3, Golden Hawk MIDI Gold interface, and a Matrix-12. If the programs don't work for you, first check: (?) On your Oberheim, do you have SYSTEMX turned on? If not, then the Oberheim will ignore incoming System Exclusive data (such as patch data and patch requests). Look on the MASTER/MIDI/ENABLES page and find the word SYSTEMX. It must be underlined. If not, then press the button below SYSTEMX to enable it. (?) Is your Oberheim's MEMORY PROTECT switch turned to "off"? If not, then the Oberheim will ignore incoming patch data. The switch is on the back panel. (?) Is the file "serial.device" in the DEVS: directory of your system disk? If not, most OberSuite programs will refuse to run, and you will see an error message like one of these: Cannot create a message port. Cannot create an extended I/O request. Cannot open the MIDI device. Cannot set the serial parameters. Boot your Amiga with an original Workbench disk and try again. (?) Are you running a version of the Amiga operating system that is older than 1.3? OberSuite should work with some or all earlier versions, but I have not tested this. Unfortunately, I do not have version 2.0 of the operating system, so I cannot test OberSuite under it. (?) Are your MIDI cables connected properly? Remember that MIDI OUT must always be connected to MIDI IN, and vice-versa. OBERHEIM COMPUTER -------- -------- MIDI IN <-------------------> MIDI OUT MIDI OUT <-------------------> MIDI IN (?) Are you using the program correctly? Double-check the instructions above. (?) Are you running another program that uses the serial port, such as a communications program, printing program, or another MIDI program? If so, this other program may be using the serial port. (OberSuite programs use the serial port in "shared" mode so they don't hog the serial port.) Exit your other programs and try again. If it still doesn't work, reboot to make sure that your other programs didn't accidentally leave the serial port "locked". Some programs allow you to "release" their hold on the serial port without exiting. (Example: Music-X.) This may be enough to allow OberSuite programs to run. (?) Are you running any other programs simultaneously with OberSuite programs? It is possible that a badly-written program could interfere with the operation of other programs. Boot your Amiga with an original Workbench disk and try again. (?) Is your synthesizer turned on? Seriously. This has happened to me. :-) If you are doing everything right, then there may be a bug in OberSuite. For example, the OberSuite programs should NEVER crash your Amiga. If you believe that there is a bug, please contact me (electronic mail is preferred). But first, try to reproduce the bug consistently. Can you find a particular set of actions, keystrokes, etc., that ALWAYS make the program crash? If you can, then I will be able to find the bug faster. TECHINCAL DETAILS ABOUT THE PROGRAMS ------------------------------------ RELIABILITY: o All programs may be exited safely by typing ^C (control-C). o If a patch transfer fails, it is retried up to 10 times before the program gives up. o All programs detect data errors to the fullest extent possible with these Oberheim synthesizers. (Which is not much, I'm afraid; the Oberheim does not transmit checksums to validate the data. I could request each patch twice and compare the results, but that would slow down the program by 50%. Maybe this will be an option in a later version of the program.) o Files are not created until after your data is verified. This means that you won't wipe out an existing file if a data transfer fails. o Existing files are not overwritten unless you give your permission. PROGRAMMING CONSIDERATIONS: o Files are read entirely into memory before they are processed, and patches are collected in memory before they are written to disk. This method results in much quicker operation (especially for users with floppy drives), but it uses more RAM. In the future, the programs may be smarter about their memory use. o Uses "asynchronous" MIDI input/output for friendly multitasking operation. SOURCE CODE: o Written in ANSI C. o Compiles under Manx Aztec C version 5.2a. o Version 1.03 is in the Public Domain. Other versions may also be in the Public Domain; check the source code itself to be sure.