Buffer Functions

The buffer functions work on the sequence itself. They are "insert", "delete" and "index". These functions add, subtract and display the position of an event in the sequence. This will make sense as we look at them.

(insert time channel kind data1 data2 data3): In this function we use the keyword "insert" followed by the raw time where we want the event inserted into the sequence. This is followed by the MIDI channel number we wish the event to be assigned and then the kind of event we wish to insert. The "data" variables correspond to the parameters for that kind of event. Not all event types will need all three "data" variables. Here is a rundown of specific insert functions for each event type:

(insert time channel NOTE key velocity duration)
(insert time channel CONTROL number value)
(insert time channel WHEEL value)
(insert time channel PATCH number bank) ;The "bank" variable is optional
(insert time channel KEYAFT key value)
(insert time channel CHANAFT value)

As you might guess, the keyword "insert" and the constant for the event type such as "NOTE" and "WHEEL" must appear in your function as shown, but all of the other parts can be variables or functions as you require. If you perform an "insert" in a "forEachEvent" loop, the event is inserted into whatever track is currently being scanned. If you have more than one track highlighted, you may have a hard time knowing when the loop has ended one track and gone on to the next one. Then again, it may not matter providing the insert is keyed to the events around it. If the insert is not within a "forEachEvent" loop, it will be inserted into the track highlighted by the cursor (or blue bar in some versions of Cakewalk) regardless of whether or not there are other tracks selected (black bar highlighted) or where the tracks fall numerically. The "bank" number in the PATCH "insert" function is optional. If it isn't supplied, it is assumed to be the same as assigning it -1, which means "none" and shows up as "---" to the user in the TRACK VIEW.

(delete): This function is only usable within a "forEachEvent" loop and will delete from the sequence the event currently being scanned by the loop. It has no arguments or data associated with it. He's just the hatchet man and he works alone. Once an event is deleted, it's gone forever. If you first store all the information about the event before you delete it, it can then be reinserted later using the "insert" function. These two make a good team when writing programs that must store an event and then act upon it based on information gained from another event during another pass of the "forEachEvent" loop. Remember, the events scanned by that loop are only available for manipulation during that pass of the loop. Once the loop starts on another pass, the first event is out of reach and a new event becomes the focus of the loop. In order to change an event after the loop has passed it, you must store the event in variables and then delete it while the loop is scanning it. Later, once you have whatever information you need to alter the event, you can then reinsert it back into the sequence at it's original event time regardless of where the loop currently is. You can see this technique if you examine some of the sample programs included in this document..

(index): This function returns the number of the event being scanned by a "forEachEvent" loop as it is ordered within a sequence. The very first event in a sequence is numbered 0 and the next 1, then 2 and so on. If you delete an event, all events after it are moved back in number so that the event following the deleted one now has its number. Inserting an event causes all events after it to move up in number to make room and so on. There are only two uses I have ever seen for "index". One is in a "message" function to tell the user how many events have been scanned, the other is in an "if" function to let the program know that it has reached the first event on a new track by testing for (== index 0).