Miles Sound System SDK 7.2a

AIL_send_sysex_message

The function AIL_send_sysex_message transmits a System Exclusive message to a MIDI device driver.

void AIL_send_sysex_message(
  HMDIDRIVER mdi,
  void const * buffer
);

In Parameters

mdi: specifies the MIDI driver to which the MIDI System Exclusive message should be transmitted.
buffer: points to an area of application memory containing the System Exclusive message to be transmitted.

Discussion

The System Exclusive message to be transmitted should not exceed 256 bytes for Roland MT-32 synthesizers, or 512 bytes for any other supported synthesizer. Longer System Exclusive messages should be broken up into smaller transmissions.

Certain synthesizers such as the Roland MT-32 and LAPC-1 require substantial delays between System Exclusive messages and any MIDI traffic which follows them. The AIL_delay function should be used to implement System Exclusive delays, where appropriate.

System Exclusive message addresses, formats, and functions vary according to the synthesizer in use. System Exclusive messages sent to incompatible synthesizers will generally be ignored.

Note that the interface and implementation of AIL_send_sysex_message no longer follows the MT-32-specific format used under MSS version 2. Under MSS version 3, the System Exclusive message's format should conform to the Standard MIDI Files 1.0 specification. For convenience, the relevant part of this specification is reprinted verbatim here.

A normal complete system exclusive message is stored in a MIDI file in this way:

F0 < length > < bytes to be transmitted after F0 >

The length is stored as a variable-length quantity. It specifies the number of bytes which follow it, not including the F0 or the length itself. For instance, the transmitted message F0 43 12 00 07 F7 would be stored in a MIDI file as F0 05 43 12 00 07 F7. It is required to include the F7 at the end so that the reader of the MIDI file knows that it has read the entire message.

Another form of sysex event is provided which does not imply that an F0 should be transmitted. This may be used as an "escape" to provide for the transmission of things which would not otherwise be legal, including system real-time messages, song pointer or select, MIDI Time Code, etc. This uses the F7 code:

F7 < length > < all bytes to be transmitted >

Unfortunately, some synthesizer manufacturers specify that their system exclusive messages are to be transmitted as little packets. Each packet is only part of an entire syntactical system exclusive message, but the times they are transmitted are important. Examples of this are the bytes sent in a CZ patch dump, or the FB-01's "system exclusive mode" in which micro tonal data can be transmitted. The F0 and F7 sysex events may be used together to break up syntactically complete system exclusive messages into timed packets.

An F0 sysex event is used for the first packet in a series it is a message in which the F0 should be transmitted. An F7 sysex event is used for the remainder of the packets, which do not begin with an F0. (Of course, the F7 is not considered part of the system exclusive message).

A syntactic system exclusive message must always end with an F7, even if the real-life device didn't send one, so that you know when you've reached the end of an entire sysex message without looking ahead to the next event in the MIDI file. If it's stored in one complete F0 sysex event, the last byte must be an F7. If it is broken up into packets, the last byte of the last packet must be an F7. There also must not be any transmittable MIDI events in between the packets of a multi-packet system exclusive message. This principle is illustrated in the paragraph below.

Here is an example of a multi-packet system exclusive message: suppose the bytes F0 43 12 00 were to be sent, followed by a 200-tick delay, followed by the bytes 43 12 00 43 12 00, followed by a 100-tick delay, followed by the bytes 43 12 00 F7, this would be in the MIDI File:

F0 03 43 12 00
81 48
F7 06 43 12 00 43 12 00
64
F7 04 43 12 00 F7

When reading a MIDI file, and an F7 sysex event is encountered without a preceding F0 sysex event to start a multi-packet system exclusive message sequence, it should be presumed that the F7 event is being used as an "escape". In this case, it is not necessary that it end with an F7, unless it is desired that the F7 be transmitted.

Group: XMIDI Services
Related Sections: DDK Function: 502H Transmit MIDI Data
Related Functions: AIL_delay, AIL_send_channel_voice_message, AIL_send_sysex_message
Related Basic Types: HMDIDRIVER, MILES_PREFERENCES, void, void const *