Miles Sound System SDK 7.2a

AIL_init_sequence

The function AIL_init_sequence prepares a sequence handle for playback of XMIDI sequence data, and allows the application to specify the starting address and sequence number of the XMIDI sequence to be played.

S32 AIL_init_sequence(
  HSEQUENCE S,
  void const * start,
  S32 sequence_num
);

In Parameters

S: indicates the sequence handle to initialize.
start: points to the memory-resident XMIDI file image containing the sequence to be played.
sequence_num: indicates the sequence number to play.

Returns

0 if the specified sequence could not be found in the XMIDI file image, or if the XMIDI file image itself is invalid; -1 if a timbre could not be loaded but the function was otherwise successful; or a non-zero value if the function was successful and all timbres were installed.

Discussion

This function must be called before any other sequence-oriented actions (such as volume or tempo control) are possible.

The *start parameter should point to a memory-resident image of an Extended MIDI (XMIDI) sequence file as produced by the Miles Sound Studio, or by a call to AIL_MIDI_to_XMI. An XMIDI sequence file may contain one or more sequences. The sequence_num parameter should be 0 to access the first (or only) sequence in the XMIDI file image, 1 to refer to the second sequence, and so on.

Immediately prior to returning, the DOS version of AIL_init_sequence informs the driver of the bank and patch numbers of all instruments needed to play the specified sequence. The driver then attempts to load any required instruments from a Global Timbre Library file or other instrument library file. If an error occurs during timbre installation, AIL_init_sequence will return 0, and the AIL_last_error function will contain the message Driver could not install timbre bank nnn, patch nnn. If this error occurs, it is possible to manipulate and play the sequence as if the function had succeeded, but some or all of the instrument voices may be missing. AIL_init_sequence will return a value of -1 in this case.

By default, MSS 2.X-compatible Global Timbre Library files will be loaded by the driver from the current working directory at the time AIL_init_sequence or AIL_install_timbre is called. If this is undesirable, the AIL_set_redist_directory function may be used to specify a DOS directory path to be used as part of the timbre filename prefix string.

None of the sequence-based library functions, including AIL_init_sequence, will write to the data at *FORM_XMID. The same XMIDI data file image may safely be passed to other drivers (or even used more than once per driver) without being reloaded into memory.

Because it performs driver calls which may access DOS or BIOS routines, the DOS version of AIL_init_sequence must not be called from within any timer, XMIDI, or digital sound callback function. The Windows and MacOS versions of AIL_init_sequence do not perform instrument file access, so they may be called from within a callback function without restriction.

Information regarding the creation of XMIDI sequence files may be found in the Tools Reference under the Miles Sound Studio program description, while the XMIDI IFF file format itself is described in the Extended MIDI (XMIDI) Specification Section.

Example files that use this function: XMIPLAY.C

Group: XMIDI Services
Related Sections: Extended MIDI IFF (.XMI) Structure, XMIDI Patch Bank Select (114)
Related Functions: AIL_MIDI_to_XMI, AIL_allocate_sequence_handle, AIL_background, AIL_init_sequence, AIL_install_timbre, AIL_last_error, AIL_protect_timbre, AIL_register_EOB_callback, AIL_register_EOS_callback, AIL_register_SOB_callback, AIL_register_beat_callback, AIL_register_event_callback, AIL_register_prefix_callback, AIL_register_sequence_callback, AIL_register_timer, AIL_register_trigger_callback, AIL_release_sequence_handle, AIL_set_GTL_filename_prefix, AIL_set_redist_directory, AIL_set_sequence_loop_count, AIL_start_sequence, AIL_unprotect_timbre
Related Basic Types: HSEQUENCE, MILES_PREFERENCES, S32, void const *
Related FAQs: How do I play an XMIDI or MIDI file?