The very first thing you must do (after registering the RxMidiIO functions, if needed), is to open up a MIDI port for output or input. Some of the other RxMidiIO functions operate only upon that MIDI port you open, and will raise a REXX SYNTAX condition if you try to call them before opening that port.


MIDI Output

You open a MIDI output port by calling MidiIoOpenPort() once.

After successfully opening a MIDI port, you may call other functions to output MIDI data, and perform other operations on that port.

Typically after opening a port for output, you'll next make one or more calls to MidiIoOutShort() to output MIDI events (ie, messages). Each call to MidiIoOutShort() outputs one event (message).

After you're done outputting MIDI messages to that port, and no longer wish to output any more, then you'll call MidiIoClosePort() to close that MIDI port. You can then subsequently open another port. (RxMidiIO works upon only one MIDI output port at a time).

Note: RxMidiIO automatically closes any output port you have left open if your script ends without doing so itself. But, it is best not to keep a port open when you're not using it, so that other programs may access that port.


MIDI Input

You may also use MidiIoOpenPort() to open a MIDI input port. You can have a MIDI input port open at the same time that you have a MIDI output port open, and they do not have to be upon the same physical device.

Alternately, you can have a MIDI input port open with no MIDI output port open, if desired. But if you choose to have incoming MIDI messages echoed to MIDI Out, you should open a MIDI output port too.

In order to do MIDI input, your script must use the REXX GUI add-on library, available at the site where you obtained RxMidiIO.

You must open a REXX GUI window, which will be associated with MIDI input. This could be your "main window" if desired. To associate the window with MIDI input, you must call the function MidiIoParams() once. You'll pass it a handle to the window. MidiIoParams() can also be used to determine what particular MIDI events you wish to receive (ie, you can have RxMidiIO not inform you of certain messages such as Active Sense, etc), what particular channels you wish to receive, and if you wish to receive System Exclusive messages, how big a buffer to use to store incoming messages.

Whenever a MIDI message arrives at the MIDI input port, Reginald will call your window's WM_EXTRA event handler. To obtain the actual MIDI data bytes of that message, you'll call the function MidiIoInput(). This will store the data in some variable of your choice, or store the bytes in the MIDIEvent stem variable in the same format that MIDI REXX uses.

After you're done inputting MIDI messages from that port, and no longer wish to input any more, then you'll call MidiIoClosePort() to close that MIDI port. You can then subsequently open another port. (RxMidiIO works upon only one MIDI input port at a time).

Note: RxMidiIO automatically closes any input port you have left open if your script ends without doing so itself.


Errata

Note: To avoid any conflicts with the names of REXX variables that RxMidiIO sets in your script, you should avoid naming any of your own variables starting with an exclamation point, nor use the variables MidiErr or MidiHeading.