MIDISysex

Excerpts (retrieves) one or more bytes of the currently selected Sysex (ie, 'Sysex', 'First Packet', 'Packet', or 'Last Packet' type) event. When MIDIGetEvent() encounters a Sysex type message, it does not return all of the data (since a Sysex event may contain a large amount of data). Instead, MIDIGetEvent() returns the size of the data (in MIDIEvent.!Data1). You can then use MIDISysex() to retrieve one or more bytes of data from that Sysex event.

Synopsis

excerpt = MIDISysex(number, start, option)

Args

number is the desired number of bytes to excerpt. If number is omitted, it defaults to 1.

start is the byte at which to start the excerpt, where 1 is the first byte in the Sysex event (typically a F0 hex byte, unless a Packet). If start is omitted, it defaults to 1.

option determines the format of each byte, and is one of the following:

Option Meaning
'A' (Ascii) Return each byte verbatim as it appears in the Sysex message. There are no spaces between the bytes. Use SUBSTR() to extract each byte (as 1 ASCII character) and then C2D() or C2X() to convert to a numeric string or hex value respectively.
'N' (Numeric) Return each byte as a numeric value in base 10, with a space separating each value. Use D2C() to convert the values back to verbatim bytes.
'H' (Hex) Return each byte as a numeric value in base 16, with a space separating each value. Use X2C() to convert the values back to verbatim bytes.
'C' (C style) Return each byte as a numeric value in base 16, but prefaced with a 0x like C language syntax, and a space separating each value.
'B' (Binary) Return each byte as a numeric value in base 2, with a space separating each value. Use B2X() and then X2C() to convert the values back to verbatim bytes.

If option is omitted, it defaults to 'A'.

Returns

The requested number of bytes if successful, or an empty string if there are no bytes (or the currently selected event is not a Sysex type of event).

Notes

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

If you pass a non-numeric value for number or start, then a SYNTAX condition is raised. CONDITION('E') returns error number 40.11 and CONDITION('D') returns the message MIDISysex argument <XX> must be positive; found "<badarg>" where <XX> is 1 for number or 2 for start, and <badarg> is what you erroneously passed.

If you pass a value for option 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 MIDISysex argument 3, option must start with one of "<options>"; found "<badchoice>" where <options> are the allowable choices and <badchoice> is what you erroneously passed.

If number + start references more bytes than are actually in the Sysex message, then only those available bytes are returned. If start is more than the length of the Sysex message, then an empty string will be returned.

Examples

/* Get the first byte of a Sysex message, and check if it is F0 */
byte = MIDISysex(,,'H')
IF byte == "F0" THEN SAY "It's a sysex start"

/* Do the same, but use 'N' format */
byte = MIDISysex(,,'N')
IF byte = 240 THEN SAY "It's a sysex start"