MIDITrack

Sets the search track(s) which MIDIGetEvent() searches, as well as the currently selected track. Also can be used to query the currently selected track.

Synopsis

selectedtrk = MIDITrack(tracks)

Args

tracks are the numbers of the desired search tracks, where 1 is the first track in the MIDI file. Several choices can be specified with a '|' or blank space between them. For example, '1 2 3' for the first three tracks. The first track you specify, which actually contains events, becomes the currently selected track (until a call to MIDIGetEvent() or perhaps another call to MIDITrack()).

If the first character of tracks is \, then these are the tracks to ignore. All other tracks are then assumed to be searched. Note that a string of only '\' sets all tracks as searchable.

If tracks is an empty string (""), then the search track and currently selected track are both changed to the next track containing events in the MIDI file. Therefore, this is a way to increment the search track and currently selected track. This is primarily useful for searching through one track at a time. If tracks is 0, then this resets the currently selected track, so that a subsequent call to MIDITrack() will start the incrementing anew.

If tracks is omitted, then neither the search tracks (nor the currently selected event/track) are changed. Therefore, this is a way to simply query the currently selected track.

Returns

If success, the currently selected track (ie, where 1 is the first track) is returned. If none of the search tracks contain any events, then 0 is returned.

Notes

If you call MIDITrack() 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 "MIDITrack" reported MIDI file not yet loaded!.

If you pass a non-numeric value for tracks, then a SYNTAX condition is raised. CONDITION('E') returns error number 40.12 and CONDITION('D') returns the message MIDITrack argument 1 must be a whole number; found "<badarg>" where <badarg> is what you erroneously passed.

If you pass a value for tracks that is larger than the number of tracks that RxMIDI supports, then a SYNTAX condition is raised. CONDITION('E') returns error number 40.1 and CONDITION('D') returns the message DLL function "MIDITrack" reported RxMIDI supports only <number> tracks! where <number> is how many tracks are supported by the version of RxMIDI that you're using.

By default, MIDIOpenFile() sets only the first track (ie, 1) as the search track, and there is no currently selected event/track.

The currently selected track may also be changed by inserting an event via MIDISetEvent().

When you set the search tracks, there is no more currently selected event, and MIDIGetEvent() restarts its search from the beginning of the new search tracks. The exception to this is when you query the currently selected track, in which case the currently selected event is not changed.

Examples

/* Set all tracks as the search tracks */
selectedtrk = MIDITrack('\')
IF selectedtrk == 0 THEN SAY "All tracks are empty!"
ELSE SAY "Currently selected track =" selectedtrk

/* Set the next track as the search/selected track */
selectedtrk = MIDITrack("")
IF selectedtrk == 0 THEN SAY "No more tracks with data"

/* Query the currently selected track without changing search tracks */
selectedtrk = MIDITrack()
IF selectedtrk \== 0 THEN SAY "Currently selected track =" selectedtrk

/* Print out the numbers of all tracks that have data */
selectedtrk = MIDITrack('\')
DO WHILE selectedtrk \== 0
   SAY selectedtrk
   selectedtrk = MIDITrack("")
END