 SDS2Wav

 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?

 SDS2Wav is an OS/2 2.X command line application that extracts MIDI Sample Dump Standard data (ie, a MIDI
 dump of a digital audio waveform from a MIDI sampler) from a MIDIEX data file (in Ascii or raw, binary format)
 or standard MIDI file and resaves that data in a standard WAVE file.  Such a WAVE file can then be loaded into,
 edited, and "played back" by any computer software that understands the WAVE file format.  SDS2Wav makes it
 possible to convert data files containing a MIDI dump of a waveform 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, SDS2WAV.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
 (315) 735-5350


SYNTAX

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

 SDS2WAV [/A] MIDIEX_filename [WAVE_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, WAVE_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 or MIDI file (that SDS2Wav is going to read).  Running
			  SDS2Wav without supplying any filename results in SDS2Wav simply printing out its help
			  template.

			  Note:  If you need to convert MIDIEX files that contain MIDI data besides MIDI Sample
				 Dump Standard (ie. SDS) data, then you need to use another conversion utility.
				 SDS2Wav extracts only SDS data.



 WAVE_filename		  The name of the new WAVE file that you want SDS2Wav to create.  If you don't supply
			  this, then SDS2Wav creates a new file whose name is the original file with the extension
			  .wav.  (ie, The original extension is stripped from the filename).

 /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 SDS2Wav of this in order for it to
			  create a proper WAVE 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 SDS2Wav that the original file is ascii (by
			  specifying the /A option), then SDS2Wav assumes that it is raw binary.  Don't specify
			  the /A option if the original file is a standard MIDI file.


 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 SDS2Wav 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 SDS2Wav from a REXX script.


Can't open source file!
 Synopsis	A MIDIEX file, that you asked SDS2Wav to convert to WAVE 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:  SDS2Wav does not support wildcards.

 Cause		Some other program has this filename currently in use, and is preventing SDS2Wav 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	SDS2Wav needs to determine the size of the source file in order to read it into memory and
		perform the conversion process.  SDS2Wav needs OS/2 to be able to return information about the
		file.

 Cause		For some reason, OS/2 didn't give SDS2Wav the requested information.
 Cure		Shut down other apps, or OS/2 itself, and try SDS2Wav 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	SDS2Wav needs to allocate memory in order to read in the entire file and perform the conversion
		process.  SDS2Wav needs OS/2 to fulfill its request for that memory block.

 Cause		For some reason, OS/2 didn't fulfill SDS2Wav'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 SDS2Wav again.

 Result 	Any of the possible errors from DosAllocMem().


Bad read of source file!
 Synopsis	While loading a MIDIEX or MIDI file, that you asked SDS2Wav to convert to WAVE 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 file is corrupt!
 Synopsis	While converting a MIDIEX or MIDI file that contains MIDI Sample Dump Standard data,
		SDS2Wav discovered an inconsistancy with what it would expect to find in such a file, indicating that
		the file is damaged, or not really MIDIEX or MIDI format, or not really a MIDI SDS transfer.

 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 or a standard MIDI
		file.  In other words, it appears to contain more than just MIDI data values, or is in another format.
 Cure		Use another file conversion program to convert this file to WAVE format.

 Cause		The file contains MIDI System Exclusive data that appears to be MIDI Sample Dump Standard data,
		but it isn't really, or is an incomplete dump.
 Cure		Use another file conversion program to convert this file to WAVE format.

 Result 	RC = -1


No SDS DUMP contained within this file!
 Synopsis	While converting a MIDIEX or MIDI file, SDS2Wav never found MIDI Sample Dump Standard data
		within the file.  SDS2Wav extracts only the System Exclusive messages that comprise a MIDI Sample
		Dump Standard transfer, and ignores all other MIDI data (including other System Exclusive messages).

 Cause		Your MIDIEX data file contains no MIDI Sample Dump Standard data.  If the file is a text file, you
		can check that it contains an SDS header (which SDS2WAV must be able to find).	This should
		begin with the data values of F0 and 7E, the third value should be 01, and the twenty-first value
		should be F7.  If the file is a standard MIDI file, use my MIDI Disassembler (ie, MF_DSM.EXE) to
		locate a System Exclusive message containing the above data values.
 Cure		There's nothing that SDS2Wav can do with a MIDIEX/MIDI file that doesn't contain SDS data.

 Result 	RC = -2


Can't open destination file!
 Synopsis	The new WAVE file, that you asked SDS2Wav 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?  SDS2Wav
		only creates files; not new directories.

 Cause		Some other program has this filename currently in use, and is preventing SDS2Wav 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 SDS2Wav
		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 WAVE file, SDS2Wav 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 WAVE file that SDS2Wav
		creates.  SDS2Wav doesn't predict required space before converting the data, so use your own
		judgment.

 Result 	Any of the possible errors from DosWrite().
