CAL Edit Menu Commands Cross-Reference

How to use this document:

If you are a CAL programmer, you will probably want to save this document to disk. Open it in your Web browser while you are working in CAL, and use it as a supplement to the Cakewalk help screens.

Table of Contents

The list below is a hyperlinked table of contents. Click on an item to go to the information on that item. For your convenience, the list uses the same order as the CAL Edit Menu help screen. Only CAL Edit Menu commands which differ between CAL versions are included in the list.

Copy | Cut | Delete | Paste | Quantize | Groove Quantize | Slide | Transpose |

Length | Retrograde | Insert Series of Controllers | Scale Velocity | Fit Improvisation

Fit to Time | Interpolate/Select by filter

Now, about the four flavors of CAL...

Recent versions of CAL come in four flavors, which I have color-coded as in the table below. The bottom line of the table shows the lowest version number of Cakewalk Pro software which will work with each version of CAL. The line just above it shows the features your Cakewalk software must have to use each version of CAL.

Yes, there really are two distinctly different flavors of CAL 4.0. I call them Blueberry and Lime. Blueberry is the version described in the help screens in versions 4.5 and higher, but without audio features. Lime is the version actually shipped with Cakewalk Pro Audio 4.5 and 5.0. Lemon is the version shipped with Cakewalk 6.0 and higher. While the edit menu commands for each of these versions have the same names, they have different parameter lists.

Any of the flavors might make a nice sherbet, but when help screens don't match the product, well, that can be sort of confusing. The purpose of this document is to dispel the confusion and to make it possible for you to translate among all of the recent CAL versions.

The VERSION constant in CAL also is helpful. VERSION returns a number 10 times the version number. So, for example, CAL 3.1 returns 31. The program NEED20.CAL, which ships with Cakewalk products, shows how VERSION can be used to exit a CAL program which the Cakewalk software in use does not support. There is another example of use of the VERSION constant in a file on this site.

Each new Cakewalk version includes CAL bug fixes. Sometimes, a CAL program may not run under an earlier version of Cakewalk than the one in which it was written, even if its syntax appears correct. The problem is especially vexing with CAL under Cakewalk versions 6.0 and higher, which use the CAL version number 6.0. I have given an example of a bug fix between CPA 6.0 and 7.0 elsewhere on this Web site, showing how a program can run under CPA 7.0 but not under 6.0 despite seemingly identical syntax. There is an important enhancement to the Slide command in versions 7.0 and higher. Be sure to test your CAL programs under every version of Cakewalk under which they may have to run.

Compatibility issues

Cakewalk is to be commended for keeping its new products compatible with programs written in older versions of CAL, all the way back to version 1.(There are, however, a couple of exceptions due to bugs in the EditFitToTime and EditControlFill commands, and another bug described elsewhere on this site.)

With these exceptions, CAL programs written in each Cakewalk release work under later releases. For maximum compatibility, use CAL 3.0 when you can. To select event types or perform operations introduced since CAL 3.0, you may have to use a newer version of CAL. You can mix command versions in the same CAL program, so if you need to update a program, you need only change the commands that will affect audio or other new event types. Conditionals using the VERSION constant let you support the features of newer Cakewalk versions in a program that still runs under earlier versions.

Many CAL 3.0 commands use more parameters than CAL 4.0 and 6.0 commands do. That is because each command in CAL 3.0 sets up its own selection, while commands in CAL 4.0 use the selection that the user (or the CAL program) has previously defined. When using CAL 4.0 and 6.0 commands, it is still possible to define a selection in CAL, only you do this before running an edit command.

As you move from Blueberry to Lime to Lemon versions of CAL 4.0 and 6.0, there are no parameters that are different, but only added parameters at the end of the parameter list. (There is one exception, in the Insert Series of Controllers command, but we will deal with that when we get to it.).

What about CAL 1.0 and 2.0?

CAL versions 1.0 and 2.0 are moldy oldies and are not covered in this document. Programs written in CAL 1.0 and 2.0 are compatible with all later Cakewalk software releases that support CAL. Commands for those versions are essentially as in CAL 3.0, except that:

CAL 1.0: Required programs to be structured as Prolog, Body and Epilog because there was no forEachEvent command. For more information, see the CAL Tutor bundled with CPA 6.0 and higher.

CAL 2.0: Introduced the forEachEvent command, but lacked several data types in the Event Filter that are available in CAL 3.0. (MCI, Wave, Sysx, etc. -- see CAL help screens in Cakewalk and the article on event types on this site.)

Hungarian notation of parameter names

The parameter names in the following tables, like those in the Cakewalk CAL help screens, use "Hungarian" notation, denoting data types with a small first letter followed by a capital letter which begins the actual parameter name. "Hungarian" first letters used in the CAL help screens are:

There is no specific CAL data type for variables to represent a Boolean or a time. A Boolean may be declared as any of the numeric data types. A time must usually be declared as a long or a dword, data types capable of handling large numbers.

The ranges shown in the table above are those for the variable types, not for specific CAL parameters. Most CAL parameters are limited to a few values, and setting the parameters to values outside the allowed range will lead to errors.

Organization of the parameter tables which follow

Each table below shows the parameters for all versions of a CAL Edit menu command under CAL 3.0, 4.0 and 6.0. Explanations as needed are provided above each table. The meanings for most of the parameter names are the same as in the Cakewalk help screens and are easy to match with the fields in the dialog box for the related Edit Menu command. I have included comments to try to answer any questions which may remain. Red letter items in the comments are the ones most likely to trip you up as you use the commands.

In the tables below, the different CAL versions read from left to right, as in the table at the start of this page, and the parameters read from top to bottom. I have used colored type so you can count parameters in groups of five. You might leave an extra space after every fifth parameter in your CAL programs to help you keep track of them.  

CAL command tables

Copy

Table of contents

Cut

The Cut command removes events from the file and places them on the clipboard.

Table of contents

Delete

There is no Delete command in Cakewalk 3.0. There is a Delete command in Cakewalk 4.5 and higher, though it is undocumented in the CAL help screens! Its parameters are the same as for the Cut command. The usefulness of the Delete command is that it does not put a selection onto the clipboard as the Cut command does -- the Delete command lets you retain events on the Clipboard while you delete others.

Table of contents

Paste

nToTrack: Beware! The track pasted to this track is not necessarily the first track you selected, but the first track you selected that contains either 1) events or 2) (verified in CPA 8) -- track parameters. CAL can not read track parameters (sigh...). You can be sure that CAL will paste to the correct track either 1) by inserting an event or track parameter in Track 1 and selecting it, or 2) by sliding the selected events past the end of the music and then performing a track-by-track search of them to find the lowest track number with events.

bOneTrack: Beware! NOT TO BE TRUSTED always to paste all selected events into a single track, as tested under Cakewalk 8. If you want to be sure what track the events will be pasted into, you must cut or copy them one track at a time.

bInOldClips: the Cakewalk help screen calls this bAsNewClips but it is backwards. The events are pasted into existing clips when the parameter is set to 1 and into new clips when the parameter is set to 0. (Verified in CPA 8.01 and probably also true in other versions. Check by using the CAL Recorder).

If you have multiple clips in a track, there is no telling in what order CAL will evaluate them. Often, correct execution of a forEachEvent loop depends on the events' being executed in order of their time in the file.

Cutting, then Pasting Into Existing Clips when there are no other clips in a track combines all the pasted events into one clip! So, select the entire track, cut, then paste back into existing clips, and all the events in the track are guaranteed to be evaluated in sequential order. This solves many a CAL headache as long as it wasn't important to keep the clips separate. I have posted a CAL program which combines clips on this Web site.

Copying a clip, then Pasting Into Existing Clips when there are no other clips in a track creates a new, linked clip. The method is a bit obscure, but yes, you can create linked clips in CAL!

nHolekind: 0.blend; 1, replace old material; 2, move old material over. Cakewalk help screens are confusing about this parameter. It is necessary in CAL 4.0 and 6.0 just as it is in the corresponding edit menu commands. Bug: old material doesn't always move over as far as it should. It only moves over as far as material in the selection pushes it over. So, for example, if you copied measures 1 and 2 but measure 2 is empty, and then paste at measure 3, the old measure 3 will only be moved to measure 4 instead of measure 5. (Verified in Cakewalk 8.04, at least as it applies to the Tempo Map).

Table of contents

Quantize

wRes, wResolution: are defined as the number of ticks for each time duration in the drop-down list in the Edit menu Quantize dialog box. For this reason, values may be set through CAL which can not be set through the dialog box.

Table of contents

Groove Quantize

wRes: is the number of ticks that corresponds to each time in the Resolution drop-down list in the Groove Quantize dialog box. Values may be set through CAL which can not be set through the dialog box

nWindow: This is the "Window-sensitivity" control in the Groove Quantize dialog box, set as a percentage from 0 to 100.

nOutofWindowMode: 0, do not change; 1, quantize to resolution; 2, move to nearest; 3, scale time.

String parameters (start with "sz" in table below): must be enclosed in double quotes in the parameter string. Use the CAL recorder to provide yourself with an example if you have questions about how to format this parameter.

Table of contents

Slide

bUnitTicks: unit for nAmount is: 0, measures; 1, ticks.

nMeasTickSecFr: unit for nAmount is: 0,  measures; 1, ticks; 2, seconds; 3, frames. BUG! The EditSlide40 command, at least under CPA 8.00, does not track tempo changes when sliding by seconds toward the start of the file. The same problem may also exist under earlier versions, though I have not verified that.

Frame rates: If you elect to slide by frames, the length of the slide will differ depending on the frame rate in effect when the CAL program is run! It is possible to determine the frame rate within CAL by comparing the results of slides by seconds and by frames.

Slides by frames are inaccurate by as much as several percent. under CPA 6.xx if there are tempo changes in your music. For long slides, slide by seconds, and then by frames. This bug appears to have been corrected in v. 7.0. Judging by the decimals that now appear in the tempo display, tempos are now stored as floating point numbers. Though the From and Through times are stored in musical time, it is possible to slide repeatedly by seconds and obtain the same result as in a single, larger slide by the same number of seconds.

Speed: When sliding by seconds or frames, the EditSlide40 command is relatively slow, due to the time conversion calculations. Even when only a single event is being slid, a single slide takes about 50 milliseconds (120 MHz Pentium). Since the command is accurate in recent versions, you can often minimize the number of times it must be used by taking the end of one slide as the starting point for the next one. This technique will considerably speed up your CAL program.

The EditSlide and EditSlide40 commands in versions through 6.xx take a minimum argument of -32768 (- 2^15) and a maximum of 32767 (2^15 - 1) regardless of the units, be they ticks, measures, seconds or frames. Read more about this in another article on this site. Attempting to use a larger number will result in a "value out of range" error and terminate your program. Though the Edit Menu Slide command in Cakewalk version 7.0 is limited to five digits by the data entry window, the EditSlide40 command in v. 7.0 and higher takes a long integer as an argument and so can slide to any valid Cakewalk time -- but be wary, since there is no error trapping for positive data overflow. If your slide takes events past the Cakewalk time limit of 16777215 ticks, they will wrap around to the start of the file. Since the CAL version number is the same in Cakewalk 6.0, 7.0 and 8.0, there is no way you can use the VERSION constant to account for the difference in the EditSlide40 command between CAL versions. Sigh.

Events remain selected after a Slide -- and this can be very useful. You can immediately perform another operation on them without having to select them again. A Slide, unlike a Cut and Paste, automatically leaves events in the same track. This makes the Slide much quicker to use, especially in CAL where it is such a chore to paste multiple tracks starting at the track you want them to. When moving a segment of music in CAL, it is often most convenient  to slide events, then cut and paste tempos, meters and markers, which do not suffer from the track assignment problem.

A neat feature of  the EditSlide and EditSlide40 commands is that they can trim the selection. Just slide the selection so its From and Thru times are completely outside their earlier range, then slide the selection back where it was. After using a Slide command to trim a selection, the Thru time, at least in CPA 8.01, will sometimes be conveniently located at the end of the last note in the selection. This is important in order, for example, to include tempo messages that go with the last note in the selection. But beware of a nasty bug. Sometimes Slide command leaves the Thru time one tick before the start of the last event. If you later use the Thru time to reselect, the last event will not be included.

When sliding by seconds or frames, events after the first one in the selection slide by the same amount of musical time, not by the same amount of real time. If there are tempo changes, but you want every event to be placed precisely in real time, you must run a different slide command for each different event time.. This is fairly straightforward (though quite slow) when inserting new events, but it is very cumbersome when processing existing events, since the EditSlide and EditSlide40 commands do not work inside a forEachEvent loop. You would have to run a while loop that runs once for every tick, selects all the events on that tick, and slides them to their new positions, then moves on to the next tick. The selection would have to move in the opposite direction from the slide, so it doesn't reselect events it has already moved. This is, for example, how you could create a MIDI echo whose delay remains the same regardless of tempo changes.

However, even this trick will not adjust note durations so they remain the same in real time despite tempo changes. You'd be better off learning C++ so you can use the Cakewalk MIDI effects if you want to do this kind of thing.

Slides toward the start of the file are error-trapped in all versions: if they reach the start of the file, that is where they will be placed.

Table of contents

Transpose

At least in Cakewalk v. 7, the Transpose commands test for limits. Any note which is transposed above 127 or below 0 is "folded in" by as many multiples of 12 (musical octaves) as are necessary to place it back within the range 0...127. All of the folded-in notes end up piled on top of each other in the top octave (116-127, G#9-G10) where they make a nasty shrieking noise, or bottom octave (0-11, C0-B0), where they make a low rumble, regardless of the range of octaves they originally occupied. When writing a CAL program, you can do better -- test for the highest or lowest note and post an error message if your program would put that note out of range.

Table of contents

Length

Cakewalk Length commands work by percentage points, though musical meter works by fractions. This weird and very annoying mismatch of tool to task is discussed in greater detail elsewhere on this Web site. This problem makes the CAL Length command maddeningly useless for many purposes. I have provided a solution to this problem by writing a replacement Length command in CAL, which is also posted on this Web site.

Be aware that the Length command does not test for data overruns. Events placed beyond the Cakewalk time limit of 16777215 ticks will wrap around to the start of the file.

Table of contents

Retrograde

No parameters in CAL 4.0?! Only the CAL 3.0 (vanilla) version has parameters, since it includes its own selection means.

Flavors of backwardness: Retrograde correctly reverses notes, so the time occupied by each note is the mirror image of where it was originally in the Retrograde "window." Retrograde does NOT correctly reverse the effects of controller, RPN, wheel and other messages, and this is a BUG. Retrograde simply mirrors the locations of these messages, without regard to the time period which they are supposed to affect. For example, if you have a controller message on beat 4 of a 4 beat measure, it affects the notes on beat 4 (and onward until the next message with the same controller number). After you run a Retrograde command, the controller message is on beat 2. But the notes it was supposed to effect are now in beat 1! (Verified in Cakewalk 8.04).

The Retrograde commands in Cakewalk only reverse the order of ticks. They do not reverse the order of events on each tick, as sent to the MIDI output port(s) and as visible in the Event List. To change the order within a tick, you must use a forEachEvent loop. This order may be important, for example in a thinning routine in which you want to preserve the last controller event on a tick (the only one which has a lasting effect) and discard the others. A forEachEvent loop will place events within a tick in the order in which they are processed.

If you want, you could write a correct Retrograde command in CAL, which would look at each controller number in turn and move its value to the time of the previous message. Unfortunately, you can't do this with RPNs or any of  the several other types of events for which CAL can not recognize parameters. Sigh.

Table of contents

Insert Series of Controllers

The Insert Series of Controllers command is in the Cakewalk Insert menu, but it appears under the Edit menu in the CAL help system.

BUG in the CAL recorder!!! When recording this command under 5.0, 6.0 and perhaps other Cakewalk versions, the CAL recorder increments the controller number by 1. For example, if you insert a series of controllers for controller 7, the CAL recorder will record them as controller 8. You may correct this by hand. This bug has been corrected in 7.0. Unfortunately, CAL version numbering does not reflect this. The sow's ear has a silver lining -- an easy way to test for the version is to insert a controller and then test for its number.

Pitch Wheel as Controller 0?: CPA 6.0 and other Cakewalk software that supports RPNs and NRPNs as data types does not recognize the Pitch Wheel as Controller 0 in the Insert Series of Controllers command , as defined in earlier CAL versions. This counts as a BUG since it violates the Cakewalk policy of backward compatibility. A program may be made compatible with all versions by use of the VERSION constant.

nWhCtrlRpnNrpn: 0,Wheel; 1, Controller; 2, RPN; 3, NRPN. BUG! The EditControlFill CAL command only works for controllers under Cakewalk 6.x and 7.0. It does not work for the Pitch Wheel, as it does under earlier Cakewalk versions. Using any value other than 1 for the last parameter will lead to unexpected results. Also, the CAL recorder only records this command for controllers. You may use my CAL programs to insert RPNs and NRPNs under 6.0 and lower. I do not yet have a version of that program that runs under Cakewalk 7.0 -- this is one more case where the CAL syntax is supposed to be the same, but it isn't. It should be easy to write a CAL to insert series of pitch wheel messages. RPNs or NRPNs are tougher since they must first be inserted as controller messages.

Table of contents

Scale Velocity

bUnitsPercent: 0, nBeg and nEnd are the beginning and ending values of the series of velocities to be inserted; 1, existing velocities will be scaled by the percentages set in nBeg and nEnd.

Table of contents

Fit Improvisation

EditFitImprov40: This command is undocumented, but is invoked by the CAL recorder in CPA versions 4.5 and higher and in corresponding versions of other Cakewalk products.

The Fit Improvisation commands work according to the length of beats in the first measure, ignoring later changes in the meter. Suppose the music starts with longer beats, say in 4/4, and goes to shorter beats, say in 9/8. (Certain bizarre, contemporary, experimental, esoteric compositions such as, um, for example, the Beatles' I Want to Hold Your Hand have meter changes like this Yes, really -- the last measure of the intro of I Want to Hold Your Hand is in 9/8. Move over, Stravinsky, tell John McLaughlin the news!)

If your music does have meter changes, and especially with beats of different lengths, it makes sense to insert an extra measure at the start, with the shortest beats used anywhere in the music. If you don't do this, you may find that the beats for the reference track become off-beats.

The Fit Improvisation commands can not draw a smooth tempo curve between beats, but instead adjust all event times within a beat proportionally to the total length of the beat. For this reason, the timing of events in the middle of a beat will be too early if the tempo is speeding up:: da....da....da....da.... instead of da.....da....da...da.. (and vice versa). The shorter the beat length you establish in the first measure, the smoother the tempo changes will be.

The Fit Improvisation commands adjust note durations according to the time length change of the beat in which the note starts. If the beat in which the note starts is lengthened more than following beats, the note becomes longer in musical time, and vice versa. This change can turn legato into staccato as the tempo is speeding up, and vice versa. Using shorter beats does not reduce this problem. Staccatos can even become more-than-legatos, leading to overlapping notes and MIDI unison conflicts. Running the UNLAP program which you may download from this site can at least avoid the overlaps.

A fancier Fit Improvisation command would adjust all times including note ends using a curve fit interpolation. In order to avoid unwanted tempo oscillations, the new command would also have to let you break the curve where there are sudden tempo changes, for example, between sections. Maybe in the next Cakewalk version? Maybe not.

Table of contents

Fit to Time

tFrom, tThru, tNewThru: these times may be displayed and entered in the Fit to Time dialog box in hours, minutes, seconds and frames, yet they are stored as musical time. You must use musical time for the CAL EditFitToTime parameters. This has an up side:  you can achieve much greater precision of musical timing using CAL than you can using the dialog box! The down side: if you use tempo changes in your music, you can't know just how much the real-time length is going to be expanded or contracted by this command. You could us the Slide command to measure the length in ticks of a given number or seconds or frames.

nMethod: 0: change tempo map; 1, change event times.

EditFitToTime40: This command is undocumented, but is invoked by the CAL recorder in CPA versions 4.5 and higher and in corresponding versions of other Cakewalk products.

BUG! The EditFitToTime command indicates an invalid number of parameters under Cakewalk versions 4.5 and higher. You must use EditFitToTime40 instead. Programs may be kept compatible with all versions by use of the VERSION constant. A CAL program downloadable from this site demonstrates how to do that.

Table of contents

Interpolate, Select by filter

These commands use the Event Filter. The Event Filter and related commands are complicated enough that I have given them their own article. Bug! The Interpolate command may work when being used in the CAL Recorder and then not work inside the CAL program. I had this happen under Cakewalk Pro Audio 8 when trying to use the command to move events to channel 1 from other channels. After discovering the bug, I used a forEachEvent loop instead, with the single line inside, (= Event.Chan 0). It worked..

Table of contents