Saves a MIDI file (loaded into RAM by MIDIOpenFile), and any changes made to it, to disk.
Synopsis
message = MIDISaveFile(filename)
Args
filename is the desired name of the MIDI file on disk.
Returns
If success, an empty string is returned (""). If an error, an error message is returned.
Notes
If you call MIDISaveFile() before calling MIDIOpenFile() to load/create a file in RAM, then a REXX SYNTAX condition is raised. CONDITION('E') returns error number 40.1 and CONDITION('D') returns the message DLL function "MIDISSAVEFILE" reported MIDI file not yet loaded!.
If you omit the filename, or pass an empty string, a SYNTAX condition is raised. CONDITION('E') returns error number 40.5 and CONDITION('D') returns the message Missing argument in invocation of "MIDISAVEFILE"; argument 1 is required.
If you set the MidiErr variable to raise a condition, then any MIDISaveFile() 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 MIDISaveFile()). Possible error numbers/messages include:
Number Message Causes 1 Can't open the MIDI file to save! There's an existing file and it's write protected. The disk is full or write-protected. Some other running program has a file by that name open and is denying access to it. 5 Had an error while saving the MIDI file! The disk is full. 7 Had an error seeking through the file! The media may be defective, such as a bad floppy disk.
If you do not set MidiErr, then any one of above error messages may be returned by MIDISaveFile().
Any disk file with the same name is automatically overwritten without prompting, so you may wish to first use the REXX built-in function QUALIFY() to check if there is already an existing file with the same name.
MIDISaveFile() does not remove the MIDI file from RAM. So additional changes can be made to it.
Examples
/* Save a MIDI file named "blort.mid" on disk */ err = MIDISaveFile("c:\mydir\blort.mid") IF err \== "" THEN SAY "ERROR saving c:\mydir\blort.mid:" err /* Use ERROR condition to trap errors */ DO MIDISaveFile("blort.mid") CATCH ERROR CONDITION('M') END