OS/2 Shareware BBS: Multimed/Multimed.zip/x2midi.zip/x2midi/x2midi.doc

Text File | 1995-08-24 | 13KB | 242 lines

 X2Midi

 Please read this document in entirety.  I took the time to make it explicit, clear, and very useful.  It took me
 longer to write it than it will ever take you to read it.  Therefore, you owe it to both of us to read it.  OK?

 X2Midi is an OS/2 2.X command line application that extracts System Exclusive data from a MIDIEX data file (in
 Ascii or raw, binary format) and resaves that data in a standard MIDI file.  Such a MIDI file can then be loaded
 into, and "played back" by, any sequencer that supports System Exclusive data and the MIDI file format.

 Some librarian and patch editing utilities (and even some sequencers) save System Exclusive data in a raw,
 binary dump, or Ascii (ie, a text file that you can load into a text editor and visually see the System Exclusive
 data values such as F0 41 39 etc).  This is not really a standard file format for music use.  The MIDI file format
 is the de facto standard for storing MIDI data, including System Exclusive data.  X2Midi makes it possible to
 convert data files made by such utilities into a more standard format to be used with a greater number of
 programs.

 This is version 1.0.


COPYRIGHT

 This OS/2 Online Book and the related file, X2MIDI.EXE are all copyright 1995 by Jeff Glatt.  These files are
 freely redistributable, and may be used by and distributed along with any software, be it commercial or
 otherwise, provided that these files are not internally modified, nor specifically sold as a complete product by
 themselves.  The only price that you have to pay is the one that you're already paying by spending all of your
 time in front of a computer instead of developing healthier outlets.

 NOT SO STANDARD DISCLAIMER:

 These programs are provided "as is" without warranty of any kind either expressed or implied or tatooed in a
 place that only a few people have ever seen, including but not limited to the implied warranties of
 merchantability, fitness for a particular purpose, and the dubious assumption that the software has been created
 by a sane individual who would never do anything that may hurt you. The entire risk as to the results and
 performance of the programs is assumed by you or someone who looks exactly like you.  Jeff Glatt does not
 guarantee that the functions in these programs will meet your requirements, especially if your requirements
 involve lots of latex and some docile, domesticated animal.  Nor does Jeff Glatt warranty the programs to be
 uninterruptable or error-free, although mercifully free of "General Protection Faults".  If you use said programs,
 you can not say anything nasty about the author, even if the programs inadvertently cause the erasure of your
 collection of X-rated GIFs of a conservative, overweight and overrated TV "personality" plooking himself vigorously
 with his royalty checks from some rancid paperback.  Jeff Glatt is not responsible for any damages as a result
 of anything that he has done, or hasn't done, or was supposed to do but never got around to it, and furthermore,
 he doesn't even care so leave him alone, ratface.  You may have more or less protections in certain states of
 the union, depending upon how far your local politician is willing to bend over for some bribe from a business
 lobbyist.  Just remember that Jeff Glatt has no money, so don't bother suing him as a result of any damages
 caused by this OS/2 program.  Tell your greasy lawyer to go after IBM, and make sure that you pick 12 really
 stupid pinheads for the jury.    If swallowed, induce vomiting immediately by contemplating the asthetics of
 Microsoft Windows.

 OS/2 is a trademark of International Business Machines Corporation.

 Windows is a trademark of Microsoft Incorporated, and furthermore, Bill Gates is to blame for it.

 If you have suggestions, comments, criticisms, and anything else other than dollar bills, then send them to
 someone else because you got it for free, and you know what you get for nothing?  But, if you do need to
 contact the author, then either phone some of the more prominent psychiatrict clinics in central New York state,
 or try this:

 Jeff Glatt
 6 Sycamore Drive East
 New Hartford, NY 13413
 [phone]


SYNTAX

 X2Midi runs in an OS/2 Command Prompt Window.    The syntax is as follows:

 X2MIDI [/A /Txxx /Pxxx /Mxxx] MIDIEX_filename [MIDI_filename]

 The items in brackets are optional.  Any, all, or none of these may be specified or omitted.  Options are
 preceded by a / character.  These can be placed anywhere (ie, after the source and destination filenames,
 inbetween the filenames, etc).  The destination filename (ie, MIDI_filename) is optional, but if specified, it must
 be somewhere after the source filename (ie, MIDIEX_filename).

 The arguments are:

 MIDIEX_filename      The name of the original MIDIEX file (that X2Midi is going to read).    Running X2Midi
              without supplying any filename results in X2Midi simply printing out its help template.

              Note:  If you need to convert MIDIEX files that contain MIDI messages besides System
                 Exclusive, then you need to use another conversion utility.  X2Midi extracts only
                 System Exclusive messages.


 MIDI_filename          The name of the new MIDI file that you want X2Midi to create.  If you don't supply this,
              then X2Midi overwrites the original file.

 /A              The original MIDIEX file is ascii text (ie, not a raw binary).  When you look at an ascii text
              file in a text editor, you should see the numerals 0 to 9 and letters A to F used to list the
              data values.    For example, you'll typically see F0 as the first data value in the file.  If the
              original file is ascii, then you need to inform X2Midi of this in order for it to create a
              proper MIDI file conversion.    On the other hand, if you look at a raw binary file in a text
              editor, you'll typically see lots of weird, graphical characters that seem to make no sense
              at all to a human.  Unless you tell X2Midi that the original file is ascii (by specifying the /A
              option), then X2Midi assumes that it is raw binary.

 /Pxxx              Set the Pulses Per Quarter Note, and xxx is the resolution.  Set this to the same clock
              resolution as the sequencer that will play back the file.  For example, if the sequencer has
              96 ppqn resolution, then specify /P96.  If you don't specify Pulses Per Quarter Note, X2Midi
              assumes 96 ppqn.

 /Txxx              Set the Tempo, and xxx is the tempo in Beats Per Minute.  Set this to the same tempo as
              you intend to use upon the sequencer that will play back the file.  For example, if you
              intend to use a tempo of 120 BPM, then specify /T120.  If you don't specify Tempo, X2Midi
              assumes 120 BPM.

 /Mxxx              Set the time inbetween System Exclusive messages, and xxx is the time in milliseconds.
              For example, if a certain MIDI unit requires that there be 40 milliseconds inbetween each
              received System Exclusive message, then specify /M40.  This time is added to the amount
              of time that it takes to transmit each System Exclusive message (contained in the original
              file) over MIDI.  If you don't specify a time delay, X2Midi assumes 40 milliseconds, which
              is what Roland non-handshaking transfers usually require.


 It's important to set Pulses Per Quarter Note and Tempo to the values that you intend to use upon the sequencer
 playing back that MIDI file.  (When the sequencer loads the MIDI file, it should automatically set itself up to that
 specified Tempo, and probably clock resolution as well).  If you subsequently speed up the Tempo or increase the
 clock resolution, the timing inbetween System Exclusive packets will be shortened such that the MIDI unit may no
 longer have the amount of delay inbetween packets that it expects, and the sequencer may send the data too fast
 for the MIDI unit to process, resulting in a bad transmission.

 Note:    It doesn't matter if you use lower or upper case on the options (ie, /A or /a).


ERRORS

 Here are the possible error messages that you may see.  Following each message is a description of likely
 causes for that error and possible remedies.

 When X2Midi finally terminates, it returns an Error Result (ie, number) to the OS.  A 0 returned value indicates
 that the operation was a success.  Non-zero values are errors.  Note that this is returned in the REXX special
 variable RC when calling X2Midi from a REXX script.


Can't open source file!
 Synopsis    A MIDIEX file, that you asked X2Midi to convert to MIDI file format, didn't open.

 Cause        The filename that you specified is incorrect.
 Cure        Check the filename that you entered.  Did you specify some directory and file that exists?

        Note:  X2Midi does not support wildcards.

 Cause        Some other program has this filename currently in use, and is preventing X2Midi from reading it.
 Cure        Make that other program close this filename.

 Result     Any of the possible errors from DosOpen().


Can't determine size of source file!
 Synopsis    X2Midi needs to determine the size of the source file in order to read it into memory and perform
        the conversion process.  X2Midi needs OS/2 to be able to return information about the file.

 Cause        For some reason, OS/2 didn't give X2Midi the requested information.
 Cure        Shut down other apps, or OS/2 itself, and try X2Midi again.  Some other app may have interferred
        with the proper reading of the file.

 Result     Any of the possible errors from DosQueryFileInfo().


Can't allocate memory to read source file!
 Synopsis    X2Midi needs to allocate memory in order to read in the entire file and perform the conversion
        process.  X2Midi needs OS/2 to fulfill its request for that memory block.

 Cause        For some reason, OS/2 didn't fulfill X2Midi's memory request.
 Cure        Check that you're not trying to convert a file that is larger than the sum total of your RAM and swap
        file size.  This could be the case if the MIDIEX file contains a waveform dump of an extremely large
        waveform.

        If it's a problem that other running apps have used up too much RAM and swap space to load the
        MIDIEX file, then shut down other apps, or OS/2 itself, and try X2Midi again.

 Result     Any of the possible errors from DosAllocMem().


Bad read of source file!
 Synopsis    While loading a MIDIEX file, that you asked X2Midi to convert to MIDI file format, an error was
        encountered.

 Cause        The file is corrupt.
 Cure        Use a backup copy of the file.

 Result     Any of the possible errors from DosRead().


Bad sysex packet! This is not a MIDIEX file, or is corrupt.
 Synopsis    While converting a MIDIEX file, X2Midi discovered an inconsistancy with what it would expect to find
        in such a MIDIEX file, indicating that the file is damaged, or not really MIDIEX format.

 Cause        The file is corrupt.
 Cure        Use a backup copy of the file.

 Cause        The file is ascii text, but you didn't specify the /A option.
 Cure        Redo the conversion, specifying the /A option.

 Cause        The file is in some other format other than a MIDIEX ascii or raw binary format.  In other words, it
        appears to contain more than just MIDI data values (ie, possibly file headers or other data).
 Cure        Use another file conversion program to convert this file to MIDI format.

 Result     RC = -1


No System Exclusive packets contained within this file!
 Synopsis    While converting a MIDIEX file, X2Midi encountered no System Exclusive data within the file.
        X2Midi extracts only System Exclusive data, and ignores all other MIDI data.

 Cause        Your MIDIEX data file contains no System Exclusive data.  If the file is a text file, you can check
        that it contains System Exclusive data by loading it into a text editor and checking to see if it
        contains data values of F0 followed by F7.
 Cure        There's nothing that X2Midi can do with a MIDIEX file that doesn't contain System Exclusive dumps.

 Result     RC = -2


Can't open destination file!
 Synopsis    The new MIDI file, that you asked X2Midi to create, didn't open.

 Cause        The filename that you specified is incorrect.
 Cure        Check the filename that you entered.  Did you specify some directory that doesn't exist?  X2Midi
        only creates files; not new directories.

 Cause        Some other program has this filename currently in use, and is preventing X2Midi from writing to it.
 Cure        Make that other program close this filename.

 Cause        The file exists, but although you agreed to overwrite it, it has its READONLY bit set, so X2Midi can't
        overwrite it.
 Cure        Use OS/2's ATTRIB command to turn off the READONLY status of this file.

 Cause        You chose to save data upon some media that is write-protected.
 Cure        Remove the write-protection.

 Result     Any of the possible errors from DosOpen().


Bad write to destination file!
 Synopsis    In saving a new MIDI file, X2Midi encountered an error writing the data to the file.

 Cause        The media is full.
 Cure        Make sure that there is enough room on the media to contain the new MIDI file that X2Midi creates.
        X2Midi doesn't predict required space before converting the data, so use your own judgment.

 Result     Any of the possible errors from DosWrite().