Alters the values (ie, time, channel, or data) of the currently selected event. Can also delete the currently selected event, a range of events, or an entire track. Can also insert a new event in a track.
Synopsis
result = MIDISetEvent(options, number)
Args
options specify what sort of operation to perform. It may be any combination of the following, each separated by a '|' character:
Option Meaning 'TIME' Set the currently selected event's time from the variables MIDIEvent.!Measure, MIDIEvent.!Beat, and MIDIEvent.!Clock 'CHAN' Set the currently selected event's MIDI channel from the variable MIDIEvent.!Channel. This is ignored for an event that has no channel. 'DATA' Set the currently selected event's data from the variable MIDIEvent.!Data1, and possibly MIDIEvent.!Data2, MIDIEvent.!Data3, etc. See.the event types to determine which Data variables need to be set prior to calling MIDISetEvent(). 'SORT' Sorts all events in the currently selected track according to their TIME 'DEL' Delete the currently selected event, or events within an excerpt in the currently selected track. 'MATCH' If 'DEL' of an On Note event, delete the matching Off or (Off) Note event, as well as all Aftertouch events inbetween for that note. Applicable only to a DEL operation 'CUT' Adjust the TIME of all events after the deleted excerpt to remove the "silence". Only applicable to DEL operation by TIME 'INS' Insert a new event at the end of the currently selected track 'AFTER' Insert the new event in the same track as the currently selected event, but place the new event after the currently selected event. Only applicable to an INS operation 'BEFORE' Insert the new event in the same track as the currently selected event, but place the new event before the currently selected event. Only applicable to an INS operation
If options is omitted, it defaults to 'TIME|CHAN|DATA'.
number is utilized only with the 'DEL' or 'INS' options. For DEL, it indicates how many events to delete starting at the currently selected event (or at the first event to delete if using a TIME excerpt). For INS, it indicates into which track to insert the new event (when not using BEFORE or AFTER option), where 1 is the first track.
Returns
If successful, then an empty string is returned. If an error, then an error message is returned.
Notes
If you call MIDISetEvent() 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 "MIDISetEvent" reported MIDI file not yet loaded!.
If there is a problem allocating memory to carry out the operation, 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 value for options which is not one of the allowable ones, then a REXX SYNTAX condition is raised. CONDITION('E') returns error number 40.28 and CONDITION('D') returns the message MIDISetEvent argument 1;, option must start with one of "<options>"; found "<badchoice>" where <options> are the allowable choices, and <badchoice> is what you erroneously passed.
If you set the MidiErr variable to raise a condition, then any MIDISetEvent() 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 MIDISetEvent()). Possible error numbers/messages include:
Number Message Causes 50 No currently selected event! You tried to edit the TIME/CHAN/DATA of the currently selected event, or insert a new event BEFORE/AFTER the currently selected event, but there is no currently selected event. 51 Can't insert after the End of Track! You can't insert a new event AFTER the currently selected event, when the currently selected event is an End of Track. 52 Unsupported event type! You tried to insert a new event with MIDIEvent.!Type set to an ID number/name not supported by this version of RxMIDI. 53 Begin time must be less than End time! When specifying an excerpt to delete by time, you specified a begin time that is not less than the end time. 54 Time is beyond the end of the track! When setting an event's TIME, you specified a time that is beyond the end of the track (ie, beyond the End of Track event's TIME). 55 MIDI channel must be a number from 1 to 16 inclusive! When setting an event's CHAN, you didn't specify a numeric value, or specified one that is not in the range 1 to 16 inclusive. 56 MIDI data byte must be a number from 0 to 127 inclusive! When setting an event's DATA, you didn't specify a numeric value, or specified one that is not in the range 0 to 127 inclusive. 57 Pitch wheel value must be a number from -8192 to 8191 inclusive! When setting a Pitch wheel event's DATA, you didn't specify a numeric value, or specified one that is not in the range -8192 to 8191 inclusive. 58 Song position must be a number from 0 to 16383 inclusive! When setting a Sng Position event's DATA, you didn't specify a numeric value, or specified one that is not in the range 0 to 16383 inclusive. 59 Seq # must be a number from 0 to 65535 inclusive! When setting a Seq # event's DATA, you didn't specify a numeric value, or specified one that is not in the range 0 to 65535 inclusive. 60 Chan # must be a number from 0 to 255 inclusive! When setting a Chan # event's DATA, you didn't specify a numeric value, or specified one that is not in the range 0 to 255 inclusive. 61 Port # must be a number from 0 to 255 inclusive! When setting a Port # event's DATA, you didn't specify a numeric value, or specified one that is not in the range 0 to 255 inclusive. 62 Bad tempo! When setting a Tempo event's DATA, you didn't specify a numeric value, or specified one that is 0 or greater than the allowed value. 63 Bad time signature! When setting a Time Sig event's DATA, you didn't specify a numeric value, or specified one that is not allowed. 64 Bad key signature! When setting a Key Sig event's DATA, you didn't specify a recognized key. 65 SMPTE values must be hour (0 to 23), min (0 to 59), sec (0 to 59) inclusive! When setting a SMPTE event's DATA, you didn't specify a numeric value, or specified one that is not allowed. 66 Time component contains non-numeric character! When specifying an event's TIME, you didn't specify a numeric value for the Measure, Beat, or Clock. 67 Time component can't be 0 or empty! When specifying an event's TIME, you specified 0 or an empty string for the Measure or Beat, or an empty string for the Clock. 68 Clock can't be larger than Timebase! When specifying an event's TIME, you specified a Clock value that is larger or equal to the MIDI file's Timebase. The value must be from 0 to one less than the Timebase. 69 End time not set! You forgot to set a required variable before calling MIDISetEvent(). 70 RxMIDI track size limit is 524,288! RxMIDI can't handle a track with more than 524,288 bytes of data.
If you do not set MidiErr to raise a condition, then any one of the above error messages may be returned by MIDISetEvent().
If specifying an event name (instead of number) for MIDIEvent.!Type when inserting a new event, only the first 4 letters need be supplied (ie, "On N" is the same as "On Note").
No error is reported if you attempt to delete the currently selected track, and there is no currently selected track. After the currently selected track is deleted, then there is no currently selected track.
You can't delete the End of Track event unless you delete the entire track. No error is reported if you attempt to delete the End of Track event itself -- the event is not deleted.
No error is reported if you attempt to delete a larger excerpt than there are actually events in the track, or if you attempt to delete an excerpt by TIME and no events happen to fall within that time.
If changing an event's time, the track is not resorted unless the SORT option is set. It is best to change all desired events' times before you finally do a SORT, and then after the SORT, call MIDITrack() again to reset the currently selected track/event.
When inserting an event, the track into which the event is inserted becomes the currently selected track, and the event inserted becomes the currently selected event.
When inserting an End of Track event, the AFTER/BEFORE options are ignored, and it is always inserted as the last event in the track.
You may insert an event into a track that is empty. No End of Track event is automatically inserted into a new track, so eventually you should manually insert an End of Track event as well.
Only one End of Track event may be inserted into a track, but no error is reported if there is an attempt to insert another End of Track. (Note that the End of Track event's TIME may be modified by the second insert).
When setting an event's DATA, if you do not wish to change a particular data value, then set the respective MIDIEvent.!Data variable to an empty string. MIDISetEvent() will then leave the old value. For example, when setting an On Note event's data, MIDIEvent.!Data1 is set to the note number and MIDIEvent.!Data2 is set to the velocity. If you wish to change only the note number, but not the velocity, then set MIDIEvent.!Data1 to the desired note number, and set MIDIEvent.!Data2 to an empty string.
If specifying more than one option, it doesn't matter in which order you list them. For example, 'TIME | DATA' is the same as 'DATA | TIME'.
Examples
See editing an event, deleting an event, or inserting an event.