Sets the parameters for MIDI input. This must be called once before opening a MIDI Input port in order to establish the REXX Dialog window that gets notified whenever a MIDI message arrives. It also establishes the size of the input buffer for System Exclusive messages. It furthermore establishes what MIDI events get filtered from the input. Finally, it sets which events, if any, get echoed to MIDI Out.
Synopsis
error = MidiIoParams(window, sysexBufferSize, eventFilters, chanFilters, eventEcho, chanEcho, messageNum)
Args
window is the handle to the REXX GUI window that will receive a notification whenever a MIDI message is input. See Inputting an event. If omitted, then the window set by a previous call to MidiIoParams() is used.
sysexBufferSize is the desired size for the input buffer that holds system exclusive data. If omitted, then the size set by a previous call to MidiIoParams is used. If you pass a 0, then system exclusive is not input.
eventFilters determine which types of MIDI messages are input. If omitted, then the filtering options are not changed from their previous state. eventFilters should be a string of the desired event numbers that you wish to be input, each separated by a space, for example "80 90 240" to input MIDI Note On, Note Off, and System Exclusive. If the first character of eventFilters is \, then these are the event types to ignore. All other types are then input. Therefore, a string of only '\' sets all event types as input.
chanFilters determine which MIDI channels are input. If omitted, then the filtering options are not changed from their previous state. chanFilters should be a string of the desired channels that you wish to be input, each separated by a space, for example "1 10" to input MIDI channels 1 and 10. If the first character of chanFilters is \, then these are the channels to ignore. All other channels are then input. Therefore, a string of only '\' sets all channels as input.
eventEcho determine which types of MIDI messages are echoed to MIDI Out as soon as they are input. If omitted, then the echo event options are not changed from their previous state. If the first character of eventEcho is \, then these are the event types to ignore. All other types are then echoed. Therefore, a string of only '\' sets all event types as echoed.
chanEcho determine which MIDI channels are echoed to MIDI Out. If omitted, then the echo channel options are not changed from their previous state. If the first character of chanEcho is \, then these are the channels to ignore. All other channels are then echoed. Therefore, a string of only '\' sets all channels as echoed.
messageNum determines what message number is passed to the window's WM_EXTRA callback. If omitted, then the message number is not changed.
Returns
An empty string if successful, or an error message if a failure.
Notes
The window handle, and sysexBufferSize can be set only before a MIDI Input port is open. If you need to change the window handle and/or sysexBufferSize, then first close any opened MIDI Input port, call MidiIoParams() with the new handle and size, and then reopen the MIDI Input port. On the other hand, eventFilters, chanFilters, eventEcho, chanEcho, and/or messageNum may be changed while a MIDI Input port is open.
Upon the first time you call MidiIoParams(), if you don't set the window handle, a SYNTAX condition is raised. CONDITION('E') returns error number 40.5 and CONDITION('D') returns the message Missing argument in invocation of "MIDIIOPARAMS"; argument 1 is required. If you pass a handle of 0 (ie, perhaps your call to GuiCreateWindow failed and you didn't check for an error, or you have closed the window whose handle you're using), a SYNTAX condition is raised. CONDITION('E') returns error number 40.14 and CONDITION('D') returns the message MIDIIOPARAMS argument 1 must be positive; found <badarg> where <badarg> is what you erroneously passed. If you pass something other than a legal window handle, then a SYNTAX condition is raised. CONDITION('E') returns error number 40.12 and CONDITION('D') returns the message MIDIIOPARAMS argument 1 must be a whole number; found <badarg> where <badarg> is what you erroneously passed.
If you never pass a non-zero sysexBufferSize argument to MidiIoParams(), then system exclusive messages will never be input. To temporarily disable input of system exclusive messages, you can specify an eventFilters that doesn't contain event number "240" (or use MidiIoRecord() to temporarily disable all input). If you pass an illegal size, then a SYNTAX condition is raised. CONDITION('E') returns error number 40.12 and CONDITION('D') returns the message MIDIIOPARAMS argument 2 must be a whole number; found <badarg> where <badarg> is what you erroneously passed.
If you pass a non-numeric value for eventFilters, chanFilters, eventEcho, chanEcho, or messageNum then a SYNTAX condition is raised. CONDITION('E') returns error number 40.12 and CONDITION('D') returns the message MIDIIOPARAMS argument <XX> must be a whole number; found "<badarg>" where <XX> is 3 for eventFilters, 4 for chanFilters, 5 for eventEcho, 6 for chanEcho, or 7 for messageNum, and <badarg> is what you erroneously passed.
You must open some MIDI Out port in order for eventEcho or chanEcho to be effective. You do not need to open the MIDI Out port prior to calling MidiIoParams(), and you can change the MIDI Out port at any time without needing to set the echo options again with MidiIoParams().
If you never set the eventFilters, then all events except Active Sense are input.
If you never set the chanFilters, then all channels are input.
If you never set the eventEcho, then no events are echoed.
If you never set the chanEcho, then all channels are echoed.
Examples
See Inputting an event.