Opens and loads an existing MIDI file on disk into RAM, or creates a new, empty MIDI file in RAM.
message = MIDIOpenFile(filename, division)
Args
filename is the name of the MIDI file on disk. This will be loaded into RAM. If omitted, then a new, empty MIDI file is instead created in RAM.
If creating a new, empty MIDI file in RAM, then division is the desired timing resolution. A positive number indicates a pulses per quarter note (PPQN) resolution, for example 192 PPQN. For SMPTE timing, two numbers should be specified. The first number will be -24, -25, -29, or -30, corresponding to the 4 SMPTE standards representing frames per second. The second number (a positive number) is the resolution within a frame (ie, subframe). Typical values may be 4 (MIDI Time Code), 8, 10, 80 (SMPTE bit resolution), or 100. (You can specify millisecond-based timing by using the values of -25 and 40).
If omitted, then a default PPQN of 96 is used.
Returns
If success, an empty string is returned (""). If an error, an error message is returned.
Notes
If there is a problem allocating memory to load the MIDI file into RAM, then a SYNTAX condition is raised. CONDITION('E') returns error number 5 and CONDITION('D') returns the message System resources exhausted.
If you pass a division that is not numeric, a SYNTAX condition is raised. CONDITION('E') returns error number 40.5 and CONDITION('D') returns the message MIDIOpenFile argument 2 must be a whole number; found <arg> where <arg> is what you erroneously supplied.
If you set the MidiErr variable to raise a condition, then any MIDIOpenFile() error (other than the above) raises that condition. CONDITION('E') returns the error number and CONDITION('D') returns the error message (as normally returned by MIDIOpenFile()). Possible error numbers/messages include:
Number Message Causes 1 Can't open the MIDI file to load! There's no such existing file. Or, some other running program has that file open and is denying access to it. 2 Can't determine the MIDI file's size! The file may be corrupt. 3 Doesn't contain a MThd. Not a MIDI file! The file is not standard MIDI file format. 4 Had an error while loading the MIDI file! The file is corrupt. 6 This is a mal-formed MIDI file! The file is corrupt. 7 Had an error seeking through the file! The media may be defective, such as a bad floppy disk. The file may be corrupt. 8 Found misplaced running status! A poorly written MIDI file, or the file may be corrupt. 9 Found an undefined status in the MIDI file! The file is corrupt or a later version of the MIDIFILE DLL is needed. 70 RxMIDI track size limit is 524,288! RxMIDI can't handle a track with more than 524,288 bytes of data. 71 RxMIDI supports only 32 tracks! The current version of RxMIDI is limited to 32 tracks.
If you do not set MidiErr to raise a condition, then any one of the above error messages may be returned by MidiOpenFile().
Specifying division when loading a MIDI file from disk, forces the MIDI file in RAM to be reformatted with that resolution. (Not yet implemented).
Any previously loaded/created MIDI file is removed from RAM. (ie, RxMIDI works upon only one MIDI file in RAM at a time). So be sure to MIDISaveFile() any changes to a MIDI file in RAM before loading/creating another MIDI file.
By default, MIDIOpenFile() sets the first track as the currently selected track, as well as the only search track.
After a file is loaded/created. information can be obtained about it using MIDIGetInfo().
It is not necessary to close a MIDI file after it is opened. MIDIOpenFile() does that automatically after loading the file into RAM.
To free up any memory used by RxMIDI, without loading any file, simply create a new, empty MIDI file in RAM by calling MidiOpenFile without passing any args.
/* Open a MIDI file named "blort.mid" on disk. */ err = MIDIOpenFile("c:\mydir\blort.mid") IF err \== "" THEN SAY "ERROR opening c:\mydir\blort.mid:" err /* Create a new, empty MIDI file in RAM with 384 ppqn resolution. */ err = MIDIOpenFile(, 384) IF err \= "" THEN SAY "ERROR creating new file:" err /* Create a new, empty MIDI file with SMPTE-based, millsecond timing. */ err = MIDIOpenFile(, -25 40) IF err \= "" THEN SAY "ERROR creating new file:" err /* Use ERROR condition to handle errors. */ DO MIDIOpenFile("blort.mid") CATCH ERROR CONDITION('M') END