Cakewalk Application Language Programming Guide

The
Cakewalk Application Language Programming Guide

for SONAR
Version: 2.2
Original author: D. Glen Gardenas
Editing and adaptations: Ton Valkenburgh
Review: Frans H.. !ergen
Febrar"# 2$# 2%&%
http://www!"#"$%itnl
Ton Valkenburgh
Contents
A word from the author and editor .................................................................................................... 8
Prefaces ............................................................................................................................................. 9
1 An overview .................................................................................................................................. 10
1.1 The nature of comuter rograms .......................................................................................... 10
! The Cakewalk Alication "anguage #undamentals .................................................................... 11
!.1 The s$nta% of Cakewalk Alication "anguage rograms ..................................................... 11
!.! &andling of event se'uences b$ Cakewalk Alication "anguage rograms ........................ 1(
!.) *ata t$es+ events+ variables+ and constants ........................................................................... 1,
!.).1 *ata t$es ....................................................................................................................... 1,
int ...................................................................................................................................... 1,
long ................................................................................................................................... 1-
word .................................................................................................................................. 1-
dword ................................................................................................................................ 1-
string ................................................................................................................................. 1-
!.).! .vents ............................................................................................................................. 1-
.vent.Chan ........................................................................................................................ 1-
.vent./ind ........................................................................................................................ 10
C&A1A#T ................................................................................................................... 10
ChanAft.Val .............................................................................................................. 10
C&23* ........................................................................................................................ 18
C21T32" ................................................................................................................... 18
Control.1um ............................................................................................................. 18
Control.Val ............................................................................................................... 18
.4P3.55621 .............................................................................................................. 18
&A63P61 ...................................................................................................................... 18
/.7A#T ...................................................................................................................... 18
/e$Aft./e$ .............................................................................................................. 18
/e$Aft.Val ............................................................................................................... 18
"736C .......................................................................................................................... 18
8C6 ............................................................................................................................... 19
12T. ............................................................................................................................. 19
1ote./e$ ................................................................................................................... 19
1ote.Vel ................................................................................................................... 19
1ote.*ur ................................................................................................................... 19
13P1 ............................................................................................................................ 19
PATC& ......................................................................................................................... 19
Patch.1um ................................................................................................................ 19
Patch.9ank ................................................................................................................ 19
3P1 .............................................................................................................................. !0
5754 ............................................................................................................................ !0
5754*ATA ................................................................................................................. !0
T.4T ............................................................................................................................ !0
:AV. .......................................................................................................................... !0
:&.." ........................................................................................................................ !0
:heel.Val .................................................................................................................. !0
.vent.Time ........................................................................................................................ !0
!.).) 8arker variables ............................................................................................................. !1
#rom .................................................................................................................................. !1
1ow ................................................................................................................................... !1
Thru ................................................................................................................................... !1
.nd .................................................................................................................................... !1
!.).( Constants ........................................................................................................................ !1
Cakewalk Alication "anguage Programming ;uide !.doc !<101
Ton Valkenburgh
#A"5. .............................................................................................................................. !1
T68.9A5. ....................................................................................................................... !1
T3=. ................................................................................................................................ !!
V.35621 ......................................................................................................................... !!
!.( #unctions ............................................................................................................................... !!
!.(.1 >for.ach.vent? @functionA? .......................................................................................... !!
!.(.! *eclaration 5tatements ................................................................................................... !)
>int @nameA B@valueAC? .................................................................................................... !(
>dword @nameA B@valueAC? .............................................................................................. !(
>long @nameA B@valueAC? ................................................................................................. !(
>string @nameA BDThis is te%tEC? ....................................................................................... !,
>undef @nameA? ................................................................................................................ !,
>word @nameA B@valueAC? ............................................................................................... !,
!.(.) Assignment #unctions .................................................................................................... !,
>F @variableA @valueA? ................................................................................................... !,
>GF @variableA @valueA? ................................................................................................. !-
>HF @variableA @valueA? ................................................................................................... !-
>IF @variableA @valueA? .................................................................................................. !-
><F @variableA @valueA? .................................................................................................. !-
>JF @variableA @valueA? ................................................................................................ !-
!.(.( 6nut functions ................................................................................................................ !-
>get6nt @nameA @romtA @minimumA @ma%imumA? ..................................................... !0
>get:ord @nameA @romtA @minimumA @ma%imumA? ................................................. !0
>getTime @nameA @romtA? ............................................................................................ !0
!.(., 2utut functions ............................................................................................................. !0
>message @oerand1A BB@oerand!AC KKC? .................................................................... !0
>ause @oerand1A BB@oerand!ACKKC? ........................................................................... !8
>format @oerand1A BB@oerand!ACKC? ............................................................................ !9
>send86*6 @ortA @channelA @kindA @data1A BB@data!ACK.C? ......................................... !9
!.(.- 9uffer functions .............................................................................................................. )0
>inde%? ............................................................................................................................... )0
>insert @timeA @channelA @kindA BKdata arametersKC? ................................................ )0
>delete? .............................................................................................................................. )1
!.(.0 8athematical functions .................................................................................................. )1
>G @oerand1A @oerand!A? ............................................................................................ )1
>H @oerand1A @oerand!A? ............................................................................................. )1
>I @oerand1A @oerand!A? ............................................................................................. )!
>< @oerand1A @oerand!A? .............................................................................................. )!
>J @oerand1A @oerand!A? ........................................................................................... )!
>GG @variableA? ................................................................................................................ )!
>HH @variableA? .................................................................................................................. )!
>random @minvalueA @ma%valueA? .................................................................................. ))
!.(.8 3elational functions ........................................................................................................ ))
>FF @oerand1A @oerand!A? .......................................................................................... ))
>LF @oerand1A @oerand!A? ........................................................................................... )(
>@ @oerand1A @oerand!A? ............................................................................................ )(
>@F @oerand1A @oerand!A? .......................................................................................... )(
>A @oerand1A @oerand!A? ............................................................................................ ),
>AF @oerand1A @oerand!A? ......................................................................................... ),
!.(.9 9oolean functions ........................................................................................................... ),
>MM @oerand1A @oerand!A? ......................................................................................... ),
>NN @oerand1A @oerand!A? ............................................................................................. )-
!.(.10 Control flow functions .................................................................................................. )-
Cakewalk Alication "anguage Programming ;uide !.doc )<101
Ton Valkenburgh
>do @e%ression1A BB@e%ression!ACKC? .......................................................................... )0
>while @conditionA @actionA? ........................................................................................... )8
>if @conditionA @trueHe%ressionA B@falseHe%ressionAC? ................................................ )9
>switch @inde%A @case1A @case1resultA B@case!A @case!resultA KC? .............................. (0
>include @filenameA? ........................................................................................................ (1
>*"" @EfilenameEA @rocedurenameA @argument1A .. @argument 1A? .......................... (1
!.(.11 8usical time functions ................................................................................................. (!
>meas @rawtimeA? ............................................................................................................. (!
>beat @rawtimeA? ............................................................................................................... (!
>tick @rawtimeA? ............................................................................................................... (!
>makeTime @measureA @beatA @tickA? ........................................................................... ()
!.(.1! 8iscellaneous functions ............................................................................................... ()
>error? ................................................................................................................................ ()
>e%it? .................................................................................................................................. ()
>dela$ @timeA? ................................................................................................................... ()
16" .................................................................................................................................... ((
!.(.1) 8enu functions ............................................................................................................. ((
!.(.1).1 .*6T 8enu #unctions .......................................................................................... (,
>.ditControl#ill B@fromA @thruA @ctrlA @chanA @begA @endAC? ................................... (,
>.ditCo$ B@fromA @thruA @eventsA @filtA @temosA @metersA @markersAC? .............. (,
>.ditCo$(0 B@eventsA @temosA @metersA @markersA @audioA @clisAC? .................. (,
>.ditCut B@fromA @thruA @eventsA @filtA @temosA @metersA @markersA @holeAC? . . . . (,
>.ditCut(0 B@eventsA @temosA @metersA @markersA @holeA @slitA @alignAC? .......... (-
>.dit*elete(0 B@eventsA @temosA @metersA @markersA @holeAB @slitA @alignACC? ... (-
>.dit#it6mrov B@referencetrackAC ................................................................................. (-
>.dit#it6mrov(0? .......................................................................................................... (-
>.dit#itToTime B@fromA @thruA @newthruA @methodA @stretchAC? .............................. (-
>.dit#itToTime(0 B@newthruA @methodA @stretchAC? ................................................... (0
>.dit;rooveOuantiPe B@fromA @thruA @filtA @resA @windowA @timeA @durA @velA
@owmA @grooveAC? ......................................................................................................... (0
>.dit;rooveOuantiPe(0 B@resA @windowA @timeA @durA @velA @owmA @fileA
@atternA @1"Aonl$AC ................................................................................................... (8
>.dit6nterolate B@nodialogAC? ....................................................................................... (8
>.dit"ength B@fromA @thruA @filtA @ercentA @startA @durAC? ..................................... (8
>.dit"ength(0 B@ercentA @startA @durA @stretchAC? .................................................... (9
.ditPaste B@toA @reA @modeA @eventsA @temosA @metersA @markersAC? ................. (9
>.ditPaste(0 B@alignA @linkA @toA @totrackA @onetrackA @reA @gaA @newcliA
@eventsA @temosA @metersA @markersA @modeA @slitAC? ......................................... (9
>.ditPastToTrack B@toA @reA @modeA @eventsA @temosA @metersA @markersA
@track?C? .......................................................................................................................... ,0
>.ditOuantiPe B@fromA @thruA @filtA @ercentA @timesA @durAC? ................................. ,0
>.ditOuantiPe(0 B@resA @ercentA @timesA @durA @swingA @windowA @offsetA
@1"Aonl$A @stretchAC? .................................................................................................. ,0
>.dit3etrograde B@fromA @thruA @filtAC? ...................................................................... ,1
>.dit3etrograde(0? ........................................................................................................ ,1
>.dit5lide B@fromA @thruA @filtA @amountA @unitsAC? .................................................. ,1
>.dit5lide(0 B@amountA @ticksA @eventsA @markersAC? ................................................ ,1
>.ditTransose B@fromA @thruA @filtA @amountA @diatonicAC? ..................................... ,1
>.ditTransose(0 B@amountA @diatonicA @audioAC? ...................................................... ,!
>.ditVelocit$5cale B@fromA @thruA @filtA @begA @endA @unitsctAC? .......................... ,!
>.ditVelocit$5cale(0 B@begA @endA @unitsctC? ........................................................... ,!
>3eset#ilter @t$eA @ever$thingA? ................................................................................. ,!
>5et#ilter/ind @t$eA @kindA @includeA? ..................................................................... ,!
Cakewalk Alication "anguage Programming ;uide !.doc (<101
Ton Valkenburgh
>5et#ilter3ange @t$eA @rangeA @inrangeA @minA @ma%A? .......................................... ,)
!.(.1).! #6". 8enu #unctions ........................................................................................... ,(
#ile.%tract B@athnameAC? ............................................................................................. ,(
>#ile8erge B@athnameAC? ............................................................................................. ,(
>#ile1ew B@temlateAC? ................................................................................................. ,(
>#ile2en B@athnameAC? .............................................................................................. ,(
>#ile5ave? ....................................................................................................................... ,(
>#ile5aveAs B@athnameAC? ........................................................................................... ,(
!.(.1).) ;2T2 8enu #unctions ........................................................................................ ,,
>;oto5earch B@noPromtAC? .......................................................................................... ,,
>;oto5earch1e%t? .......................................................................................................... ,,
!.(.1).( 5.TT61;5 8enu #unctions ................................................................................ ,,
>5ettingsChannelTable B@onA @n1A @n!A @n)A @n(A @n,A @n-A @n0A @n8A @n9A
@n10A @n11A @n1!A @n1)A @n1(A @n1,A @n1-AC? ....................................................... ,,
>5ettings8etronome B@la$A @recA @accA @countA @ortA @chanA @ke$A @velA @durA
@beeAC? ......................................................................................................................... ,,
>5ettings8idi6n B@n1A @n!A @n)A @n(A @n,A @n-A @n0A @n8A @n9A @n10A @n11A
@n1!A @n1)A @n1(A @n1,A @n1-AC? .............................................................................. ,,
>5ettings8idi2ut B@t%midirtA @sendcontA @sendsA @sdela$A @ctrlPeroA
@ctrlchaseAC? ................................................................................................................... ,,
>5ettings8idiThru B@modeA @ortA @chanA @ke$A @velA @localonortAC? .................. ,,
>5ettings3ecord#ilter B@noteA @ke$aftA @controlA @atchA @chanaftA @wheelAC? ........ ,,
!.(.1)., T3AC/ 8enu #unctions ...................................................................................... ,-
>TrackArchive B@archiveA B@trackACKC? ....................................................................... ,-
>TrackActive B@activeA B@trackACC? ............................................................................... ,-
>Track9ank B@bankA B@trackACC? ................................................................................... ,-
>TrackChannel B@chanA B@trackACC? ............................................................................... ,-
>Track/e$G B@amountA B@trackACC? ............................................................................... ,-
>Track1ame @nameA @trackA? ....................................................................................... ,-
>TrackPan B@anA B@trackACC? ........................................................................................ ,-
>TrackPatch B@atchA B@trackACC? .................................................................................. ,-
>TrackPort B@ortA B@trackACC? ...................................................................................... ,0
>Track5elect @stateA @trackA? ....................................................................................... ,0
>TrackTimeG B@ticksA B@trackACC? ................................................................................. ,0
>TrackVelG B@amountA B@trackACC? ................................................................................ ,0
>TrackVolume B@volumeA B@trackACC? ........................................................................... ,0
) Creating $our CA" rograms ........................................................................................................ ,8
( Programming techni'ues ............................................................................................................... ,9
(.1 Conventions ........................................................................................................................... ,9
(.1.1 Program header ............................................................................................................... ,9
(.1.! Variable names ............................................................................................................... -0
(.! .rror handling ........................................................................................................................ -1
(.!.1 Checking the marking of .vents ..................................................................................... -1
(.!.! Preventing overHrange Problems ..................................................................................... -!
(.!.!.1 6nut range checking ............................................................................................... -)
(.!.!.! Preventing internal overHrange errors ...................................................................... -)
(.) 8athematics ........................................................................................................................... -)
(.( 5ending 5754 messages ....................................................................................................... -(
(., 5witch Tree 8enus ................................................................................................................ -,
(.- 6mlementing 2nH"ine hel in a CA" rogram ..................................................................... --
(.0 9uilding an include librar$ .................................................................................................... -0
, Tis+ and workHarounds ................................................................................................................. 00
,.1 CA" Comatibilit$ ................................................................................................................ 00
Cakewalk Alication "anguage Programming ;uide !.doc ,<101
Ton Valkenburgh
,.1.1 *ownwards comatibilit$ ............................................................................................... 00
,.1.! =wards comatibilit$ .................................................................................................... 0!
,.! *etails of event se'uences ..................................................................................................... 0!
,.) Correcting se'uences which do not look se'uential ............................................................... 0)
,.( #orcing Version - >.dit6nterolate? To =se 8arkers ............................................................. 0)
,., .%licit and imlicit track selection ....................................................................................... 0)
,.- =sing the CA" View :indow ............................................................................................... 0,
,.-.1 .ntering CA" Te%t ......................................................................................................... 0,
,.-.! &idden tras in the CA" editor ....................................................................................... 0-
,.-.) 3ecording 8acros ........................................................................................................... 09
,.-.).1 PreHsetting .dit #unctions =sing 8acro 3ecord ..................................................... 80
,.-.( ;host 6n The 8achine .................................................................................................... 81
,.0 =nder the influence ................................................................................................................ 8!
,.8 CA" interactions with digital audio ....................................................................................... 8!
,.9 *etails on 3P1 and 13P1 Controller .vents ....................................................................... 8)
,.10 &elful Tis for =sing the *"" #unction ............................................................................ 8(
,.10.1 *ata T$esQ ................................................................................................................... 8(
,.10.! ParametersQ .................................................................................................................. 8(
,.10.) 8emor$ 8anagementQ .................................................................................................. 8,
,.10.( 8iscellaneousQ .............................................................................................................. 8,
- CA" .rror and #76 messages ....................................................................................................... 8-
Attemt to change constant ......................................................................................................... 8-
CA" .rror 001Q 5$nta% error ...................................................................................................... 8-
CA" .rror 00!Q *ivide b$ Pero .................................................................................................. 8-
CA" .rror 00)Q :rong number of arguments functionRname .................................................... 8-
CA" .rror 00(Q=nknown rocedure rocedureRname ............................................................... 80
CA" .rror 010Q T$es do not match ........................................................................................... 80
CA" .rror 01(Q Value out of range ............................................................................................ 80
CA" .rror 0!1 Program called >e%it? ......................................................................................... 80
CA" .rror 0!!Q =ser ressed cancel ........................................................................................... 80
CA" .rror 0!)Q Cannot oen include file fileRname .................................................................. 80
Cannot load *$namic "ink "ibrar$ ............................................................................................ 80
Command is disabled on the menu ............................................................................................. 80
.valuation stack overflow ........................................................................................................... 88
.%ression too comle% .............................................................................................................. 88
.%ected closing 'uote ............................................................................................................... 88
8iscellaneous error ..................................................................................................................... 88
8ismatched arentheses ............................................................................................................. 88
8issing one or more closing arentheses .................................................................................... 88
1ot valid in >for.ach.vent? or bod$ e%ression ......................................................................... 88
2ut of memor$ ............................................................................................................................ 88
Proc does not e%ist in *$namic "ink "ibrar$ ............................................................................. 89
Program called >error? ................................................................................................................. 89
=ndef of undefined variable ....................................................................................................... 89
=nknown variable ....................................................................................................................... 89
Valid onl$ in >for.ach.vent? or bod$ e%ression ....................................................................... 89
Variable redefined ...................................................................................................................... 89
0 .%amles ....................................................................................................................................... 90
Addition.cal ................................................................................................................................ 90
;8 8ode.cal .............................................................................................................................. 90
Program skeleton.cal ................................................................................................................... 90
5how version.cal ......................................................................................................................... 90
Timebase.cal ............................................................................................................................... 90
Cakewalk Alication "anguage Programming ;uide !.doc -<101
Ton Valkenburgh
8 "ibrar$ .......................................................................................................................................... 9!
G!H! meter.cal ............................................................................................................................. 9!
G)H( meter.cal ............................................................................................................................. 9!
G(H( meter.cal ............................................................................................................................. 9!
G-H8 meter.cal ............................................................................................................................. 9)
G9H8 meter.cal ............................................................................................................................. 9)
GConstant.cal .............................................................................................................................. 9)
GController.cal ............................................................................................................................ 9(
G.vents marked.cal ..................................................................................................................... 9(
G8eter.cal ................................................................................................................................... 9,
G8eter declarations.cal ............................................................................................................... 9,
Gneed version.cal ........................................................................................................................ 9-
9 6nformation sources ....................................................................................................................... 90
10 *ocument conventions ................................................................................................................ 98
10.1 9ackus 1auer #orm ............................................................................................................ 98
11 6nde% ........................................................................................................................................... 99
All roducts and coman$ names are
T8
or S trademarks of their resective owners. Cakewalk is a
trademark of Twelve Tone 5$stems inc.T :indows ).1+ :indows 9,+ :indows 98+ :indows !000+
:indows 4P+ :indows Vista and :indows 0 are trademarks of 8icrosoft incororation.
U Co$right 1998 H !010 b$ *. ;len ;ardenas and Ton Valkenburgh
This document can freel$ be used for ersonal uroses.
#or commercial alications contactQ midiHkit VPiggo.nl
Cakewalk Alication "anguage Programming ;uide !.doc 0<101
Ton Valkenburgh
A word from the author and editor
Over the past few years, producing music on the keyboard has been synonymous with the use of
sequencers, particularly PC based sequencer software. With the sophistication of off-the-shelf
sequencer packages for the PC, a person needs only to connect a !"! or serial keyboard to a
computer to start producing professional demos. !n fact, the software can even replace the
instrument if you are willing to take the time and care to enter notes by hand and edit in the #live$
feel. "o not think this cannot be done without sounding obviously unperformed. With a bit of time
and a creative touch, it is ama%ing what can be done with nothing else then a good synthesi%er, and
a computer running high-powered sequencer&editor software.
'he key to unleashing your creativity using any sequencer is to avail yourself to all of the tools it
provides. 'his is true regardless of how much or how little equipment, time or e(perience you have.
!f you want the best results, you must open all of the doors. !n this case, open all of the dialog
bo(es and menu lists. )ind out what your sequencer can do and use those tools to their limit. !f the
music is going to sound right, the editing must be right. *owever, as fle(ible as modern PC based
sequencers may be, it is impossible for any program to anticipate on the needs of each individual
musician. +ooner or later you will need to do something that goes beyond the limits of every menu
option. Customi%ing is the ne(t step. Within Cakewalk, you can do that with the Cakewalk
,pplication -anguage.
.
;len Cardenas created his tutorial W DThe 5ecrets of CakewalkXs CA" Programming #eatureE W in
1998. 6 discovered it on 6nternet. 6t heled me to understand some of the articulars of how the
CA" rograms interact with Cakewalk. &owever+ 6 still missed W as YoldX comuter rogrammer H
good reference material about the language and how to use secific Cakewalk concets within the
rograms.
Therefore+ 6 decided to restructure the information+ to add m$ secifics+ and to udate it for
Cakewalk 521A3. At the end+ 6 assume that it will be almost rewritten. &owever+ in the current
version readers+ who know ;lenXs :.9Hsite+ will still recognise arts of his tutorial. ;len
;ardenas+ who does not have time to udate his :.9Hsite+ gave me ermission to ublish this
document. 7ou ma$ e%ect that over time this document will deviate more and more from ;lenXs
tutorial.
Those of $ou+ who have e%erience in comuter rogramming+ will recogniPe this document H more
than ;lenXs tutorial H as a rogramming reference. 6 hoe W due to m$ e%erience as musician W that
it will also hel nonHrogrammers to understand the rogramming in the Cakewalk Alication
"anguage.
Ton Valkenburgh
1
Te%t from ;len ;ardenas+ coied out of his DThe 5ecrets of CakewalkXs CA" Programming
#eatureE.
Ton Valkenburgh
Prefaces
're(a)e with version 2 and 2.&
9ased on the review of #rans 9ergen+ 6 have udated+ and restructured the guide.
The main arts of the guide areQ
The CA" language >chater !?T
Creating the CA" rogram >chater )?T
Programming techni'ues >chater(?T
Tis+ and workHarounds >chater ,?.
6 have added more information about the Y*enu (un)tionsX. 6 have not tested all functions with
521A3+ and therefore cannot guarantee that the information is correct for 521A3. 8$ e%erience
has shown that eseciall$ in the Y*enu (un)tionsX there ma$ be changes comared with revious
Cakewalk version. This means there is still work to do in this area.
6 like to thank #rans 9ergen for reviewing this guide+ and his hel to imrove the 'ualit$.
're(a)e with version &.$
6 have imroved the e%lanation of the send86*6 function and added an e%amle in chater (Q
YProgramming techni'uesX. 6 added more routines to the librar$. The rest are editorial changes and
some restructuring of the document.
're(a)e with version &.+
Chater (Q XProgramming techni'uesX has been e%anded. 6n addition+ new librar$ rograms are
included which are used in tools of the 86*6H/it.
're(a)e with version &.2
6 have added more 521A3 secifics+ librar$ rograms+ and an inde%.
're(a)e with version &.&
6 have added some information about 521A3 secifics. 6 will add more in later versions of the
rogramming guide. 6 have added laceholders for more functions+ but did not describe them $et
e%licitl$. This version includes now descritions of the e%amle and librar$ rograms.
're(a)e with version &.%
This version is almost an unchanged co$ from the original :.9Hsite from ;len ;ardenas.
Ton Valkenburgh
1 An overview
9ased on the "65P s$nta% the Cakewalk Alication "anguage is not eas$ to understand for nonH
rogrammers W as most users of Cakewalk robabl$ are. Also it has unfortunatel$ man$
une%ected+ and unnecessar$ limitations+ which ma$ reduce its usage.
6n this rogramming guide the Cakewalk Alication "anguage will be e%lained+ and it can be
used as a reference to the features of the language.
6n addition a set useful routines are rovided+ which hels to overcome a coule of the limitations
in the language.
1ot ever$ se'uencer lets $ou H the user H create $our own custom editing functions. Cakewalk has
this feature. The Cakewalk Alication "anguage makes it one of the most owerful se'uencers.
The rogramming feature allows $ou to e%and Cakewalk to satisf$ $our needs. Zust because $ou
read the word Yprogra*X does not mean $ou need to be a certified rogrammer to create CA"
rograms. Although a background in comuter rogramming will give $ou some advantage in
learning CA"T all $ou reall$ need to know+ are a few basic concets and $ou must have a clear idea
of what $ou want to do with $our 86*6Hse'uence. Therefore+ it is imortant for the understanding
of this guide that $ou alread$ have a good understanding of the features of Cakewalk 521A3 for
:indows.
As far as CA" is concerned+ what we will discuss here alies to Cakewalk 521A3. &owever+ it
ma$ al$ to all versions of Cakewalk from version ) through version 9 too. *ue to limitations in
m$ time and the versions of Cakewalk in m$ ossession+ 6 onl$ tested with Cakewalk 521A3 ). 6
will reference to man$ of CakewalkXs features and will send little time e%laining them. 8uch
related information is in the userXs book and the Cakewalk hel files. 3ead these first+ get used to
what Cakewalk is alread$ able to do+ and then learn with this guide how to go be$ond these builtHin
functions+ and enter the world of CA" customiPing.
This document focuses on CA" rograms as written in 521A3+ using functions arranged as
rogram code. The information can also be used for earlier versions of Cakewalk. 5ecifics for
earlier versions of Cakewalk can be found in chaterQ ,Q YTis+ and workHaroundsX.
1.1 The nature of comuter rograms
9efore going into deth in the nature of writing comuter rograms we have to get a good feeling
how rograms will look like+ and how the$ differ from what we are used to in YnormalX live. This is
articular true for the Cakewalk Alication "anguage.
6t is not imortant to know how the se'uence data is formatted and stored in a comuter. 7ou onl$
need to know how it is resented to the rogrammer+ and how Cakewalk uses the rogram
statements to maniulate the data.
The best wa$ to learn the art
!
of rogramming is b$ starting with a simle e%isting rogram and
modif$ing it for $our own urose.
!
5oftware rogrammers like to state that rogramming is an art. To m$ view+ it is more a disciline.
Ton Valkenburgh
! The Cakewalk Alication "anguage #undamentals
CA" has data t$es+ events+ variables+ constants and functions+ which 6 will describe in this chater.
1ot all of this is documented in the Cakewalk documentation. 6 will make e%licit statements if the
function+ data t$e+ or whatever is an undocumented one. 3ealiPe that using undocumented features
can alwa$s give surrises+ because in later versions of CA" the$ can disaear or behave
differentl$.
!.1 The s$nta% of Cakewalk Alication "anguage rograms
A Cakewalk Alication "anguage looks different from what $ou are used to. Therefore+ we will
first e%lain how the s$nta% of this rogram language looks like.
"et us first write down a normal calculationQ
1 + 2
6n CA" it will look likeQ
(+ 1 2)
2f course+ both notations give the same resultQ +.
1ormall$ $ou will not maniulate numbers+ but data in $our 86*6Hse'uence. This data is
reresented as variables or events.
5o let us make our e%amle a little bit more abstractQ
(operator variable1 variable2)
The oerator in our e%amle is the ,. CA" has man$ other oerators. "ater we will mention them
all.
The s$nta% of CA" is like in "65P. 8athematical oerations like Daddition- and logical oerations
such as Dgreater than- are functions. That is first+ $ou list the function+ and then $ou list the
arguments+ or variables the function oerates on. /ee in mind that an argument can be a variable+
another function+ or even a grou of functions in arentheses. As humans+ we sa$ Ytwo plus three.
when we add. CA" sa$s Yplus two threeX instead. Zust remember+ in CA" $ou must alwa$s ut the
t$e of function to be erformed first followed b$ an$ arguments needed for the oeration.
6 will dig now further in the structure of the CA" rograms. :hen writing in CA" and in most
languages that use arentheses in this wa$+ the rogram statements are within arentheses. The
structure of a rogram isQ
(do (op var var) (op var var))
2f course mostl$ rograms are too big to fit on one line. Therefore+ the rogram code tends to be
arranged with one function on a line and the closing arenthesis of comle% functions >functions
made u with other functions? on their own lines. 6ndenting also makes the code readable. To
demonstrate this+ let us look at a logical rogram using filler words to reresent functions.
(do ; each program starts with a do statement
(declare a variable) ; then you declare variables
(declare another variable)
(forEachEvent
3
; then the functions of the program
(do
(something)
)
The D(orEa)hEventE function will be e%lained in chater !.(.1
Ton Valkenburgh
(another thing)
) ; end of do
) ; end of forEachEvent
) ; end of do
The DdoE indicates that a se'uence of functions will follow. Therefore+ the first DdoE indicates that
the rogram will have several functions one after another to be run one at a time. These will be the
first variable declaration+ the second declaration and the D(orEa)hEventE function. 6 will handle the
details of the D(orEa)hEventE function in chater !.(.1.
The reason for the declaration statements is+ that we must make sure variables are declared before
the$ are used b$ functions in the rogram code. 6n other words+ if $ou are going to use a variable to
hold the value of a note+ sa$ the highest note $ou wish some function to recogniPe+ and $ou wish to
call that variable+ then $ou must tell CA" to e%ect to see it in the code and to save room for it in
memor$ under its reviousl$ defined name. 6n this e%amle+ two variables are declared and then the
D(orEa)hEventE function is e%ecuted.
The DdoE after the D(orEa)hEventE statement lets CA" know that this loo is also made u of
several functions.
7ou can see b$ the colors how the closing arentheses associate with the oening arentheses. As
stated above $ou could also write the rogram like thisQ
(do (declare a variable) (declare another variable)(forEachEvent (do
(something) (another thing))))
8aking a rogram readable is half the [ob. :ith roer formatting+ $ou can match the closing
arenthesis with the oening ones b$ the indention. Adding comments
(
to that will hel even more+
and ensure that later $ou still can understand $our own rogram.
/eeing one function to a line also hels in maintaining a logical understanding of what the
rogram is doing along its various oints. Aside from making the code readable to humans+ CA"
could not care less if there is indention or if functions and closing arentheses are on their own
lines. The form is for $our own benefit. CA" does not care what the rogram code looks like+ the
rogram must onl$ be written following the s$nta% rules.
6 will go back to our original e%amle that 6 made more abstractQ
(operator variable1 variable2)
The oerator in this e%amle is the ,. CA" has man$ other oerators.
2f course+ $ou want to store the result in another variable. "ook at the following more comle%
statementQ
(= result (+ variable1 variable2))
&ow does this work\ CA" anal$Pes and rocesses first the information within the inner
arentheses+ and then the information within the outer arentheses. This is ver$ imortant to
remember for rogramming. The evaluation is form inside to outside.
1ow we must assign a value to the variables+ because otherwise we will not get an$ result.
*eending on its use the siPe of a variable can var$. #or numbers one of the used variable t$es is
the integer. The rogram will now look likeQ
(int variable1 1)
(int variable2 2)
(= result (+ variable1 variable2))
(
The te%ts behind the semiHcolon >/? are comments+ and ignored b$ CA".
Cakewalk Alication "anguage Programming ;uide !.doc 1!<101
Ton Valkenburgh
The roblem with this rogram is that $ou have to change it if $ou want to calculate e.g. + , 0.
:hat $ou reall$ want is that $ou do the calculation based on numbers+ which are entered b$ the
user. Therefore+ let us re'uest for user inut for each number. 6n this e%amle+ 6 have added
comments after the semicolon+ which is the normal wa$ of adding comments to a CA" rogram.
(int variable1 ) ;!he default value of variable1
; is
; is
(int result ) ;!he default value of the
; result is
(get"nt variable1 #$umber 1 = % &1 1) ;'e(uest input for variable 1
; with the te)t* $umber 1 =
; values between & 1 and 1
; are allowed
(get"nt variable2 #$umber 2 = % &1 1) ;'e(uest input for variable2
(= result (+ variable1 variable2)) ;+dd and store in result
(pause #'esult = % result) ;,isplay result and pause
6 use in this rogram the function Dget1ntE. This function romts the user with a te%t+ gets the
inut+ and stores it in an integer variable. The other function 6 added is DpauseE. This function
auses rocessing+ and romts the user with te%t. The te%t can be built u b$ using contents of
variables.
This is now almost a comlete rogram. &owever+ we have to add the start and begin indication of
the rogram. All CA" rograms are contained within a D2doE at the begin and a D3E at the end.
Therefore+ our rogram will look likeQ
(do
; is
; is
; result is
(get"nt variable1 #$umber 1 = % &1 1);'e(uest input for variable 1
; with the te)t $umber 1 =
; are allowed
(get"nt variable2 #$umber 2 = % &1 1);'e(uest input for variable2
) ; end of do
7ou see also two conventions+ which make reading the rogram easier. The statements within the
do statement are indented+ and to the closing arenthesis the commentQ / end o( do is added.
Comments are ver$ imortant. The rogram does not use them+ but the$ e%lain to the reader what
the rogram is suosed to do. 7ou should realise that+ if $ou do not add enough clear comments to
$our rograms+ that after some time+ $ou do not understand $our own rograms an$more.
Cakewalk Alication "anguage Programming ;uide !.doc 1)<101
Ton Valkenburgh
Therefore+ 6 show $ou now how the total rogram should look like. 7ou will find the rogram in
chater 0 as YAddition.calXQ
; +ddition-cal
; . /opyright 20 !- 1al2enburgh
; 1ersion 1-3 +pril 20
;
; !his routine adds two numbers-
; "nput parameters* 4$umber 1 = 4 (51--1)
; 4$umber 2 = 4 (51--1)
;
(do
; is
; is
; result is
(get"nt variable1 #$umber 1 = % &1 1);'e(uest input for variable 1
; with the te)t $umber 1 =
; are allowed
(get"nt variable2 #$umber 2 = % &1 1);'e(uest input for variable2
) ; end of do
; end of program
To run this rogram in 521A3+ $ou must select YRun 4alX from the Y'ro)essX menu+ or from the
YEditX or YToolsX in other versions+ and choose this rogram from the ones listed. 3un this rogram+
and see how the user interaction is. #or using editors in detail see chater ).
This rogram has nothing to do with music. CA" rograms will normall$ maniulate music events
in a se'uence of music event data. This e%amle rogram is onl$ created to show $ou the basic
s$nta%+ and structure of the Cakewalk Alication "anguage. 7ou must realiPe the nestled structure
of the language. This structure does not alwa$s make it eas$ to read the rograms+ but remember
the evaluation is from inside to outside.
!.! &andling of event se'uences b$ Cakewalk Alication "anguage
rograms
6t is imortant to realiPe that the se'uences are organiPed b$ track and event times. 6f $ou ask an
editor feature to oerate on events from time 4 to time 7 on tracks 1+ !+ and )+ the software will
start at time 4 and work on all of the events on track 1 until it reaches the last event at time T. 6t
will then start over at time 4 on track ! and do the same thing. 6t does this in one long ass+ first
one track and then the ne%t. 6f $ou build a CA" rogram that must kee W in $our mind H the events
on each track searate+ $ou can deend on CA" to oerate onl$ on the events in one track from the
Cakewalk Alication "anguage Programming ;uide !.doc 1(<101
Ton Valkenburgh
starting time at the D#romE marker to the end time at the DThruE marker before going on to the ne%t
track. The values of the D#romE and DThruE markers are shown in Cakewalk anel.
Time in a se'uence is different from the time $ou see on the screen. 6n a se'uence+ time is a raw
number of clock ticks stored as a double word >)! bit value? from 0 to (.!9 billion. 2n the screen
the raw time is disla$ed as Y*easureX+ YbeatX and Yti)kX or Y:!:TX time. The raw time is
converted to Y:!:TX time according to the value stored in DT68.9A5.E
,
. #or settings of 1!0
ticks er 'uarter note and a meter of
(
<
(
+ there are (80 ticks er measure. CA" has functions that can
convert the YrawX time and Y:!:TX time back and forth taking $our settings into account.
CA" works on selected tracks+ or art of selected tracks. To run CA" rograms+ $ou would set the
D#romE and DThruE markers and highlight the track or tracks $ou wish to maniulate [ust as if $ou
were about to use the YTransposeX or Y5uanti6eX or an$ other feature in the YEditX menu. CA"
rograms will do nothing or une%ected things if no track or art of a track is selected. 6
recommend to add checking in $our rogram whether a selection has been made. CA" does not
rovide secial functions for that. Therefore+ 6 will describe in chater (.!.1 YChecking the marking
of .ventsX how this can be done.
!.) *ata t$es+ events+ variables+ and constants
8ost of the data t$es+ events and constants in the following ages will look familiar to an$one
who has dabbled in CA". 7ou can also find brief descritions in the Cakewalk hel files. The truth
of the matter is that there will likel$ be things here comletel$ new to even veteran users because so
much about CA" is undocumented. 6 have run into allot of the information in this tutorial b$
e%erimentation+ luck and accident. /ee in mind that this comilation is based on m$ ersonal
e%erience. That means that there ma$ be more than 6 have documented here+ and that 6 cannot
alwa$s guarantee that this information base is absolutel$ comlete. 6t is+ however+ a more comlete
source of information on CA" as 6 have encountered an$where else+ and so hoe it will be of
significant value to an$one who seeks enlightenment on the toic of CA".
2.3.1 Data types
There are five data t$es in CA" and each is of somewhat different use. The main difference
between the t$es is the siPe of number it can hold >aside from the DstringE t$e+ which is for te%t?.
.ach can be assigned to a variable of $our own making+ but which is best for what kind of variable
deends on the use to which it will be ut. &ere is a rundown of the five t$es listed b$ the
abbreviation $ou will use when referencing them in a CA" rogram. 1ote that the$ must be selled
e%actl$ as $ou see them here in order for CA" to recogniPe them.
7ou must be careful with mi%ing data t$es in calculations+ because this can give une%ected
results.
int
An DintE stands for a signed 1-Hbit integer and is the most common data t$e. 6t is a whole number
ranging from negative )!-0- to ositive )!0-0. 7ou will use the DintE data t$e for most of $our
flags+ loo counters+ temorar$ buffers+ and [ust about an$thing that does not involve large values.
There is an imortant asect. Assume $ou are going to scale values. 7ou take a number+ multil$ it
b$ some factor+ and then divide it back down to a smaller number again. 7ou must ensure that
variable is big enough to hold the temorar$ results of such scaling even if the result would be well
within the limits of an integer t$e.
,
To set the number of Yti)ks per 7uarter8noteX 7ou select from the YOptionsX menu+ the Y'ro9e)t
OptionsX heading+ then the Y4lo)kX tab+ and the Yti)ks per 7uarter8noteX.
Cakewalk Alication "anguage Programming ;uide !.doc 1,<101
Ton Valkenburgh
long
A DlongE is a signed )!Hbit integer that can range from roughl$ ositive to negative ! billion. &ere
is some roomL This is a good variable to declare if $ou think $ou will be overHranging an integerXs
value during calculations.
word
A DwordE is an unsigned 1-Hbit integer that goes from 0 to -,,)-. This whole number will alwa$s
be ositive. 1ote durationXs are stored as DwordE values. Again+ if $ou are going to be la$ing
around with a duration value+ $ou might want to declare a variable larger than this one [ust in case
$ou send the value over the to at some oint before $ou have a chance to correct it.
dword
A DdwordE >double word? is an unsigned )!Hbit integer that can range from 0 to over ( billion.
.vent times are stored as double words. There is no variable t$e bigger+ but none is likel$ to be
needed in that ( billion ticks at 1!0 ticks er 'uarter note would run almost 9 million measures.
.ven :agner would have had a hard time writing a score that longL
string
A DstringE is a series of A5C66 characters between double 'uotes+ or to ut it siml$+ it is te%t. 7ou
can declare strings+ build strings and send strings to some functions that use te%t+ but unfortunatel$+
$ou cannot inut a string during the running of a CA" rogram. A string will look likeQ
#!his is a string%
2.3.2 Events
CA" rovides for our use several builtHin variables and constants. The most imortant for ever$da$
use are the constants and variables that corresond to the t$es of events in a se'uence and the
various arameters or data variables that belong to each one. 7ou should memoriPe the following
list if $ou lan to do a lot of work in CA". Again 6 must stress that $ou must use e%actl$ the same
selling+ caitaliPation and unctuation format as $ou see here in order to use them. 1ote that man$
CA" internal variables have a eriod between words+ use caital letters in the middle of names and
other odd things.
1ormall$ $ou refer to variables and constants b$ name. &owever+ the$ have an internal number
which 6 also resent.
All events have arameters kind+ time+ and channel. All event arameters are stored in variables.
Event.4han
CA" uts that 86*6 channel number in this variable when an event is being scanned b$ the
D(orEa)hEventE loo. There are two things to remember about event channel assignments. #irst+
this channel number will have no effect uon what channel the event will be sent over if the track in
which it resides has a channel assignment. The track channel will alwa$s override the event
channel. 6f the track has no assigned channel+ then the event channel determines the final channel it
will be sent over. 5econd+ even though we number the 86*6 channels from 1 through 1-+ Cakewalk
internall$ numbers them one digit lower from 0 to 1,. Therefore+ in a CA" rogram $ou must use 0
to 1, for channels.
Cakewalk Alication "anguage Programming ;uide !.doc 1-<101
Ton Valkenburgh
As a side note+ the same is true for track number assignments. :e see tracks 1 through !,- and
CA" sees them as 0 through !,,.
Event.:ind
CA" manages this variable and $ou should not attemt to assign a value to it. CA" gives it a value
based on the secific t$e of event in the se'uence currentl$ being accessed during a
D(orEa)hEventE loo. The secific number this variable holds+ is of little imortance. =suall$ it is
not necessar$ to view it or calculate with it. Zust for the record+ the number it holds will be 1(( if
the event is a note+ 10- if the event is a controller+ !!( if the event is a itch wheel and so on. The
reason $ou donXt need to know this >e%cet for downwards comatibilit$ issues as noted above? is
that there are constants in CA" >see below? that e'ual those numbers and all we need to do is see if
D.vent./indE is e'ual to one or more of them. 1ote that the two words DEventE and D:indE have a
eriod and no saces between them. This will be the case with allot of these CA" variables+ so a$
attention to this detail.

.vent kinds areQ
DC&A1A#TE >Channel after touch? D12T.E
DC&23*E D13P1E >1onHregistered Parameter 1umber?
DC21T32"E DPATC&E
D.4P3.55621E E3P1E >3egistered Parameter 1umber
D&A63P61E >D5754E+ D5754*ATAE >5$stem .%clusive
data message?
D/.7A#TE >/e$ after touch? DT.4TE
D"736CE D:AV.E >Audio?
D8C6E >:indows 8edia Control 6nterface
command?
D:&.."E
The constantsQ DC&23*E+ D.4P3.55621E+ D&A63P61E+ D"736CE+ D8C6E+ D13P1E+ D3P1E+
D5754E+ D5754*ATAE+ DT.4TE+ D:AV.E allow an D.vent./indE test to locate these D.ventsE
in a se'uence+ and $et there are no rovisions for viewing+ accessing or changing the values
associated with them. This makes their use rather limited to merel$ hunting for this t$e of event+
but not being able to do an$thing with it+ once it has been found+ e%cet deleting themL
1evertheless+ 6 list them here mostl$ because+ for man$ of them+ their e%istence as the$ relate to
CA" is undocumented. These constants are onl$ available in the versions of Cakewalk that suort
these data t$es as art of their feature ackage.
4H;<;FT
This DEventE constant is e'ual to !08 and is the D4hannel ;(ter tou)hE event. 1ot all
s$nthesiPers suort it. DC&A1A#TE has onl$ the variableQ value.
ChanAft.Val
The one variable associated with a D4hannel ;(tertou)hE event holds the strength of the after
touch. 6t is an DintE and can be from 0 to 1!0.
Ton Valkenburgh
4HORD
Chord names can be added to a se'uence to assist guitar la$ers following along with the music.
These events are entered in the D5TA##E View. The constant e'uals 0. CA" rograms cannot
access the variables.
4O<TRO=
This is the DEventE that holds the constant value 10- for a controller event. "ike D12T.E+ we
use this constant+ among other things+ to test D.vent./indE to see if the current event is a
controller.
DC21T32"E will have the variables number and value.
Control.Num
CA" sets this variable with the controller number value for events that are of the DC21T32"E
kind. #or e%amle+ a value of 0 corresonds to a volume controller event and 10 to a an
controller event. Changing this value changes the t$e of controller we are working with. This
variable is of the DintE t$e and can range from 0 to 1!0.
Control.Val
The value or strength of a controller event is laced in this variable. 6t is an DintE and ranges
from 0 to 1!0. Changing this value changes the amount of controller action for this event.
E>'RE??1O<
The e%ression event e'uals ,+ and can be inserted into a se'uence in the Y?ta((X view. The$
guide a musician in the erformance of a iece. The event does not affect the 86*6
erformanceT it is a staff view event onl$ >be aware that it is not the same as 86*6 controller
11?. CA" cannot access its variables.
H;1R'1<
These events corresond to the *iminuendo and Crescendo marks available in the Y?ta((X view.
Their constant e'uals -. The event does not affect the 86*6 erformanceT it is a staff view event
onl$. CA" cannot access its variables.
:E@;FT
The D/.7A#TE >Yke" a(tertou)hX? event is denoted b$ this constant of 1-0. 5ome s$nthesiPers
do not recogniPe this event+ and still others will receive it but not send it. D/.7A#TE has the
variablesQ ke$+ and value.
KeyAft.Key
CA" fills in this variable with the itch number when it sees a D/.7A#TE event. "ike
D1ote./e$E+ it is an DintE from 0 to 1!0 and denotes the itch or in this case+ the h$sical ke$
number associated with the event.
KeyAft.Val
CA" gives us this value when the D.vent./indE is a D/.7A#TE. "ike the D1ote.VelE variable+
it is of t$e DintE and denotes the strength of the Ya(tertou)hX in values from 0 to 1!0.
=@R14
This constant e'uals !. The data associated with this event is a single s$llable or word that is to
be sung at that instant in the song. These l$rics can be disla$ed during la$back in the Y?ta((X
view. The variable contains a single te%t word of s$llable+ and is not accessible b$ CA".
Ton Valkenburgh
41
An 8C6 command tells :indows to do something with one of its multimedia devices at that
instant in the song. 5ee the user manual or the :indows 8ultimedia ProgrammersX 3eference
for more details. 6ts constant value is (. The variable contains the 8C6 command te%t. CA"
cannot access its variables.
<OTE
This is one of the events that allow us to test D.vent./indE and also to assign the event within an
DinsertE function. 5iml$ ut+ D12T.E alwa$s e'uals the number 1((+ which is the CA" value
for a note event.
A D12T.E will have the variablesQ ke$+ velocit$+ and duration.
Note.Key
This variable is one of the arameters of a D12T.E event. 6t contains the itch number of the
note. 6t is of t$e DintE or integer and can range in value from 0 to 1!0. CA" fills in this variable
with the itch value whenever D.vent./indE e'uals D12T.E+ and $ou are free to work with+
calculate with or even change this value if $ou want to alter the itch of the note event.
Note.Vel
&ere is another arameter of a D12T.E event. 6t is of t$e DintE and contains the velocit$ of the
note. 6t can range in value from 0 to 1!0. "ike D1ote./e$E+ CA" fills in the value for us
whenever the current event is a D12T.E and we are free to use and change it as we see fit in
order to change the noteXs velocit$.
Note.Dur
The duration in ticks of the note event is available to us through this variable. 6t is of t$e
DwordE+ can range from 0 to -,,), and is rovided b$ CA" when the D.vent./indE e'uals
D12T.E. Changing this value moves the 86*6 D<ote O((E message for that note back and forth
in time relative to the D<ote OnE message.
<R'<
The D13P1E or D<on8Registered 'ara*eter <u*berE+ which is 10+ are clusters of four
controller messages which Cakewalk versions - and above+ and man$ s$nthesiPers read as single
messages. .arlier Cakewalk versions can send and receive them+ but the$ aear as clusters of
controller messages. .ach D13P1E event contains two numbers+ a arameter value and a data
value+ each being a number between 0 and 1-)8). CA" cannot access the variables.
6f access to such controller events is imortant to $ou+ such as the e%amle of accessing itch
bend deth+ then see the chater ,.9 Y *etails on 3P1 and 13P1 Controller .vents X for a wa$
around this roblem.
';T4H
This event e'uals 19! and denotes a atch change. DPATC&E will have the variablesQ number+
and bank.
Patch.Num
As $ou might guess+ this is the atch number associated with the DPATC&E event. 6t is an DintE
from 0 to 1!0.
Patch.Bank
The instrument bank can be found or changed in a DPATC&E event as well+ and this variable
contains the bank number. 6t can range from H1 to 1-)8) with H1 meaning Dunde(inedE.
Ton Valkenburgh
R'<
The D3P1E or DRegistered 'ara*eter <u*berE+ which is 9+ are clusters of four controller
messages which Cakewalk versions - and above+ and man$ s$nthesiPers read as single
messages. .arlier Cakewalk versions can send and receive them+ but the$ aear as clusters of
controller messages. .ach D3P1E event contains two numbers+ a arameter value and a data
value+ each being a number between 0 and 1-)8). CA" cannot access the variables.
6f access to such controller events is imortant to $ou+ such as the e%amle of accessing itch
bend deth+ then see the chater ,.9 Y *etails on 3P1 and 13P1 Controller .vents X for a wa$
around this roblem.
?@?>
This constant e'uals 0 and is for a D?"ste* EA)lusive !ankE message. 6ts e%istence is
documented as a CA" constant even though it is imossible to access the data associated with
the event. The variable contains the 5$s% bank number >0H!,,?. The bank actuall$ holds the
data. The variable is not accessible b$ CA".
?@?>D;T;
5$stem .%clusive data is 86*6]s wa$ of letting each s$nthesiPer manufacturer transmit rivate
data about their roducts. The constant value is 8. A 5$stem .%clusive message has a
manufacturer 6*T the rest of the message is comletel$ rorietar$ and varies for each
manufacturer+ even for each of their roducts.
D5754*ATAE has the actual data b$tes to be sent as art of the event data. Again+ none of this
data is accessible.
TE>T
Te%t events e'ual 1. The$ are sort of like notes $ou write to $ourself and lace in the se'uence
to serve as documentation or reminders. T.4T will not be visible in the 5taff view. CA" cannot
detect T.4T events. :hen a test is done on a T.4T .vent+ CA" will do a test on a D"736CE
event.
The variable contains te%t+ but is also not accessible b$ CA".
B;VE
This value of ) corresonds to the D;udioE events that can be added to a se'uence. The
variables areQ name+ velocit$+ and number of samles. The variables are not accessible b$ CA".
BHEE=
This constant identifies a itch wheel event. 6t e'uals !!(. D:&.."E will have the variableQ
value.
heel.Val
&ere we have a variable that can be ositive or negative. 6t is of t$e DintE and ranges from 8191
to H819!. :hen we have a D:&.."E event+ CA" fills in this variable with the itch bend
amount. :e are free to change it as we see fit+ but remember+ be reared to deal with either a
ositive or negative value.
Event.Ti*e
CA" fills it with the DrawE time of whatever event is being evaluated b$ the D(orEa)hEventE loo.
6t can also be assigned a value to change the time of an event or wIhen inserting events. 6t is of t$e
DdwordE and so can be from 0 to over ( billion.
Cakewalk Alication "anguage Programming ;uide !.doc !0<101
Ton Valkenburgh
2.3.3 !arker var"a#les
Fro*
This variable is the same as the D#romE marker in the Cakewalk front anel. 6t is the starting oint
for the sele)ted art of a se'uence. This value can be changed during the running of a CA"
rogram an$ lace other than within a D(orEa)hEventE loo. This makes sense in that the
D(orEa)hEventE loo oerates on events starting at the time stored in D#romE and so cannot alter
its own starting oint. D#romE is of t$e DdwordE and so can range from 0 to over ( billion. 6f+
during a CA" rogram+ $ou change the value stored in D#romE before a D(orEa)hEventE loo+ the
loo will start at this new location in the se'uence. Thus+ $ou can make the assigning of this
variable+ and so the starting oint of the loo+ sub[ect to conditions or calculation results within the
rogram itself. This can be ver$ hand$L /ee in mind+ however+ that [ust as Cakewalk will not
allow $ou to assign D#romE a number larger than the value stored in DThruE+ neither will CA". The
offending value will be automaticall$ reassigned to correct the condition.
<ow
This variable corresonds to the osition of the bar cursor in the se'uence and holds the value
visible in the D1owE time window on the screen. 6t is the lace where la$back would start if the
Y'la"X button were clicked on the front anel. 6t has little use in CA". There are some strange
limitations to the siPe of numbers this marker variable can hold. .ven though it is )! bits wide+
assigning it a number close to that limit can crash some Cakewalk versions earlier than 0. 5ee the
chater ,.-.! Y &idden tras in the CA" editor X for more information.
Thru
DThruE is the same as D#romE e%cet+ of course+ being the end marker of the selected art of a
se'uence. .ver$thing said above about D#romE alies to DThruE.
End
The final marker variable is reall$ a Yread8onl"X variable. 6t holds the location of the end of the
se'uence and thus cannot be changed from within a CA" rogram.
2.3.$ Constants
As a useful convention+ CA" constants are named with all caital letters so the$ are eas$ to sot.
F;=?E
This is a boolean constant is the other side of the DT3=.E<E#A"5.E coin. 6t holds a value of Y%X.
5ee the definition for DT3=.E below for details.
T1E!;?E
This constant rovides the number of ticks er 'uarter note the user has selected for keeing time in
Cakewalk. The default value Cakewalk rovides when it is installed+ is deending on the version of
Cakewalk<521A3+ but can be changed b$ the user.
-
9ecause CA" sees time as the number of ticks
-
6n certain >sub? versions of 521A3 ) the DT68.9A5.E constant does not var$ with the user
setting+ and will alwa$s be 9-0. This means that 521A3 will work with a wrongl$ calculated raw time.
The b$ass for this bug is to set the ticks er 'uarter notes on 9-0. This will then become the new default.
Ton Valkenburgh
from the start of the se'uence >referred to as YrawX time? and humans see it as the number of
measures+ beats and ticks in the comosition >referred to as Y:!:TX time?+ this value is an
imortant factor in e'uations that must take both time keeing s$stems into account.
This Y)onstantX is a variable from the user oint of viewT because it can be set for each ro[ect.
CA" cannot change DT68.9A5.-.
TRCE
This is a boolean constant that holds a value of Y&X. This constant is used in functions that re'uire a
9oolean value of "es or no in order to signif$ the selecting or deHselecting of some arameter. #or
e%amle+ if $ou are setting u an DEdit4op"E function+ there are arguments that corresond to the
check bo%es used to set u the YEditX menu Y4op"X command. 6n order to translate to CA" the act
of checking or unchecking these bo%es+ the corresonding variables will be given a value of Y&X for
checked or Y%X for unchecked. 6t is allowable to substitute the constants DT3=.E and D#A"5.E for
Y&X and Y%X in these arguments.
VER?1O<
This constant contains the version of CA" currentl$ running on the userXs comuter. 6tXs
undo)u*ented+ but useful as an error checker. A test should be made at the start of ever$ CA"
rogram to make sure the user has the roer version of CA" to run the rogram. This is most
convenientl$ done using the Din)ludeE function to run a small CA" rogram called Y<eed2%.4;=X
from within an$ larger rogram to check this DV.35621E value and abort if it shows that an
incomatible version of CA" is running. 6f $ou are creating CA" rograms that can onl$ run on
higher versions of CA"+ $ou can use the in the Y"ibrar$X >chater 8? rovided include rogram
YGneed version.calX which test the CA" level based on inut from the calling rogram.
The version number consists of a version and subHversion+ divided b$ a dot. CA" does not use the
dot. This means that e.g. a version !.0 is seen in CA" as !0.
!.( #unctions
:ithout the abilit$ to alter the values in variables+ a rogram would not be of much use. 6t is with
this in mind that we now introduce the various wa$s that we can maniulate the variables listed in
the revious chaters. 3emember+ all of the operations $ou will be looking at in this section are
real functions. That means that the wa$ the elements of the oeration are ordered will follow the
rules of function s$nta% and as such robabl$ look a bit weird to $ou at first. Zust kee in mind that
as with all functions+ the function name >or in some cases+ s$mbol? comes first followed in proper
order b$ the arguments that will be oerated on.
6n the e%amles+ 6 will sometimes use not $et described items+ but 6 still believe that the e%amles
hel to make things clear. :e will start with a ver$ imortant function in CA". 6t is ke$ to
understand this function+ because it is one of the basics of CA" oeration.
2.$.1 %forEachEvent& 'funct"on(&
As alread$ stated earlier+ CA" rograms mostl$ will maniulate selected events in the selected
tracks. The defined actions within the function D(orEa)hEventE al$ to the selected .vents. 6n a
rogram it will look likeQ
(forEachEvent (function))
or more like $ou are used to seeingQ
:ith the samle rogram YTimebase.calY. $ou can check whether $our version of Cakewalk has this bug.
Cakewalk Alication "anguage Programming ;uide !.doc !!<101
Ton Valkenburgh
(forEachEvent
(function)
)
As alread$ mentioned+ this function is the ma[or workhorse of CA". 6t takes the events in the
selected art of the se'uence >the area between D#romE and DThruE on the tracks $ou have
highlighted? and runs each event through it has nested functions+ one event at a time and in
se'uential order+ until all of the events have been scanned. 6t then aborts and CA" continues with
the ne%t function after the looXs closing arenthesis. 7ou can run as man$ D(orEa)hEventE loos
as $ou want in a CA" rogram so long as $ou donXt tr$ to run one inside of another.
The D(orEa)hEventE function can have onl$ one function in its nest. 6n order to get things done+
that function is often a comound function made u of nested functions. This comound function is
usuall$ a DdoE or an Di(E function with lots of nested functions like soQ
(forEachEvent
(do
(somefunction)
(anotherfunction)
(morefunctions)
)
)
The DdoE tells CA" that even though it would e%ect onl$ one function for this loo+ there will be
several instead. This is because the three functions are not nested together. .ach stands alone. :e
therefore use DdoE to create a nest for them all to share so that the D(orEa)hEventE loo still sees
[ust one function. The function DdoE will be e%lained in the chater !.(.10 Q YControl flow
functionsX.
:hen this loo is running+ CA" laces the kind of event currentl$ being serviced in the variable
D.vent./indE+ the eventXs starting time in D.vent.TimeE and 86*6 channel in D.vent.ChanE. The
eventXs arameters are laced in the other event variables as alies. 1otes will have their
arameters available in D1ote./e$E+ D1ote.VelE and D1ote.*urE and so on for each t$e. Also
during the running of this loo+ the marker variables D#romE+ DThruE and D1owE are no longer
resonsive to an$ changes $ou might tr$ to make to them.
*uring this rocessing CA" kees a co$ of the selected events. 6f $ou insert a new event at an
D.vent.TimeE higher than the sot the loo is currentl$ at+ CA" will not see the new event when it
comes to the new eventXs time until the loo is over. 6f $ou were to run a second D(orEa)hEventE
loo+ the events inserted b$ the last loo would be available to this new loo.
2.$.2 Declarat"on )tatements
CA" allows $ou to initialiPe variables+ but does not allow $ou to define constants. 6f $ou want to
use a constant in $our rogram $ou have e.g. to declare an integer with the re'uired value.
<ote: 9efore using a variable in a CA" rogram+ $ou must first have declared this variable.
Cakewalk Alication "anguage Programming ;uide !.doc !)<101
Ton Valkenburgh
(int 6name7 86value79)
D

This declares an integer that $ou can name whatever $ou want. 7ou should use names that hel
remind $ou of the variable urose such as YhighnoteX or Y)ounterX. After the name comes the
otional value+ it will be initialiPed to. 6f nothing else+ initialiPe it to Pero. 3ealiPe that if the
variable does not get his initial value+ that the value cannot be redicted.
7ou can also initialiPe a variable to the value of another variable so long as the latter has been
declared and initialiPed. 5uose $ou declare a variable like
(int range 12)
and $ou want to declare another variable later that e'uals YrangeX. Also+ suose that in the
meantime+ YrangeX has been sub[ected to other functions and so it is value is unknown. 7ou could
do it like thisQ
(int lowpoint range)
and now YlowpointX will be initialiPed to whatever value currentl$ resides in YrangeX. 7ou could
also have declared YlowpointX and initialiPed it to Pero at the same time $ou declare DrangeE and
then when the time comes [ust set YlowpointX e'ual to YrangeX like
(= lowpoint range)
which is the usual course of action. 6f $ou are one of those efficienc$ freaks that must use the
absolute minimum number of statements to erform a task+ $ou can save $ourself the e%tra Ye7ualX
function b$ declaring at the time of assigning the value instead. Another wa$ to save a few b$tes is
to chain the declaration of like variables. This means that $ou can list several variable names on the
line after the DintE ke$word+ each searated >YdelineatedX in geek seak? b$ a sace+ and then at the
end given an initial value. All of them will be initialiPed to that same value. 5uch a statement might
look like thisQ
(int first second last loop lownote highnote ma)vel minvel temp )
6n this statement+ all of the variables listed from Y(irstX through Yte*pX would be declared as
integers and initialiPed to Pero. 6 donXt like to do this because as luck would have it+ at some oint 6
might need to change the initial value of a variable as 6Xm shaking down m$ rogram and would
have to edit this statement to remove the offending variable and then write a new one [ust for it. 6
like to kee m$ variables searate so all 6 have to do to change them is alter one statement. 6t also
makes them easier to read and kee track of. 3emember that an DintE has a range of H)!-0- to
)!0-0 so be sure all of $our integer variables will sta$ in that range throughout the running of $our
rogram.
(dword 6name7 86value79)
This declares a double word called Yna*eX initialiPed to a value of YvalueX. These variables are
ositive onl$ and can range from 0 to (+!9(+9-0+!9,. .ver$thing said about DintE alies here as
well.
(long 6name7 86value79)
This declares a long variable. 6t is able to swing lus or minus !.1( billion. Again+ the rules are the
same as noted above.
0
@nameA indicates a re'uired arameter nameT
B@valueAC indicates an otional arameter valueT
arameters can be constants+ variables+ or functions.
5ee also chater 10Q Y*ocument conventionsX Y 9ackus 1auer #orm X.
Cakewalk Alication "anguage Programming ;uide !.doc !(<101
Ton Valkenburgh
(string 6name7 8#!his is te)t%9)
&ere we have a variable declared as a string called Yna*eX and initialiPed to the te%t enclosed in
double quotes. 5trings can be ver$ useful when we want our CA" rogram to generate track names
or some such. "ike its kind above+ $ou can chain declare multile string variables and initialiPe
them all to the te%t in 'uotes+ but 6 see little use for such an occurrence. There is a limit to the siPe
of a string variable+ 1!- characters. 3arel$ would a string of more that twoHdoPen characters be
needed+ so that issue will robabl$ never come u in general use.
(undef 6name7)
This function unde(ines or erases from memor$ the ocket occuied b$ a variable and deletes its
name from the list of declared variables. 6t works on an$ variable $ou have declared using an$ of
the above data t$es. This is a wa$ of freeing u memor$ for new variables after a current one has
outlived its usefulness. 6t can come in hand$ for erasing large variables like double words to make
room for more integers for e%amle. #rom time to time+ 6 have run into the limits of CA"Xs abilit$
to kee u with too man$ variables. The use 6 tend to ut this function to the most is undefining
variables that an included rogram declares+ but does not need to ass back to the arent rogram.
5ee chater !.(.10 for an e%lanation of the Din)ludeE function.
(word 6name7 86value79)
This statement declares a word variable named Yna*eX with an initial YvalueX. .ver$thing
mentioned above alies here. 6ts range is limited to ositive numbers and can go from 0 to -,,)-.
2.$.3 Ass"*nment +unct"ons
The following are mathematical assignment functions. The$ start with the most basic+ the Ye'ualsX
function+ but then slide into a gra$ area between assignment and mathematical. 6 will list them here
before the mathematical functions the$ emulate because the$ do ossess assignment characteristics.
(= 6variable7 6value7)
This De7ualE function assigns the value of YvalueX to the YvariableX. Take a close look at the
sentence $ou [ust readL 6t is YvariableX that will be assigned and YvalueX that holds the master value
that will be assed on b$ the De7ualE function+ not the other wa$ around. 6n .nglish+ it would read
Y?tore the value into the variableX. *o not get confused on the direction of flow in this and all
following mathematical functions+ as it is eas$ to do given the "65P s$nta% of CA". 1ot
surrisingl$+ that YvalueX can be a variable like D#romE+ or even another function. #or e%amle+ $ou
could have something likeQ
(= lowrange (5 $ote-:ey base))
&ere+ the variable YlowrangeX is set e'ual to the result of subtracting YbaseX from D1ote./e$E.
1otice the arentheses. The function D*inusD with its two arguments must be enclosed b$ its own
set of arentheses+ but this does not lessen the necessit$ of enclosing the De7ualE function with a
comlete set of arentheses as well.
Cakewalk Alication "anguage Programming ;uide !.doc !,<101
Ton Valkenburgh
(+= 6variable7 6value7)
This assignment function acts as a form of shorthand for making a variable e'ual to itself as
modified b$ a value. 6n .nglish+ this would read Y;dd the value to the variable and store the
result into the variableX. As with an$ e'uation+ YvariableX can be a constant or another function. 6n
CA" longhand+ it would readQ
(= variable (+ variable value))
9$ the wa$+ the double use of YvariableX in this longhand e%amle is legal. 7ou can use the same
variable as both destination and source because CA" first does the calculations and then asses the
result to the destination variable. This wa$+ the contents of the variable are safel$ reserved until
after it is used in the calculation+ and onl$ then+ it is changed to its new value. The D,EE function is
siml$ a bit more efficient.
(5= 6variable7 6value7)
(;= 6variable7 6value7)
(<= 6variable7 6value7)
These are [ust like the first e%amle >D,EE? e%cet the$ reresent subtraction+ multilication and
division resectivel$.
(== 6variable7 6value7)
This one ma$ take some e%laining. The ercent sign means YFind the *odulo valueX. A modulo
value is the remainder left over after dividing the first variable b$ the second >value?. CA" does not
see fractions+ fractional amounts or decimal values. 6t deals strictl$ in whole numbers. Therefore+ if
$ou divide 9 b$ 8+ $ou will get an answer of 1. 7ou will get the same result for dividing 9 b$ 0+ 9
b$ -+ or 9 b$ ,. The result of dividing 9 b$ ( would be !. The remainder left over b$ an$ of these
divisions is onl$ available b$ obtaining the modulo value. The modulo value from dividing 9 b$ 8
is 1+ as that is the remainder from dividing them. #or 9 b$ 0 the modulo value would be !+ for 9 b$
- it would be ) and so on. :e can use this value after erforming a DdivideE function for various
uroses such as rounding. =sing the modulo assignment function is a bit more obscure than the
rest of our mathematical assignments described above. :e are more likel$ to use a modulo value in
the conventional mathematical functions.
2.$.$ ,nput funct"ons
2nce we declare a variable+ it is a fair gameL &owever+ there will be man$ times when the
oeration of a CA" rogram will deend on the abilit$ of the user to set some of the arameters.
Thus+ we come to the DgetE statements. There is a DgetE statement for the integer and word and a
secial wa$ of entering a double word+ as we will see shortl$. There is no inut statement for the
string unfortunatel$T it would be nice to inut strings from time to time. &owever+ alas+ we have not
the lu%ur$. As far as the numerical variables go+ we are free to 'uer$ the user for inut at an$ time
using the following statementsQ
Cakewalk Alication "anguage Programming ;uide !.doc !-<101
Ton Valkenburgh
(get"nt 6name7 6prompt7 6minimum7 6ma)imum7)
(get>ord 6name7 6prompt7 6minimum7 6ma)imum7)
As should be obvious+ each statement is meant for a secific data t$e. 1ote how the DgetE art is in
lower case and then without an$ sace comes the name of the data t$e with its first letter
caitaliPed. 1e%t comes the name of the variable we are giving the user the oortunit$ to change.
Then comes a DstringE that will serve as the romt for the user. 6t can be an$thing $ou wish to
conve$+ [ust limit it to less that a screenXs width because the resulting dialog bo% will sill off the
screen. "ast+ come the restrictions $ou can lace on the userXs resonse in the form of two values.
This is otional but recommended. The first is the smallest+ or in the case of an DintE+ the lowest
value $ou will allow. The second is the highest value allowed. As 6 mentioned earlier in this
document+ 6 like to leave a sace or two at the end of the romt before closing the 'uotes. The
reason is that the dialog bo% disla$s a small window after the romt containing the current value
of the variable and a blinking cursor. The saces allow a bit of esthetic room between the te%t and
that little window. The user can [ust hit YEnterX or click YO:X and accet the current value or can
enter a new value and then hit YEnterX or click YO:X. 6f the$ attemt to enter a value outside the
limits $ou have set with Y*ini*u*X and Y*aAi*u*X+ an error bo% aears disla$ing those limits
and allows the user to tr$ again until an accetable value is entered. 7our choice of Y*ini*u*X
and Y*aAi*u*X will deend on the nature of the variable. 6f $ou are re'uesting a 86*6 channel
number+ the limits should be 1 and 1-. 6f $ou are re'uesting a itch+ $ou would use 0 and 1!0 as
$our limits and so on.
(get!ime 6name7 6prompt7)
This is a bit different in that the user is to enter a time value in Y*easureX+ YbeatX and Yti)kX that
CA" will convert into YrawX time and assign to the double word variable Yna*eX. This variable
*ust be of t$e DdwordE and alread$ been declared. /ee in mind that $ou can have a Yti)kX value
of %+ but YbeatX and Y*easureX must be a value of at least &. Also+ if $ou enter a beat that does not
e%ist+ such as - in (<( time+ or a value of Yti)kX greater than the value set in DT68.9A5.E+ CA"
will convert the values an$wa$ b$ multil$ing the number of YbeatX b$ DT68.9A5.E and adding
to the result the value in Yti)kX. 6f $ou reconstruct the YrawX time back into Y:!:TX time >see
D*akeTi*eE in chater !.(.11Q Y8usical time functionsX?+ all of the values will be corrected to
disla$ a roer time given the Y*eterX and DT68.9A5.E values in use during that Cakewalk
session.
8
'he other difference is that C,- will not allow the use of -m"n"mum/ and 0ma."mum/
limits for #getTi*e$. ,ttempting to use limits, results in a 0/ron* num#er of ar*uments/ error at
run time.
2.$.0 1utput funct"ons
CA" gives us the chance to send information and data to the user and to the 86*6 ort. Along with
these outut functions we will also discuss the D(or*atE function+ which converts variable data into
te%t for e.g. use within functions which laces te%t into the YTra)kX view screen fields >and thus
into the se'uence file?.
(message 6operand17 886operand279 ??9)
This function laces a message on the status bar at the bottom of the screen. 6t does not interrut the
oeration of the rogram+ [ust disla$s the message. The D*essageE oerands can be strings >te%t
between double 'uotes?+ integers >DintE+ DwordE+ DdwordE?+ or a function. The D*essageE function
8
This feature has a bug in it for CA" versions 0 and 8. The >DgetTi*eE? dialog+ which is suosed to
re'uest user inut in Y:!:TX time+ instead will onl$ accet YrawX time.
Ton Valkenburgh
will disla$ the oerands in the form of numbers or an$ mi%ture of the two. There is an imortant
thing to consider about sending messages to the status bar. :hile a D(orEa)hEventE loo is
running+ CA" has e%clusive access to the status bar. &owever+ outside this loo+ an$thing CA" uts
there can be overwritten b$ a Cakewalk internal function message like letting $ou know that an
Y;utosaveX is going on. Y;utosaveX can haen during CA" rograms. #or that reason+ $ou cannot
be assured the message will be there long enough for the user to read it. 1eedless to sa$+ after the
CA" rogram ends and suosing there is no Y;utosaveX rocessing+ [ust ointing the mouse at a
disla$ field will relace the message with the descrition of what the cursor is ointing at. 6f the
ointer haens to be over such a sot when CA" stos+ an$ message will be immediatel$
overwritten. This aside+ the message is a good wa$ to let the user know where the rogram is and
that it is alive and running+ less the user anic during a long loo and think the s$stem has locked
u. There is a rice to a$ for this functionQ time. 6t takes longer to run a CA" rogram if there is
constant udating to the status bar. Consider this code fragmentQ
(forEachEvent
(do
(message #@rocessing Event A # (inde)))
(if (so on and so on------
CA" will be sending a new message to the screen ever$ time the D(orEa)hEventE starts a new
ass. :hile this can be a great wa$ of keeing the user transfi%ed on the status bar as numbers
flicker b$ at a rate too fast to read+ it also slows down the s$stem a little. 7ou must weigh the costs
and benefits of roviding such an ongoing tall$ message. 3emember to leave a sace between
closing 'uotes and variables because unlike some versions of 9A56C+ CA" does not format the
disla$ of variables and te%t for $ou.
(pause 6operand17 886operand279??9)
This is similar to the DmessageE function and again $ou can combine strings+ integers >DintE+
DwordE+ DdwordE?+ or functions. The difference is that DauseE halts e%ecution of the CA" rogram
and disla$s a dialog bo% in the middle of the screen containing the information the user rovides in
the function statement lus YO:X and Y4an)elX buttons. The user must click YO:X or hit the YEnterX
ke$ to acknowledge the DpauseE bo% before the rogram will continue. The user can also click the
Y4an)elX button or hit the YEs)X ke$ and abort the CA" rogram comletel$.
9

9esides disla$ing information critical to the userXs decision to continue the rogram or cancel+ the
DpauseE is a great troubleshooting tool for rogrammers. 6f a CA" rogram is not acting 'uite right
or if $ou want to verif$ the oeration of some art of a rogram+ $ou can lace DauseE statements
at ke$ locations in the code to disla$ the contents of some imortant variables and see if things are
running as lanned. 1ote this e%amleQ
(if (7 something somevalue)
(do
(pause #'eached first test- somevalue = # somevalue)
(go on about your business-----
&ere a DpauseE has been laced at the YthenX art of an Di(E function to hel verif$ if that function
is being called. 6f it is+ the DpauseE tells the rogrammer where the rogram currentl$ is and what
the current value of variable Yso*evalueX is. After the rogrammer hits YEnterX or clicks YOkX+ the
rogram goes on as if nothing ever haened. 9$ the wa$+ there is a limit of 1!8 characters for a
DpauseE message+ so if $ou have allot of information to give out+ it ma$ re'uire more than one
DpauseE bo% to deliver it.
9
9$ the wa$+ hitting the YEs)X ke$ at an$ time in the running of a CA" rogram will cause it to abort
and e%it.
Ton Valkenburgh
(format 6operand17 886operand279?9)
"ike the D*essageE and DpauseE functions above+ D(or*atE takes an$ combination of strings and
integers values >DintE+ DwordE+ DdwordE?+ or functions and generates a string that can be assed to
another function or assigned to a DstringE variable. Take this e%amleQ
(int trac2 )
(string name #$o $ote Bas Ceen Dound%)
(forEachEvent
(if (== Event-:ind $E!E)
(do
(= name (format #$ote $umber # $ote-:ey)
(!rac2$ame name trac2)
(++ trac2)
)
)
)
:hat we have done here is declare an integer variable that we will use for track numbers and
initialiPe it to 0 so it oints to the first track
10
. 1e%t+ we declare a string variable and initialiPe it to a
default te%t string. 1e%t+ we enter a D(orEa)hEventE loo and our Di(E function filters out an$thing
e%cet notes. #or each note we find+ we use format to convert D1ote./e$E into a number and
combine it with the te%t string in 'uotes. The result is assigned to the string variable YnameX and
using the DTra)k<a*eE function+ we lace this te%t in the onHscreen Y<a*eX field for track number
Ytra)kX. 1ow we increment Ytra)kX so that uon the ne%t occurrence of a note+ it will oint to the
ne%t track and we loo again. :hen the rogram stos+ aside whatever else the rogram containing
this fragment does+ it will have named tracks for each note in the selected art of the se'uence. 6f
$ou wanted to eliminate the Ytra)kX variable all together+ $ou could relace the first two statements
after the Di(E with this single statementQ
(!rac2$ame (format #$ote $umber # $ote-:ey) trac2)
As a art of this rogram+ $ou would also likel$ end u cutting out all of the notes of each itch and
asting them into the aroriatel$ named tracks. This is useful with ercussion tracks where itXs
convenient to searate each ercussion instrument onto its own track so it can be maniulated
indeendentl$.
(sendF"," 6port7 6channel7 62ind7 6data17 886data279?-9)
&&
7ou can send a 86*6 event during a CA" rogram with this function.
=se YportX as the ort number >0 .. 1,? $ou want to send over. 6f YportX is set to H1+ the function will
send the message through all orts. The Y)hannelX variable is the channel number >0 .. 1,? and H1
will set the function to send over all channels. The YkindX constant is one of the recogniPed event
t$es such as D12T.E or DC21T32"E [ust like with the DinsertE function. =se Ydata&X and
Ydata2X for the information to be sent. 1ot all event kinds use both data b$tes+ and $ou must use the
roer formatting of the data b$tes for the event in 'uestion. Ydata2X is onl$ valid for D12T.E+
DC21T32"E + and D/.7A#TE. 3emember+ 86*6 data b$tes must be between 0 and 1!0 e%cet
for t$e D5754E >s$stem e%clusive message?.
10
3emember+ we see tracks 1 through !,- and CA" sees them as tracks 0 through !,,.
11
This function onl$ works for CA" versions above ).1. The version number ).1 is resented as )1 within
CA".
Ton Valkenburgh
The D5754E message is formatted b$ sending the number !(0 >#0? before Ydata&X+ and after
sending the number !(0 >#0? after $our last data.
1!
Check $our s$nthesiser 86*6 imlementation
secifications for details on how to use s$stem e%clusive messages with $our instrument.
The value of @channelA will be ignored for D5754E messages.
2.$.2 Buffer funct"ons
The buffer functions work on the se'uence itself. The$ are DinsertE+ DdeleteE and DindeAE. These
functions add+ subtract and disla$ the osition of an event in the se'uence. This will make sense as
we look at them.
(inde))
This function returns the number of the event being scanned b$ a D(orEa)hEventE loo as it is
ordered within a track se'uence >buffer?. The ver$ first event in a track se'uence is numbered 0 and
the ne%t 1+ then ! and so on. 6f $ou delete an event+ all events after it are moved back in number so
that the event following the deleted one now has its number. 6nserting an event causes all events
after it to move u in number to make room and so on. 6 have seen onl$ two alications for
DindeAE. 2ne is in a D*essageE function to tell the user how man$ events have been scanned+ the
other is in an DifE function to let the rogram know that it has reached the first event on a new track
b$ testing for >F F >inde%? 0?.
(insert 6time7 6channel7 62ind7 8?data parameters?9)
6n this function we use the ke$word DinsertE followed b$ the raw time where we want the event
inserted into the se'uence. This is followed b$ the 86*6 channel number we wish the event to be
assigned and then the kind of event we wish to insert. The YdataX variables corresond to the
arameters for that kind of event. 1ot all event t$es will need all three YdataX variables. &ere is a
rundown of secific DinsertE functions for each event t$eQ
(insert time channel $E!E 2ey velocity duration)
(insert time channel /E$!'EG number value)
(insert time channel >BEEG value)
(insert time channel @+!/B number ban2) ;!he 4ban2H variable is optional
(insert time channel :EI+D! 2ey value)
(insert time channel /B+$+D! value)
As $ou might guess+ the ke$word DinsertE and the constant for the event t$e such as D12T.E and
D:&.."E must aear in $our function as shown+ but all of the other arts can be variables or
functions as $ou re'uire. 6f $ou erform an DinsertE in a D(orEa)hEventE loo+ the event is
inserted into whatever track is currentl$ being scanned.
1)
6f $ou have more than one track
highlighted+ $ou ma$ have a hard time knowing when the loo has ended one track and gone on to
the ne%t one. Then again+ it ma$ not matter roviding the insert is ke$ed to the events around it. 6f
the insert is not within a D(orEa)hEventE loo+ it will be inserted into the track highlighted b$ the
cursor
1(
regardless of whether or not there are other tracks selected or where the tracks fall
numericall$. The YbankX number in the Y'at)hX DinsertE function is otional. 6f it is not sulied+ it
is assumed to be the same as assigning it H1+ which means YnoneX and shows u as Y888Y to the user
in the YTra)kX view.
1!
8ake sure that $ou do not include these D5754E message start b$te #0 and end b$te #0+ in $our data+
because CA" will sul$ them. 5ee also the rogram E;8 8ode.calE for an imlementation.
1)
The recommended aroach is to use DinsertE within a D(orEa)hEventE loo.
1(
5ee also chater ,.,Q Y.%licit and imlicit track selectionX.
Cakewalk Alication "anguage Programming ;uide !.doc )0<101
Ton Valkenburgh
(delete)
This function is onl$ usable within a D(orEa)hEventE loo and will delete from the se'uence the
event currentl$ being scanned b$ the loo. 6t has no arguments or data associated with it. &e is [ust
the hatchet man and he works alone. 2nce an event is deleted+ it is gone forever. 6f $ou first store
all the information about the event before $ou delete it+ it can then be reinserted later using the
DinsertE function. These two make a good team when writing rograms that must store an event
and then act uon it based on information gained from another event during another ass of the
D(orEa)hEventE loo. 3emember+ the events scanned b$ that loo are onl$ available for
maniulation during that ass of the loo. 2nce the loo starts on another ass+ the first event is out
of reach and a new event becomes the focus of the loo. 6n order to change an event after the loo
has assed it+ $ou must store the event in variables and then delete it while the loo is scanning it.
"ater+ once $ou have whatever information $ou need to alter the event+ $ou can then reinsert it back
into the se'uence at its original event time regardless of where the loo currentl$ is.
2.$.3 !athemat"cal funct"ons
"et us move right into the mathematical functions. The$ are ver$ straight forward+ and b$ now
should be eas$ to follow assuming $ou have made it this far without frothing at the mouth and
falling into a coma. 3emember that these mathematical statements are functions and as such+ the
YoerationX comes first followed b$ the variables to be oerated on. 6f it hels make sense of the
s$nta%+ in $our mind [ust move the oerator from in front of the function to in between the variables
and the$ will seem more familiar. This will also hel kee straight the order of oeration in
subtraction+ division and in relational functions.
(+ 6operand17 6operand27)
This is simle enough. :e add the value of oerand! to oerand1 and send the result to whatever
function contains this function. 6n short+ there is no YtargetX or destination imlied b$ [ust this
function alone. 7ou will use it within another larger function+ most likel$ with an De7ualE
assignment sending the result to a third variable. #or e%amle+ we might do something likeQ
(= $ote-1el (+ hammer baseline))
in order to set the velocit$ of a note e'ual to the sum of two variables. As $ou might guess+ one or
both of these variables could also be constants or other functions such asQ
(= $ote-,ur (+ (+ offset pastdur) (5 Event-!ime lasttime)))
&ere note duration is set e'ual to the sum of an offset amount and a stored duration lus the
difference between the eventXs starting time and another stored time. 1otice the wa$ the functions
stack. 6f $ou were to relace an$ of the nested functions with values+ the order of the larger
functionXs arts and mathematical oerations would sta$ the same. 3emember+ CA" does not care
if $ou use variables+ constants or nested functions as arguments. 6t is all the same to CA". The
lacement of the DplusE ke$words and arentheses never changes. 7ou [ust stack them when the
functions take on nested functions.
(5 6operand17 6operand27)
Take a close look at this function. :ith the addition function above+ the order of the variables did
not matter. Addition gives the same result adding !G) and )G! due to addition being
Y)o**utativeX. This is not the case for subtraction. This statement reads in .nglish Y?ubtra)t
(ro* operand& the value in operand2X+ or siml$+ Yoperand& *inus operand2X. *onXt get the
order mi%ed u or $ou will have all kinds of roblems. 2therwise+ the rules for using D8D are the
same as for using D,E.
Ton Valkenburgh
(; 6operand17 6operand27)
This is multilication. &ere the order does not matter. Zust make sure $ou do not overrun the range
limits of $our variables. The rules for using this function are as described above.
(< 6operand17 6operand27)
*ivision also has a secific order of the oerands. This statement reads in .nglish Ydivide
operand& b" operand2X. /ee in mind that CA" does not see fractions and does not round off.
The result of division in CA" is the integer value onl$. 7ou must use the D*oduloE function below
to obtain the remainder of the division. 2therwise+ the rules mentioned above al$.
(= 6operand17 6operand27)
9ecause CA" does not use fraction and does not round off division+ we use the D*oduloE function
to obtain the fractional art of a division. The result of >J @oerand1A @oerand!A? is the integer
number left over after subtracting Yoperand2X from Yoperand&X over and over >which is the act of
division? until there is a remainder that is less than Yoperand2X and thus there can be no further
subtraction without sending the result negative. This remainder is the fraction of Yoperand&X left
over from the division. #or e%amle+ if !) were divided b$ $+ the answer would be 0 and the
remainder would be +. Thus+ in CA"+ the function >< !) (? would result in an answer of 0 and >J !)
(? would result in an answer of +. &ere is how $ou would use this function to round of division.
1ote the following formula for obtaining an average.
(= average (< sum count))
(if (7= (= sum count) (< count 2)) (++ average))
#irst+ the average is found b$ dividing the sum of numbers b$ the total of numbers that were
summed. Assume we have added (, numbers together and the total was !!8(,. Therefore+ Ysu*X is
!!8(, and Y)ountX is (,. :e divide the two to get the average and the answer is ,00.-0. 9ecause
CA" does not see fractions and will not round+ the answer for the first function above will be the
integer ,00. &owever+ for accurac$+ we would want to round off this number to ,08. The second
function does that b$ taking the remainder of the division of !!8(, b$ (,+ which is )0+ and seeing if
this remainder is greater than or e'ual to half of count+ or half of (,. 6f it is+ then we increment
YaverageX and get ,08 instead of ,00. 6f $ou look at a CA" rogram sulied with Cakewalk called
YThin )ontroller data.)alX+ which is a rogram that thins out controller events b$ deleting ever$
1th event+ $ou will see the modulo function used to locate that 1th event b$ counting and dividing+
and whenever it sees a remainder of 0+ an event is deleted. .ver$thing said about using and setting
u the other mathematical functions alies to the D*oduloE function as well.
(++ 6variable7)
&ere is a secial case of a combo mathematical < assignment function. This siml$ adds 1 to the
value of YvariableX. This is referred to as Yin)re*entingX a variable and often haens in
association with counting the occurrence of some kind of condition. 5uch things as counting the
number of times a DwhileE loo has e%ecuted or tall$ing the number of notes encountered are
handled b$ the Din)re*entE function.
(55 6variable7)
This is the same thing as incrementing e%cet it subtracts 1 from a variable. This is known as
Yde)re*entingX and has a lot of the same uses including countdown timers and so on. /ee in
Cakewalk Alication "anguage Programming ;uide !.doc )!<101
Ton Valkenburgh
mind that it is a bad idea to let a variable decrement below Pero unless the variable can handle
negative numbers.
(random 6minvalue7 6ma)value7)
Although this is sort of an assignment function+ 6 lace it here because it+ like the rest of these
mathematical functions+ has no imlied destination for the result and must therefore be a nested
function of a larger function. :hat this gu$ does is come u with a seudoHrandom number that can
be an$ number starting with Y*invalueX u to Y*aAvalueX. The reason it is called a pseudo8
rando* number is that if $ou did nothing but call this function and $our comuter e%ecuted the
e%act same number of machine c$cles between each numberXs outut+ the results would eventuall$
form a reeating attern and as such would be redictable and not trul$ random. 6n ractice+
however+ the results are random enough for an$thing one might want to use the function. 8ostl$+ it
is used to generate random notes or timing offsets for making comuter generated music or
hu*ani6ing >fluctuating slightl$? the starting times of notes that have been handHentered or
'uantiPed.
2.$.4 5elat"onal funct"ons
3elational functions have nothing to do with the mating habits of CA" rograms >disaointed\
5orr$?. :hat these functions do is test arguments for there relative values b$ making comarisons.
6Xm sure once $ouXve seen them+ the$Xll make sense. =sing these functions does not change the
values of an$ variables and does not result in a numerical result >well+ it reall$ does+ but we donXt
care what that number result is?. The outcome of running relational functions is either DT3=.E or
D#A"5.E+ and as far as we care+ this is all we need to know about their outut. Zust for the record+
the numerical result for a condition being D#A"5.E is % and for being DT3=.E is an$ other
number+ usuall$ &. "ike the mathematical functions+ these functions do not stand alone but make u
the condition statements of DifE and DwhileE functions. 6n order for CA" to make a decision+ it
needs to test some condition and lan its course of action based on the outcome. :e will see man$
e%amles of these statements+ as conditional tests make u the heart of man$ CA" rograms.
This first grou make comarisons between two arguments and offer a result. 2ne argument can be
comared as being e'ual to the other+ not e'ual to the other+ larger than the other+ smaller than the
other or some combination.
(== 6operand17 6operand27)
This function tests for e'ualit$ between two oerands e.g. a variable and a constant. .ither or both
oerands could also be functions instead. The oint is that the result will be DT3=.E if the two
arguments are De7ualE to each other and D#A"5.E if the$ are not. 1otice that the ke$word >DEEE?
is made u of two e'ual signs+ and there is to be no sace between them. 6f $ou remember from an
earlier art of this document+ there can be some confusion between the use of a single e'ual sign
that means Y?tore operand2 into operand&X and these double e'ual signs that mean YTest to see i(
operand& is e7ual to operand2X. 6n the first case+ Yoperand&X has its value reassigned and in the
second case nothing changes and onl$ a condition is tested for. =sing such a statement with an DifE
function is the most common form. &ere is an e%amleQ
(forEachEvent
(+= $ote-1el 1)
)
)
Cakewalk Alication "anguage Programming ;uide !.doc ))<101
Ton Valkenburgh
6n this e%amle we comare the value CA" has rovided us in D.vent./indE with the event kind
D12T.E to see if the current event in our D(orEa)hEventE loo is a note. 6f it is+ then the nested
function that makes u the XthenX art of our Di(E function is carried out. 6n this case+ the note
velocit$ is increased b$ 10. 6f the event had not been a note+ the Di(E condition would have failed
and no action would have been taken on the event.
(J= 6operand17 6operand27)
This is the oosite of the above function. &ere we test for the two oerands being une'ual. The
result is DT3=.E if the values of the variables are different and D#A"5.E if the$ are e'ual. As
alwa$s+ we could use a constant for one of the variables and<or nested functions for one or both of
them. &ere is an e%amle of using DFEE.
(forEachEvent
(if (== Event-:ind /E$!'EG)
(if (J= /ontrol-$um K)
(delete)
)
)
)
&ere we test each event during a D(orEa)hEventE loo to find onl$ controller events. &aving found
one+ we test to see if the event is not a volume controller >controller number 0? and if it isnXt+ we
delete it. :hen we look at the 9oolean functions+ 6Xll show $ou how to make this same rogram
fragment more efficient b$ combining the test for controller events and test for the controller not
being number 0 into a single Di(E statement >see in chater !.(.9Q the logical D;<DE function?.
As $ou might guess+ this statement tests for Yoperand&X being less than Yoperand2X. :e might use
this function to segregate items or variables as in this e%amleQ
(if (6 $ote-:ey L0)
(+= $ote-1el 1)
)
This little fragment tests to see if the current note event has a itch less than -(+ or .) in 86*6 note
form+ and if so raises the noteXs velocit$ b$ 10. The usual rules for using constants and functions in
lace of variables al$.
(6= 6operand17 6operand27)
A variation on the above function+ this one results DT3=.E if Yoperand&X is less than or e'ual to
Yoperand2X. 6f we had to do this in long hand as art of an Di(E function+ it would look like thisQ
(if (MM (6 variable+ variableC) (== variable+ variableC))
(somefunction)
)
6 have used the 9oolean DORE function to create the long hand version. This statement reads Y1(
either variable; is less than variable! or variable; e7uals variable! then return a result o(
GTRCE- and run 2so*e(un)tion3X. As $ou can see+ the DHEE shorthand is suerior. The same Di(E
statement above now readsQ
Cakewalk Alication "anguage Programming ;uide !.doc )(<101
Ton Valkenburgh
(if (6= variable+ variableC)
(somefunction)
)
which is much easier to read and work with.
As the obvious comlement to the above DHE function+ this one tests for Yoperand&X being greater
than Yoperand2X.
(7= 6operand17 6operand27)
:e finish this grou with the Dgreater than or e7ualE function. 6t works like the others shown
before.
2.$.6 Boolean funct"ons
The two 9oolean functions derive from classical logic. The two oerator ke$words CA" uses are
logical D;<DE and logical DORE. 6n the academic world+ these oerators are associated with a
Ytruth tableX which describes the outcome of al$ing 9oolean logic to a set of conditions. 6 will
save $ou the trouble b$ sa$ing it in simle .nglish.
(NN 6operand17 6operand27)
This is the logical D;<DE function. As with the other relational functions+ the 9oolean functions
are not meant to stand alone but are to be used as oerands for Di(E and DwhileE functions. &ere+
Yoperand&X and Yoperand2X al$ to an$ statement that roduces an outcome. Although it is
ossible to use a variable alone as a condition+ in that its ver$ e%istence defines an outcome+ the
most ractical alication is to make the Y)onditionsX relational functions. #irst+ let me e%lain
what logical D;<DE means. 5iml$ ut+ the outcome of the D;<DE function will be DT3=.E if
and onl$ if both Yoperand&X and Yoperand2X are DT3=.E. &ere is an e%amleQ
(if (NN (== $ote-:ey basenote) ( 7 $ote-1el minlevel))
(insert Event-!ime Event-/han $E!E (+ $ote-:ey 12) $ote-1el $ote-,ur)
)
:ith this e%amle+ we test to see if both the current note itch is e'ual to a itch number stored in
YbasenoteX and the note has a velocit$ greater than the value stored in Y*inlevelX. 6f both of these
conditions are met+ then we insert a new note at the current noteXs event time and on the current
noteXs channel with the current noteXs velocit$ and duration+ but one octave higher in itch. 6f either
of the conditions had been D#A"5.E+ the entire Di(E statement would have been D#A"5.E and thus+
no new note would be inserted. As romised+ 6 will now show how to make more efficient
conditional statements using 9oolean functions. 6f $ou recall earlier we had an e%amle that went
like thisQ
(forEachEvent
(if (== Event-:ind /E$!'EG)
(if (J= /ontrol-$um K)
(delete)
)
)
Cakewalk Alication "anguage Programming ;uide !.doc ),<101
Ton Valkenburgh
)
:e can ut both conditions in one statement using D;<DE like soQ
(forEachEvent
(if (NN (== Event-:ind /E$!'EG) (J= /ontrol-$um K))
(delete)
)
)
This makes the code a bit more comact and clear.
There is a limit as to how man$ individual functions $ou can stack in a single statement like this. At
some oint+ CA" will give $ou an Y.valuation stack overflowX error if $ou get too carried awa$.
(MM 6operand17 6operand27)
The other 9oolean function is the logical DORE. #or this statement to be DT3=.E+ either one of the
oerands or both must be DT3=.E. The DORE functions resolves to D#A"5.E onl$ if both
conditions are D#A"5.E. 7ou can think of DORE as the inverse of D;<DE. &ere is an e%amle of
an DORE functionQ
(while (MM (6 count L0) (6 time Event-!ime))
(do
(insert time Event-/han /E$!'EG K count)
(++ time)
(++ count)
)
)
Ah+ the DwhileE loo functionL 6 will go into how the DwhileE loo works in chater !.(.10+ but for
now understand that a DwhileE loo e%ecutes its nested functions until the conditional statement
becomes D#A"5.E. At that time+ the loo becomes unstuck and the rogram continues with
whatever comes after the DwhileE loo closing arenthesis. 6n this e%amle+ the while loo has a
9oolean DORE function as its conditional statement. 6t sa$s that for as long as either the value of
Y)ountX is less than -( DORE Yti*eX is less than D.vent.TimeE+ kee inserting volume events and
incrementing both YcountX and YtimeX. At some oint+ Y)ountX will become greater than -( and
YtimeX will e%ceed D.vent.TimeE+ then the DORE condition will be D#A"5.E and the loo will
abort. This rogram fragment does not have much use+ but serves as an e%amle onl$. #or the
record+ $ou can stack DORE functions [ust as we did with the D;<DE functions. 6n fact+ $ou can
mi% D;<DE and DORE functions in the same stack.
2.$.17 Control flo/ funct"ons
.%ecution of CA" rograms starts at the to of the code and flows down to the bottom without an$
chance of being directed back u or skiing down or running subHroutines. This lack of subH
routine and [um functions is anno$ing at times+ but not insurmountable. #or the record+ there are
some limited wa$s of branching out of the Ytop downX format+ but ver$ limited. 1evertheless+ these
meager branching otions are enough to allow the needed fle%ibilit$ to generate some ver$
owerful rograms. There are two effective looing and two branching functions. The earlier
described D(orEa)hEventE function can be seen as a looing function+ but the real available
looing function is the DwhileE function. #urthermore+ CA" has the branches Di(E and Dswit)hE.
Cakewalk Alication "anguage Programming ;uide !.doc )-<101
Ton Valkenburgh
&owever+ we will start with the nesting control function DdoE and the e%ternal rogram sawning
function Din)ludeE+ which is the closest thing+ we have to a userHfriendl$ YgosubX function. #inel$
we will touch on the DD==E function+ which is an Din)ludeEHt$e function that oerates on the
DD==E rograms that e%ist to suort :indows and :indows alications.
(do 6e)pression17 886e)pression279?9)
The DdoE function is a nest builder. 6t combines multile functions and nests them so the$ will fit
into laces where CA" e%ects to see onl$ one function. This is wh$ we start CA" rograms with a
DdoE. A CA" rogram is siml$ one big functionL The same is true for the functions that go within
Di(E functions+ DwhileE and D(orEa)hEventE loos+ indeed an$where that has re'uirements for a
single function but more needs to get done than will fit in one function. &ere is a secific e%amleQ
(forEachEvent
(do
(somefunction)
(somefunction)
(somefunction)
(anotherfunction)
(soforth)
(andsoforth)
) ; end of do
5ee how all of the functions+ which come after the DdoE+ are groued into one nest because the
D(orEa)hEventE function can have but one function as an action. That one function is DdoE. An$ of
the functions nested within the DdoE can likewise be DdoE functions with their own nested
functions. &ere is a lace where $ou might think a DdoE is needed but isnXtQ
(forEachEvent
(while (6 $ote-:ey L0)
(if (7 $ote-1el 0)
(+ $ote-:ey 1)
(+ $ote-:ey 2)
) ; end of if
) ; end of while
(delete)
) ; end of if
This is another useless code fragment+ but roves a oint. :e do not need an$ DdoE functions
because the D(orEa)hEventE sees onl$ one function+ the Di(E. The Di(E sees onl$ one function+ the
DwhileE loo for its YthenX art. The DwhileE loo sees onl$ one functionQ the last Di(E. This Di(E
sees onl$ one function for its YthenX art and onl$ one function for its YelseX art. Afterwards+ the
first Di(E has onl$ one function+ the DdeleteE for its YelseX art. This is an e%treme e%amle+ but
illustrates that $ou must think about $our DdoE lacements as each nested function takes u room in
CA" and leaves less for calculations. 6f the nesting levels become too encumbered+ it has been m$
e%erience that $ou can elicit an Y.valuation stack overflowX error at some oint from CA". There
is one 'ualifier to the above statements. 6 have had times when building multile Di(E functions+ that
Ton Valkenburgh
on some rare occasions one of the nested Di(E statements will not e%ecute. 6 solved the roblem [ust
b$ adding an otherwise useless DdoE and nested the roblem Di(E statement under it. 6 reall$ did not
need it because there was technicall$ onl$ one function there. 6t seems that the DdoE somehow
sharened CA"Xs view of the comound statement. 2therwise 6 cannot e%lain wh$ the DdoE was
necessar$+ it [ust workedL #or a more detailed discussion of this roblem+ see the section chater
,.-.!Q X&idden tras in the CA" editorX.
=oops are chunks of code that kee being e%ecuted over and over until some condition tells them to
sto. :e have alread$ shown the DwhileE function+ but now is the time to get kneeHdee into them.
(while 6condition7 6action7)
The DwhileE loo is ver$ useful. 6t can used to e%ecute a nested function for as long as Y)onditionX
is DT3=.E. 7ou can run DwhileE loos within a D(orEa)hEventE loo+ $ou can run
D(orEa)hEventE loos within a DwhileE loo+ $ou can even run DwhileE loos within other DwhileE
loos. The Y)onditionX can be an$ valid function or grou of nested functions so long as it will
resolve to a DT3=.E or D#A"5.E result. There are so man$ uses for the DwhileE loo that 6 hardl$
know where to begin giving e%amlesL :e looked at one e%amle when we demonstrated the DORE
function. &ere is anotherQ
(while (6 looptime stoptime)
(do
(= newa (+ ref (< (; percent change) 1)))
(insert (+ notetime looptime) chan /E$!'EG K newa))
(+= looptime gap)
(= percent (< (; looptime 1) stoptime))
) ; end of do
) ; end of while
This is a simlified fragment from a rogram ;len wrote that erforms automatic cross fades for
the duration of a note from the first track to the second track. #or each note+ it starts again in track
one. &e has removed man$ of the contents of the loo and [ust left the fading in one track to
e%lain the DwhileE function.
This DwhileE loo is within a D(orEa)hEventE loo so that it runs for each note in the selected art
of the se'uence. #irst+ we have the condition for the loo. 5o long as Yloopti*eX is less than
Ystopti*eX+ the loo will run.
:e use DdoE to create a nest for the ( functions that follow so that DwhileE will see onl$ one
function in its nest [ust like D(orEa)hEventE as discussed above. The first nested function
calculates a value for YnewaX b$ multil$ing Yper)entX and Y)hangeX+ dividing the result b$ 100
then adding it to the offset Yre(E. This value will be the value of our volume controller event+ which
we insert in the ne%t line at time Ynoteti*eX+ lus Yloopti*eX. :e then add YgapX to Yloopti*eX to
oint to the lace we want to insert the ne%t volume event+ and then calculate a new value for
ercent+ which is derived b$ seeing how far along we+ are in Yloopti*eX relative to Ystopti*eX.
1ow we go back and test the condition again to see if we can run another DwhileE loo or if the
conditions have been met and we can e%it the loo. :hen Yloopti*eX fails to be smaller than
Ystopti*eX+ the loo ends. 6t is imortant to kee in mind that if the Y)onditionX is false the first
time CA" looks at it+ the DwhileE loo will never run at all. This is useful because there ma$ be
times when $ou will want to run the loo onl$ if Y)onditionX e%ists and b$ass the loo if
Y)onditionX doesnXt e%ist. 9$ the wa$+ $ou can use DwhileE loos to build onHline hel s$stems for
$our CA" rograms. Check out in chater (.-Q Y6mlementing 2nH"ine hel in a CA" rogramX.
Ton Valkenburgh
Y!ran)hingX functions allow us to ski over some of the code that we do not need on that occasion
and go directl$ to some code that we do need. The rules for using the two branching functions are
to be strictl$ followed or $our rogram can do some strange stuffL
(if 6condition7 6true5e)pression7 86false5e)pression79)
6n man$ e%amles 6 have mentioned the Di(E function. 6 will go now into more detail of this
function. 6t is the well known Yi( then elseX function which e%ists in all rogramming languagesQ
(if (condition) (thenfunction) (elsefunction))
This form is [ust fine if the Ythen(un)tionX and+ if used+ the otional Yelse(un)tionX are simle and
not made u of nested functions. 2therwise+ the more readable form would be
(if (condition)
(thenfunction)
(elsefunction)
)
1eedless to sa$+ the Ythen(un)tionX and Yelse(un)tionX functions can be comound nested functions
as well. "ook at this monster Di(E functionQ
(if (NN (== Event-:ind $E!E) (7 $ote-:ey lownote)) ; first if
(do ; first do
(if (J= $ote-:ey lastnote) ; second if (do
; second do
(if (6 $ote-,ur length) (= $ote-,ur length)); third if
; on one line
(++ count)
) ; closing of second do
(if (7= count limit) (+ lownote offset)) ; forth if on
; one line
) ; end of second if
(insert Event-!ime Event-/han $E!E lownote $ote-1el length)
) ; end of first do
(= count )
) ; end of first if
Again this code fragment does not reall$ do an$thing useful+ it is [ust a bunch of stuff in order to
demonstrate the form of a comound Di(E statement. The first Di(E statement has a condition made
of the 9oolean function D;<DE and two relational functions+ both of which must be DT3=.E for
the Di(E function to e%ecute. This Di(E has a YthenX art that is defined b$ all statements within the
first DdoE function. This DdoE function combines two functions+ the second Di(E and the DinsertE
function. As it haens+ the second Di(E uses a Dnot e7ualE as its conditional+ 6t nests a YthenX art
in the form of the second DdoE and an YelseX art+ the forth Di(E function. The second DdoE nests the
third Di(E function and an Din)re*entE function. The third and forth Di(E functions are on one line
in that the$ have onl$ a short conditional statement+ a single YthenX function and no YelseX art.
*o $ou notice how the functions at the same indention oint within an Di(E function make u the
YthenX and YelseX arts\ 1otice also that the functions at the same indention oint within a DdoE
function are all searate functions that share the same nest. Can $ou see how the closing arenthesis
of a comound function is alwa$s at the same indention oint as the corresonding oening
arenthesis that resides a few lines above\ These are imortant conventions that make good
rogramming habits and save hours of frustration if things need to be changed later on. 3emember+
Ton Valkenburgh
the YthenX art is mandator$+ and the YelseX art is otional. 7ou cannot technicall$ have an Di(E
function with an YelseX art and no YthenX art. This is of little conse'uence+ because an Di(E
statement condition can usuall$ be rewritten to make it unnecessar$.
6f for some reason $ou have built a condition so comle% or wish to kee it readable from some
articular oint of view+ and the action of the Di(E function as written need onl$ act uon events
other than those filtered b$ the condition >the condition selects events that must be b$assed and
ever$thing else needs to have something done to it?+ then $ou can make a doHnothing YthenX art
using the relativel$ undocumented D16"E ke$word and have the YelseX art do all of the work. The
form might look something like thisQ
(if (NN (== Event-:ind $E!E) (MM (7 $ote-1el 0) (7= $ote-,ur 1)))
$"G
(delete)
)
6n this e%amle+ we set u a rather comlicated condition that an event must be a note event and
have either a velocit$ above (0 or a duration as long or longer than 10 ticks. 6f these conditions are
true+ we do nothing. #or all other events and for notes that do not meet these conditions+ we delete
them. 1otice that D16"E is not in arentheses. 6 donXt know wh$ this is so+ it [ust works that wa$.
7ou never need to ut D16"E in arentheses+ 6 guess because as far as CA" is concerned+ it does not
e%istL Technicall$+ we could rewrite the above condition so that the YthenX art could hold the
DdeleteE function like thisQ
(if (MM (J= Event-:ind $E!E) (NN (6= $ote-1el 0) (6 $ote-,ur 1))) (delete))
This condition sa$s that if an event is either not a note or is a note that has both a velocit$ less than
or e'ual to (0 and a duration less than 10+ it will be deleted. 9oth statements do the same [ob+ but
the second one is siml$ better form. &owever+ if for continuit$ reasons it behooves $ou to create
the Di(E condition in the first form+ the D16"E ke$word is available to $ou.
(switch 6inde)7 6case17 6case1result7 86case27
6case2result7 ?9)
The Dswit)hE function is a ver$ useful. Therefore it is imortant that $ou understand how and when
to use it. This is the full form as $ou would use it in a rogramQ
(switch value
caseO1 (functionO1)
caseO2 (functionO2)
?
lastOcase (lastOfunction)
)
:hat Dswit)hE does is allow $ou to select a chunk of code to run based on the contents of YvalueX.
The Y)aseX arts are siml$ the various ossible values that YvalueX can have+ and the Y(un)tionX
art is what ever $ou wish to haen if YvalueX e'uals Y)aseX. CA" evaluates the YvalueX art+
which ma$ be a variable or a function or nested functions or an$thing $ou want to use. :hatever
the outcome is+ even if itXs a DT3=.E or D#A"5.E outcome+ CA" will scan the list of Y)aseX values
until it finds a match and then run the associated Y(un)tionX and onl$ that function. &aving done
this+ CA" e%its the Dswit)hE function >often referred to as a Y?wit)h TreeX? and continues with
whatever follows the Dswit)hE closing arenthesis.
2f course+ using a Y?wit)h TreeX for a DT3=.E<E#A"5.E YvalueX wouldnXt make much sense
because there are onl$ two ossible outcomes+ and an Di(E function is all $ou need to select a course
of action based on two outcomes. 6ndeed+ it makes no sense to use Dswit)hE at all unless $ou wish
Cakewalk Alication "anguage Programming ;uide !.doc (0<101
Ton Valkenburgh
to select from three or more ossible outcomes of YvalueX. As $ou might susect+ Y(un)tionX can be
a simle function or a comound function of an$ siPe+ [ust as long CA" sees onl$ one function in
each Y)aseX. All $ou need is a DdoE to nest together ever$thing $ou want to have run and $ou can
lace entire rograms in each Y)aseX. 6n fact+ thatXs one of the best uroses of a Y?wit)h TreeX. 5ee
the chater (.,Q Y5witch Tree 8enusX+ for an e%amle of a menu switch function.
(include 6filename7)
The Din)ludeE function causes the CA" rogram named in double 'uotes to be loaded and run at
that oint in the rogram containing the Din)ludeE. After this sawned rogram ends+ e%ecution
continues with the code that follows the Din)ludeE statement. 6t is as if the code in the Yin)ludedX
rogram had been asted into the calling rogram in lace of the Din)ludeE statement like a
DGo?ubE routine.. A good e%amle isQ
(do
(include #$EE,2-/+G%)
(declare your variables)
(and continue as usual)
)
.%amles of include rograms can be found in the 86*6H/it librar$.
7ou can use Din)ludeE to add in to all of certain t$es of rograms some feature the$ all should
have in common such as correcting note overlas or removing slurred notes or whatever. 5ee
chater (.0 X9uilding an include librar$X for insight into using included rograms.
(,GG 6%filename%7 6procedurename7 6argument17 -- 6argument
$7)
The best thing 6 can tell $ou about this function is use it as less as ossible+ unless $ou are an
e%erienced :indows rogrammer. 7ou need the documentation for using )!Hbit :indows
DD==E >*$namic "ink "ibraries? rograms.
9riefl$+ this function calls the DD==E+ file name listed in double 'uotes >without the e%tension
DD==E? and re'uests e%ecution of the service Ypro)edure na*eX within that DD==E file. 9oth of
these names must be in 'uotes. After the Yrocedure nameX+ $ou sul$ whatever arguments the
service re'uires in order to carr$ out its function. The >*""? function will onl$ accet two
1,
arguments. 6f $ou leave out an argument $ou are likel$ to corrut the s$stem stack and thus likel$
crash $our session of :indows+ or at the ver$ least make CA" and<or Cakewalk go south. 6f $ou
sul$ more than two+ those e%tra arguments will ass garbage instead of the data in those e%tra
arguments to the DD==E. &ere is a simle e%amleQ
The rogram uses a :indows s$stem *"" to sound a bee..
(do
; sound a beep
(string sysdll Pc*QwindowsQsystemQRser32-dllP)
(,GG sysdll PFessageCeepP)
) ; end of do
1,
This is not according to the CA/.:A"/ Pro Audio hel files. &ere is stated that more than ! arguments
can be sulied. 7ou *ust sul$ the re'uired number of arguments for the secific rocedure of the *""
rogram.
Ton Valkenburgh
6f $ou reall$ want to use this function+ see also chater ,.10Q Y&elful Tis for =sing the *""
#unctionX.
2.$.11 !us"cal t"me funct"ons
There are two wa$s of keeing time in a se'uence recogniPed b$ Cakewalk and CA". The first is in
terms of I*easureX+ YbeatX and Yti)kX called Y:!:TX time and the other is in the form of a )!Hbit
number referred to as YrawX time+ stored in a DdwordE variable.
To ut it siml$+ raw time is a count of the number of clock ticks from the start of a se'uence to the
end.
Y:!:TX time is that same number divided b$ the number ticks er beat and that amount further
divided b$ the number of beats in the current songXs meter. The result is formatted in standard
musical time notation with the remainder number of ticks included for accurac$.
At YrawX time Pero+ the musical time is 1Q1Q0 or Y*easureX F &+ YbeatX F &+ Yti)kX F %. 1ote that $ou
cannot have a measure or beat number 0. This is convention as established b$ hundreds of $ears of
musical tradition and Cakewalk has no intention of fl$ing in the face of it.
:hat Cakewalk adds is the Yti)kX comonent. 9ecause events must be recisel$ located within a
musical score+ the ticks rovide the necessar$ resolution without having to resort to stuff like !,-
th
notes. Can $ou imagine how obno%ious such notes would be on aer with all of those little flags
on the Y?ta((X\
9$ using ticks and setting the number of ticks er beat or 'uarter note+ a se'uence can record
human feel without having to note it in the score+ [ust like the real musicians la$.
The constant DT68.9A5.E makes the userXs setting of the number of ticks er beat available to
CA" for calculations and evaluations. The default value is 1!0 ticks er beat but this can be
changed from the front anel. The user can also set the meter from the front anel and thus select
(
<
(
or ^ or
0
<
8
or whatever meter the$ want. These settings are then used to calculate the Y:!:TX time
from YrawX time and vice versa. To facilitate this conversion from human to comuter time
keeing+ CA" has rovided us with a set of conversion functions. 6f $ou recall our discussion of the
DgetTi*eE function+ which allows the user to inut a time in Y:!:TX format and let CA" store it
as a double word in YrawX time format >at least in versions other than 0 and 8?+ we saw an e%amle
of a time keeing conversion function. &ere are the rest.
(meas 6rawtime7)
(beat 6rawtime7)
(tic2 6rawtime7)
These functions take the YrawX time+ or a function that resolves to a value of YrawX time and
calculates the roer number of measures+ beats or ticks as the$ would aear in the D1owE
window on the front anel. 6f $ou wanted to disla$ this information to the user in a dialog bo% at
some oint in the rogram+ $ou could do something like thisQ
(pause #!he time is # (meas Event-!ime) #*% (beat Event-!ime) #*% (tic2
Event-!ime) # at event # (inde)))
Assuming that the D.vent.TimeE is+ sa$+ !!)-8+ the DT68.9A5.E and meter settings are 1!0 and
(
<
(
and the current event being scanned b$ the D(orEa)hEventE loo is number !!(,+ the DpauseE
dialog bo% would disla$Q
!he time is 0K *3 *0S at event 220T
Cakewalk Alication "anguage Programming ;uide !.doc (!<101
Ton Valkenburgh
(ma2e!ime 6measure7 6beat7 6tic27)
This is the recirocal to the above conversion functions. "ike DgetTi*eE+ this function takes values
>or functions resulting in values? for Y*easureX+ YbeatX and Yti)kX and returns a raw time. "ike math
functions+ these functions are meant to be art of a larger function where the resulting calculations
can be outut or assigned to some variable. Check this outQ
(insert (ma2e!ime measure beat tic2) channel >BEEG value)
&ere we have inserted a itch wheel event at a time calculated from searate measure+ beat and tick
variables.
2.$.12 !"scellaneous funct"ons
(error)
This function can be used to terminate $our rogram if an error occurs. 6t generates a dialog bo%+
stating that the YProgram called >error?X+ and terminates CA".
(e)it)
6f $ou look at the code that makes u the Yneed2%.)alX rogram that installs with Cakewalk+ $ou
will see an undocumented function called DeAitE. 7ou donXt see it an$where else or see mention of
it an$where. 7ou would think the develoers of CA" were ashamed of it or something. 6t can be
ver$ useful as demonstrated in Yneed2%.)alX. :hen CA" hits this ke$word+ the rogram aborts and
all CA" activit$ ends. This can be ver$ useful if $ou want to autoHe%it after testing true for some
fatal condition such as there being no events in range that 'ualif$ for whatever $ou were going to
do to them.
The result of calling D>e%it?E is the resentation of a dialog bo%+ stating that the YCA" .rror 0!1
Program called >e%it?X and the termination of CA".
(delay 6time7)
This function doesnXt do an$thing e%cet susend e%ecution of the CA" rogram b$ the number of
milliseconds >1000ths of a second? in the value Yti*eX. This is a wa$ of making CA" sto what itXs
doing long enough for a human to read some message or react to a condition or erhas it can be
used as some kind of time keeing function causing some function to run ever$ so often.
Personall$+ 6Xve never had man$ occasions to use it+ but $ou might. As an e%amle+ letXs sa$ we
wanted to scan a art of a se'uence and give the user time to make notes of whatXs going on like
thisQ
(forEachEvent
(do
(message #/urrent $ote @itch "s # $ote-:ey)
(delay 2)
)
)
)
6n this e%amle we call a D(orEa)hEventE loo and use Di(E to make sure we onl$ look at D12T.E
events. :e disla$ on the status bar at the bottom of the screen the itch number of the note we
Cakewalk Alication "anguage Programming ;uide !.doc ()<101
Ton Valkenburgh
have found+ dela$ for ! seconds to give the user time to write this number down+ then go on to the
ne%t event in the loo.
$"G
This undocumented feature is not a function e%actl$+ and it never needs to be in arentheses. 6t is
[ust a laceholder. 6f $ou have a CA" function that re'uires an argument in some art of the
e%ression and $ou donXt want there to be one+ $ou can use D16"E as a substitute. That usage was
illustrated earlier in the overview of the Di(E function. This is about the onl$ lace 6 can think of to
use it+ that CA" versions ! and above donXt re'uire the D16"E as art of the code the wa$ earlier
versions of CA" did.
2.$.13 !enu funct"ons
The following CA" functions emulate the Yenu !arX commands that are available to the user
from the droHdown lists at the to of the Cakewalk screen.
There are several versions for most of the YEditX functions. #irst+ there are the ones from Cakewalk
version ) which 6 will call CA")0 functions and those from Cakewalk version ( and above+ which 6
will call CA"(0 functions
1-
. The difference is the argument list in the CA"(0 functions reflecting
the assu*ption that the D#romE and DThruE markers are set elsewhere and so no rovision is made
in the argument list for them+ nor for the YCse Event FilterX $es<no check bo% argument. Along
with this change there are a few CA"(0 functions that have e%anded argument lists that reflect the
additional otions available in versions , and - such as the audio and cli editing features. #inel$+
there are some YTra)kX menu functions that are new as of version 0. Version 8 doesnXt aear to
have changed CA" from the version 0 imlementation.
7ou will likel$ notice that+ for the most art+ if $ou know how to use the Cakewalk droHdown
menu commands+ $ou can use the CA" functions also. There are noticeable e%cetions. 2ne is the
use of the editing and interolating filters. These can be a bit of a ain in the butt. &owever+ in
earlier versions of CA/.:A"/ $ou could use the YRe)ording 4al a)rosX to generate the
rotot$e code for setting u these filters which then re'uire onl$ a bit of editing to make them
usable in a rogram. 6n 521A3 this is not available an$more. Therefore+ 6 give more information
about these functions. The (0Hfunction take advantage of the filter settings of 521A3+ therefore+ 6
recommend to use them instead of the )0Hfunctions.
Another is the bug that e%ists in Cakewalk version - which revents the DEdit1nterpolateE function
from acknowledging the D#romE and DThruE markers. 6nstead+ the function will oerate on the
entire track at once. As a side effect of this bug+ after the function runs+ the values stored in the
markers are dumed and relaced with the times corresonding to the start and end oints of the
se'uence resectivel$. There is a workHaround for this roblem. #or details see chater ,.( Y#orcing
Version - >.dit6nterolate? To =se 8arkersX.
2ne of the most imortant asects of using these 8.1= functions is the limitation that the$ will
not run within a D(orEa)hEventE loo. This makes sense if $ou think about it+ but 6 mention it here
so there is no misunderstanding as to the nature of these functions. This is the onl$ restriction. The$
work ver$ well and are 'uite useful in DwhileE loos and branching functions like Di(E.
1-
The new versions have a Y$%X suffi% in their name+ for e%amle+ DEdit4ut$%E is the new version of the
DEdit4utE function.
Cakewalk Alication "anguage Programming ;uide !.doc ((<101
Ton Valkenburgh
2.$.&+.& ED1T enu Fun)tions
(Edit/ontrolDill 86from7 6thru7 6ctrl7 6chan7 6beg7 6end79)
#ills the selected range Y(ro*. till YthruX with controllers Y)trlX in channel Y)hanX starting with
begin value YbegX and ending with value YendX.
Y)hanX is from 1..1-.
9egin value YbegX of the controllers+ and end value YendX must be between 0 and 1!0.
6f $ou omit all arameters+ the dialog bo% will o u.
(Edit/opy 86from7 6thru7 6events7 6filt7 6tempos7 6meters7
6mar2ers79)
This is the CA" ).0 comatible function corresonding to the Y4op"X command. 6t coies the
selected range Y(ro*X till YthruX to the cliboard.
7ou can select what will be coied b$ setting the arametersQ YeventsX+ Y(iltX >use event filter?+
Yte*posX+ Y*etersX+ and Y*arkersX on DT3=.E of D#A"5.E.
6f the Yuse event filterX arameter Y(iltX is DT3=.E+ then the Yevent (ilterX setting will be alied.
(Edit/opy0 86events7 6tempos7 6meters7 6mar2ers7 6audio7
6clips79)
This is the CA" (.0 function corresonding to the Y4op"X command. 6t coies the selection to
the cliboard.
7ou can select what will be coied b$ setting the arametersQ YeventsX+ Yte*posX+ Y*etersX+ and
Y*arkersX on DT3=.E of D#A"5.E.
YaudioX DT3=.E meansQ Y?plit ;udio EventsXT
Y)lipsX DT3=.E meansQ Y4op" Entire 4lip ;s =inked 4lipX.
The settings of the range >D#romE and DThruE?+ and the Yevent (ilterX setting will be alied.
6n versions of CA" between (.0 and -.0 some arameters are missing. The s$nta% isQ
(Edit/opy0 86events7 6tempos7 6meters7 6mar2ers79)
(Edit/ut 86from7 6thru7 6events7 6filt7 6tempos7 6meters7
6mar2ers7 6hole79)
This is the CA" ).0 comatible function corresonding to the Y4utX command. 6t cuts the
selected range Y(ro*X till YthruX+ and coies it to the cliboard.
7ou can select what will be coied b$ setting the arametersQ YeventsX+ Y(iltX >use event filter?+
Yte*posX+ Y*etersX+ and Y*arkersX on DT3=.E of D#A"5.E.
6f the Ydelete holesX arameter YholeX is DT3=.E+ then the created holes will be deleted.
6f the Yuse event filterX arameter Y(iltX is DT3=.E+ then the Yevent (ilterX setting will be alied.
Cakewalk Alication "anguage Programming ;uide !.doc (,<101
Ton Valkenburgh
(Edit/ut0 86events7 6tempos7 6meters7 6mar2ers7 6hole7 6split7
6align79)
This is the CA" (.0 function corresonding to the Y4utX command. 6t cuts the selection and
coies it to the cliboard.
7ou can select what will be coied b$ setting the arametersQ YeventsX+ Yte*posX+ Y*etersX+ and
YholeX DT3=.E meansQ YDelete HolesXT
YsplitX DT3=.E meansQ Y?plit ;udio EventsXT
YalignX DT3=.E meansQ Y;lign To easuresX.
The settings of the range >D#romE and DThruE? and the Yevent (ilterX setting will be alied.
9etween CA" ).0 and CA" -.0 there are less arametersQ
(Edit/ut0 86events7 6tempos7 6meters7 6mar2ers7 6delhole79)
(Edit,elete0 86events7 6tempos7 6meters7 6mar2ers7
6hole78 6split7 6align799)
This is an undocumented CA" (.0 function. 7ou can select what will be deleted b$ setting the
arametersQ YeventsX+ Yte*posX+ Y*etersX+ and Y*arkersX on DT3=.E of D#A"5.E. 6f ]hole] is
#A"5.+ omit ]slit] and ]align].
YholeX DT3=.E meansQ YDelete HolesXT
YsplitX DT3=.E meansQ Y?plit ;udio EventsXT
YalignX DT3=.E meansQ Y;lign To easuresX.
6f hole is D#A"5.E+ then omit YsplitX and YalignX.
6f $ou omit the arameters the dialog bo% will o u.
(EditDit"mprov 86referencetrac279
This is the CA" ).0 comatible function corresonding to the YFit 1*provisationX command. 6t
changes temos according to the reference track. The reference track is a single cli with a
single note on each beat boundar$.
Yre(eren)etra)kX the track number >0 K!,,?.
6f $ou omit the arameter+ the dialog bo% will o u.
(EditDit"mprov0)
This is the CA" (.0 version corresonding to the YFit 1*provisationX command.
The CA" (.0 version does not have a arameter. 6t assumes that the reference track is selected.
(EditDit!o!ime
1K
86from7 6thru7 6newthru7 6method7 6stretch79)
This is the CA" ).0 comatible function corresonding to the YFit to Ti*eX command. 6t fits
the range into the secified time. 6t inserts temo changes or modifies event times in $our 86*6
se'uence.
Y(ro*X the from valueT
YthruX the thru valueT
10
6n 521A3 this function has a bug. 6t returns the message Yinvalid valueX.
Cakewalk Alication "anguage Programming ;uide !.doc (-<101
Ton Valkenburgh
YnewthruX the new thru valueT
Y*ethodX event times or temo ma+ DT3=.E meansQ YEvent Ti*esXT
Ystret)hX DT3=.E meansQ Y?tret)h ;udioX
18
.
9elow CA" (., there is one arameter less. The s$nta% isQ
(EditDit!o!ime
1U
86from7 6thru7 6newthru7 6method79)
(EditDit!o!ime0
2
86newthru7 6method7 6stretch79)
This is the (.0 function corresonding to the YFit to Ti*eX command. 6t fits the selected range
into the secified time. 6t inserts temo changes or modifies event times in $our 86*6
se'uence.
YnewthruX the new thru valueT
Y*ethodX event times or temo ma+ DT3=.E meansQ event timesT
Ystret)hX DT3=.E meansQ Y?tret)h ;udioX.
#or CA" (.0 there is one arameter less. The s$nta% isQ
(EditDit!o!ime0
21
86newthru7 6method79)
(EditVrooveWuantiXe 86from7 6thru7 6filt7 6res7 6window7 6time7
6dur7 6vel7 6owm7 6groove79)
This is the CA" ).0 comatible function corresonding to the YGroove 5uanti6eX command. 6t
alies the ;roove OuantiPe command to the range Y(ro*X till YthruX. 5ettings can beQ
Y(iltX if DT3=.E the event filter will be usedT
YresX resolution in ticksT
YwindowX sensitivit$ in ercentageT
Yti*eX ercentage of time >0..100?T
YdurX ercentage of duration >0K100?T
YvelX ercentage of velocit$ >0K100?T
Yow*X YOut O( Bindow odeXQ
0 F do not changeT
1 F 'uantiPe to resolutionT
! F move to nearestT
) F scale timeT
18
The Y?tret)h ;udioX is limited to values between !, J and (00 J.
19
6n 521A3 this function has a bug. 6t returns the message Yinvalid valueX.
!0
This is an undocumented function. 6n 521A3 it has a bug. 6t returns the message Yinvalid valueX
!1
This is an undocumented function. 6n 521A3 it has a bug. 6t returns the message Yinvalid valueX
Ton Valkenburgh
YGrooveX YGroove ?our)eX name between 'uotes
!!
.
(EditVrooveWuantiXe0 86res7 6window7 6time7 6dur7 6vel7 6owm7
6file7 6pattern7 6$G+only79
This is the CA" (.0 function corresonding to the YGroove 5uanti6eX command. 5ettings can
beQ
YresX in note values >0 is whole note+ 1 is halve note+ etc.?
!)
T
YwindowX sensitivit$ in ercentageT
Yti*eX ercentage of time >0..100?T
YdurX ercentage of duration >0K100?T
YvelX ercentage of velocit$ >0K100?T
Yow*X YOut O( Bindow odeXQ
0 F do not changeT
1 F 'uantiPe to resolutionT
! F move to nearestT
) F scale timeT
Y(ileX YGroove FileX name between 'uotesT
YpatternX YGroove 'attern. name between 'uotesT
Y<=;onl"X DT3=.E meansQ Y<otes# ="ri)s# ;udio Onl"X.
6f both Y(ileX and YpatternX are emt$ W indicated b$Q DE W the cliboard will be used as source.
(Edit"nterpolate 86nodialog79)
This function resumes+ that the search >1? and relace >!? filters have alread$ been set as
desired.
YnodialogX an" value means no dialog bo%+ and the filter settings are usedT
o*itted means the dialog bo% are resented+ and the filter settings b$ CA"
functions are ignored
!(
.
5ee also chater ,.(Q #orcing Version - >.dit6nterolate? To =se 8arkers.
(EditGength 86from7 6thru7 6filt7 6percent7 6start7 6dur79)
This is the CA" ).0 comatible function corresonding to the Y=engthX command. 6t stretches or
shrinks the range >Y(ro*X till YthruX ? according to the arameter settings.
!!
D@cliboardAE means that the cliboard is used as source.
!)
To be checked.
!(
#or CA" below version 0.0 the dialog bo% resents the filter settings as set with the aroriate CA"
functions.
Ton Valkenburgh
Yper)entX ercentage to stretch or shrinkT
Y(iltX DT3=.E meansQ the event filter will be usedT
YstartX DT3=.E meansQ start time will be modifiedT
YdurX DT3=.E meansQ duration will be modified.
(EditGength0 86percent7 6start7 6dur7 6stretch79)
This is the CA" (.0 function corresonding to the "ength command. 6t stretches or shrinks the
according to the arameter settings.
Yper)entX ercentage to stretch or shrinkT
YstartX DT3=.E meansQ start time will be modifiedT
YdurX DT3=.E meansQ duration will be modifiedT
Ystret)hX DT3=.E meansQ Y?tret)h ;udioX
!,
.
9etween CA" (.0 and CA" version -.0 the Y?tret)h ;udioX arameter is not valid.
The settings of the range >D#romE and DThruE? and the YEvent FilterX settings will be alied.
Edit@aste 86to7 6rep7 6mode7 6events7 6tempos7 6meters7
6mar2ers79)
This is the CA" ).0 comatible function corresonding to the Y'asteX command. 6t astes the
cliboard in a track at the time to.
7ou can select what will be asted b$ setting the arametersQ YeventsX+ Yte*posX+ Y*etersX+ and
YrepX is the number of reetitionsT
Y*odeX
!-
0 meansQ blends new material with current materialT
1 meansQ relaces e%isting material with the asted materialT
! meansQ slides old material over and makes room for the new asted material.
6f $ou omit all arameters the dialog bo% will o u.
(Edit@aste0 86align7 6lin27 6to7 6totrac27 6onetrac27 6rep7 6gap7
6newclip7 6events7 6tempos7 6meters7 6mar2ers7 6mode7 6split79)
This is the CA" (.0 function corresonding to the Y'asteX command. 6t astes multile tracks+
cut or coied to the cliboard+ in the same order starting in destination totra)k at the time to.
YalignX DT3=.E meansQ Y;lign To easuresXT
YlinkX DT3=.E meansQ Y=ink RepetitionsXT
Yonetra)kX DT3=.E meansQ Y'aste To One Tra)kXT
YgapX this is the ga in Yrawti*eX between the asted reetitionsT
!,
The Y?tret)h ;udioX is limited to values between !, J and (00 J.
!-
This arameter is onl$ used for CA" ).0. All other versions of CA" ignore the value.
Ton Valkenburgh
Ynew)lipX DT3=.E meansQ Y'aste ;s <ew 4lipXT
Y*odeX
!0
YsplitX DT3=.E meansQ Y?plit ;udio EventsX.
9etween CA" ).0 and -.0 there are less arameters. The s$nta% isQ
(Edit@aste0 86to7 6totrac27 6onetrac27 6rep7 6gap7 6newclip7 6events7 6tempos7
6meters7 6mar2ers79)
2Edit'astToTra)k JHtoK HrepK H*odeK HeventsK Hte*posK H*etersK H*arkersK Htra)k3L3
This is the CA" ).0 comatible function corresonding to the Y'asteX command. 6t astes the
cliboard in a track at the time to.
Y*odeX
!8
Itra)k. the track number >0..1,?.
6f $ou omit all arameters the dialog bo% will o u.
(EditWuantiXe 86from7 6thru7 6filt7 6percent7 6times7 6dur79)
This is the CA" ).0 comatible function corresonding to the Y5uanti6eX command. 6t 'uantiPe
the range >Y(ro*X to YthruX?.
Yper)entX the ercentage that indicates the lacement of out8o(8ti*e events in erfect timingT
Yti*esX DT3=.E meansQ YEvent Ti*es. will be effectedT
YdurX DT3=.E meansQ durationXs will be trimmed on the resolution marks.
(EditWuantiXe0 86res7 6percent7 6times7 6dur7 6swing7 6window7
6offset7 6$G+only7 6stretch79)
This is the CA" (.0 function corresonding to the Y5uanti6eX command.
YresX resolution in ticksT
Yper)entX the ercentage that indicates the lacement of out8o(8ti*e events in erfect timingT
Yti*esX DT3=.E meansQ YEvent Ti*es. will be effectedT
YdurX DT3=.E meansQ durationXs will be trimmed on the resolution marksT
YswingX swing in ercentageT
!0
This arameter is onl$ used for CA" ).0. All other versions of CA" ignore it.
!8
This arameter is onl$ used for CA" ).0. All other versions of CA" ignore the value.
Cakewalk Alication "anguage Programming ;uide !.doc ,0<101
Ton Valkenburgh
YwindowX ercentage of the window+ where will be looked at out of lace eventsT
Yo((setX off set in ticks of the resolution marksT
Y<=;onl"X DT3=.E meansQ Y<otes# ="ri)s# ;udio Onl"XT
Ystret)hX DT3=.E meansQ Y?tret)h ;udioX.
9etween version (.0 and -.0 there is one arameter less. The s$nta% isQ
(EditWuantiXe0 86res7 6percent7 6times7 6dur7 6swing7 6window7 6offset7
6$G+only79)
(Edit'etrograde 86from7 6thru7 6filt79)
This function reverses the order of events in the selected art >determined b$ D #romE and
DThruE? of a track.
Y(iltXDT3=.E meansQ the event filter will be used.
(Edit'etrograde0)
This is the CA" (.0 comatible function corresonding to the YRetrogradeX command. 6t has no
arguments+ but uses the values D#romE+ DThruE+ and the filter settings.
(EditYlide 86from7 6thru7 6filt7 6amount7 6units79)
This function slides >shifts? the selected events >between YfromX+ and YthruX?.
Ya*ountX the number of unitsT
YunitsX the t$e of unitsQ ?till to be (illed in
(EditYlide0 86amount7 6tic2s7 6events7 6mar2ers79)
2U
This is the CA" (.0 function corresonding to the Y?lideX command. 6t slides >shifts? the b$ the
user selected range. 7ou can select what will be shifted b$ setting the arametersQ YeventsX+
Yte*posX+ and Y*arkersX on DT3=.E of D#A"5.E.
Yti)ksX is DT3=.E+ then Ya*ountX is treated as ticksT otherwise it is treated as measures.
(Edit!ranspose 86from7 6thru7 6filt7 6amount7 6diatonic79)
This function transoses the selected notes >between YfromX+ and YthruX?.
Ydiatoni)X DT3=.E meansQ diatonic transosition.
!9
The arameters YeventsX and Y*arkersX are added from CA" version -.0.
Ton Valkenburgh
(Edit!ranspose0 86amount7 6diatonic7 6audio79)
3
This is the new CA" (.0 function corresonding to the YTransposeX command.
Ydiatoni)X DT3=.E meansQ diatonic transositionT
YaudioX DT3=.E meansQ audio will be transosed.
(Edit1elocityYcale 86from7 6thru7 6filt7 6beg7 6end7 6unitspct79)
This function lets $ou create crescendos >volume swells? and decrescendos on those instruments
that resond to 86*6 velocit$. The velocit$ is changed in the range Y(ro*X till YthruX with
starting value YbegX and end value YendX.
Yunitsp)tX DT3=.D means that YbegX and YendX are ercentages.
(Edit1elocityYcale0 86beg7 6end7 6unitspct9)
This is the CA" (.0 version of YVelo)it"?)aleX command. 6t scales the velocit$ of the notes
within the selected range.
Yunitsp)tX if DT3=.D indicates that YbegX and YendX are ercentages+ otherwise if D#A"5.E that
the$ are velocit$ values.
('esetDilter 6type7 6everything7)
:henever $ou use one of the .*6T menu functions+ $ou need to let CA" know what events to
include in the action. The CA")0 functions >e%cet _.dit6nterolate_? give $ou the otion of
lacing a D#A"5.E value in the Y(iltX arameter thus ignoring the filter setting. The edit will
affect all events in the range. The CA"(0 functions do not have this argument and so should
have at least this YResetFilterX function run first to give it redictable access to events.
Yt"peX indicates the kind of filter being set.
0 meansQ YCse Event FilterXT
1 meansQ the 6nterolate .vent search filterT
! means the 6nterolate relace filter.

Yever"thingX DT3=.D corresonds to YEdit ?ele)t ;llX.
(YetDilter:ind 6type7 62ind7 6include7)
The ne%t filter setu function selects the actual event kind to be effected. 6f the above
YResetFilterX function]s Yever"thingX arameter D#A"5.E+ then this function would select the
events to be included. 6f Yever"thingX was DT3=.E+ then this function would be used to tell
CA" which events to e%clude. 6f several event kinds are to be included or e%cluded b$ this
method+ a Y?etFilter:indX function must be run for each event kind.
)0
The arameter YaudioX is added from CA" version -.0.
Cakewalk Alication "anguage Programming ;uide !.doc ,!<101
Ton Valkenburgh
YkindX is one of the following kindHofHevent constantsQ
DC&A1A#TET
DC21T32"ET
D/.7A#TET
D"736CE >new from ).0?T
D8C6E >new from ).0?T
D12T.ET
DPATC&ET
D5754E >new from ).0?T
DT.4TE >new from ).0?T
D:AV.E >new from ).0?T
D:&.."E.
Yin)ludeX DT3=.D means to include this kind of event.
(YetDilter'ange 6type7 6range7 6inrange7 6min7 6ma)7)
This function is a bit odd for a number of reasons 6 will tr$ to e%lain in a moment.
YrangeX is one of the followingQ
0 1ote /e$T
1 1ote Velocit$T
! 1ote *uration T
) /e$ After touch /e$T
( /e$ After touch Pressure >value?T
, Controller 1umberT
- Controller ValueT
0 Patch 1umberT
8 Channel After touch Pressure >value?T
9 :heel AmountT
10 ChannelT
11 9eatT
1! TickT
1) Patch bank number >new in -.0?T
1( 1(F 3P1 1umber >new in -.0?T
1, 3P1 Value >new in -.0?T
1- 13P1 1umber >new in -.0?T
Cakewalk Alication "anguage Programming ;uide !.doc ,)<101
Ton Valkenburgh
10 13P1 Value >new in -.0?.
YinrangeX is the oosite of the Y<ot )he)kboAXQ
D#A"5.E means Y<otX is checkedT
DT3=.E means it is not checked.
Y*inX+ Y*aAX are the minimum and ma%imum values for the range.
2.$.&+.2 F1=E enu Fun)tions
DileE)tract 86pathname79)
6f Ypathna*eX argument is omitted+ then the user is romted for the name.
6f Ypathna*eX alread$ e%ists+ then user is warned and given the abilit$ to enter a different name.
3eturnsQ D#A"5.E if file was not saved. This could be either because of an error writing the file
or because the user ressed Y4an)elX in the dialog.
(DileFerge 86pathname79)
3eturnsQ D#A"5.E if file could not be loaded. This could be either because of an error reading
the file or because the user ressed Y4an)elX in the dialog.
(Dile$ew 86template79)
6f Yte*plateX argument is omitted+ then the user is romted for the name of a temlate. The
Yte*plateX argument is a string and should contain onl$ the base name of the temlate+ without
an e%tension. #or e%amle Y<or*alX is correct but Y<or*al.T'=X is not.
3eturnsQ D#A"5.E if the temlate was not found and loaded. This could be either because of an
error reading the file or because the user ressed Y4an)elX in the dialog. The Y<or*alX temlate
alwa$s worksQ if no Y<or*al.T'=X file is found+ a blank work file is created with the normal
rogram defaults.
(DileEpen 86pathname79)
3eturnsQ D#A"5.E if file was not loaded. This could be either because of an error reading the
file or because the user ressed Y4an)elX in the dialog.
(DileYave)
3eturnsQ D#A"5.E if file was not saved due to an error writing the file.
(DileYave+s 86pathname79)
6f Ypathna*eX alread$ e%ists+ then user is warned and given the abilit$ to enter a different name.
3eturnsQ D#A"5.E if file was not saved. This could be either because of an error writing the
file or because the user ressed Y4an)elX in the dialog.
Cakewalk Alication "anguage Programming ;uide !.doc ,(<101
Ton Valkenburgh
2.$.&+.+ GOTO enu Fun)tions
(VotoYearch 86no@rompt79)
The Yno'ro*ptX argument is siml$ a s$ntactic laceholder. 6t can be an$thing. 6f there is an$
argument+ the user will not be romted with the 5earch dialog. 6nstead+ Cakewalk will erform
the search using the 5earch .vent #ilter asHis.
:hen Cakewalk records this command for $ou into the CA" editor+ it first uses one or more
calls to the DResetFilterE+ D?etFilter:indE+ and D?etFilterRangeE functions+ all using the filter
number 1. Then it addsQ
(VotoYearch 1)
The dumm$ argument Y&X means not to romt the user.
6f $ou are writing a CA" rogram where $ou want the user to be romted for comletion of
the 5earch dialog+ then call DGoto?ear)hE with no argumentsQ
(VotoYearch)
(VotoYearch$e)t)
3eeats the last search.
2.$.&+.$ ?ETT1<G? enu Fun)tions
(Yettings/hannel!able 86on7 6n17 6n27 6n37 6n07 6nT7 6nL7 6nK7
6nS7 6nU7 6n17 6n117 6n127 6n137 6n107 6n1T7 6n1L79)
n1 through n1- are track numbers+ 0..!,,.
(YettingsFetronome 86play7 6rec7 6acc7 6count7 6port7 6chan7 62ey7
6vel7 6dur7 6beep79)
(YettingsFidi"n 86n17 6n27 6n37 6n07 6nT7 6nL7 6nK7 6nS7 6nU7
6n17 6n117 6n127 6n137 6n107 6n1T7 6n1L79)
n1 through n1- are 86*6 channels. A value of Pero means the channel is not recorded or
echoed. A value of one means that it is recorded or echoed.
(YettingsFidiEut 86t)midirt7 6sendcont7 6sendspp7 6sppdelay7
6ctrlXero7 6ctrlchase79)
These arguments corresond to the similarl$Hnamed items in the 86*6 2ut dialog bo%.
(YettingsFidi!hru 86mode7 6port7 6chan7 62ey7 6vel7
6localonport79)
These arguments corresond to the similarl$Hnamed items in the 86*6 Thru dialog bo%.
(Yettings'ecordDilter 86note7 62eyaft7 6control7 6patch7 6chanaft7
6wheel79)
These arguments corresond to the similarl$Hnamed items in the 3ecord #ilter dialog bo%.
Cakewalk Alication "anguage Programming ;uide !.doc ,,<101
Ton Valkenburgh
2.$.&+.0 TR;4: enu Fun)tions
6n all the mentioned track menu functions the value of the arameter Ytra)kX must be between 0 and
!,,+ unless otherwise stated..
(!rac2+rchive 86archive7 86trac279?9)
This function handles the track archiveHstatus. An ar)hived track is silenced during la$back.
7ou must sto la$back to change a track]s Yar)hiveX status.
Yar)hiveX must be one of the followingQ
1 archiveT
0 unHarchiveT
H1 toggle.
(!rac2+ctive 86active7 86trac2799)
This function sets the track active or muted. &owever+ $ou can turn a muted track Ya)tiveX
during la$back.
Xa)tiveX must be one of the followingQ
1 la$ingT
0 muteT
H1 toggle.
(!rac2Can2 86ban27 86trac2799)
This functions sets the track bank.
YbankX must be H1..1-)8(.
(!rac2/hannel
31
86chan7 86trac2799)
This function sets the track channel.
Y)hanX must be 0..1,.
(!rac2:ey+ 86amount7 86trac2799)
This function sets how much numbers of semiHtones the track will be transosed.
Ya*ountX must be H1!0..1!0.
(!rac2$ame 6name7 6trac27)
This function sets the Yna*eX of a Ytra)kX. The Yna*eX is either a string literal or a string created
b$ a function.
(!rac2@an 86pan7 86trac2799)
This function sets the anning of the Ytra)kX.
YpanX must be H1..1!0.
(!rac2@atch 86patch7 86trac2799)
This function sets the Ypat)hX of the Ytra)kX.
Ypat)hX must be H1..1!0.
)1
the function was calledQ TrackChan in CA" version ).
Cakewalk Alication "anguage Programming ;uide !.doc ,-<101
Ton Valkenburgh
(!rac2@ort 86port7 86trac2799)
This function sets the outut YportX of the Ytra)kX.
Yport. must be 0..1,.
(!rac2Yelect 6state7 6trac27)
32
This function defines whether a track is selected or not selected. YstateX must be one of the
followingQ
1 selectT
0 unHselectT
H1 toggle.
Ytra)kX be H1 to mean Yall tra)ksX+ otherwise it must be from 0 to !,,.
<ote: This onl$ has an effect on old Cakewalk ).0 comatible CA" functions. #or e%amle+
this will change which tracks YEdit4utX oerates on+ but not YEdit4ut$%X. The latter strictl$
follows what the user has selected. 5ee also chater ,.1.1Q Y*ownwards comatibilit$X.
(!rac2!ime+ 86tic2s7 86trac2799)
5ets an offset >TimeG? to the start time of the events in the Ytra)k . 6s does not affect the stored
time for each event in the Ytra)kX.
The YrawX time as a result of the value Yti)ksX must be between 0 and the ma%imum value of
YrawX time.
(!rac21el+ 86amount7 86trac2799)
This function sets an offset >VelG? to the velocit$ of ever$ note in a Ytra)kX.
Ya*ountX must be between H1!0..1!0.
(!rac21olume 86volume7 86trac2799)
This function sets the Ytra)kX volume.
Yvolu*eX must be between H1..1!0.
)!
521A3Q To be able to be selected tracks must contain events.
Ton Valkenburgh
) Creating $our CA" rograms
9efore 521A3+ Cakewalk had a builtHin editor for CA" rograms. :ith 521A3 $ou need to use
an A5C66 editor to be able to create CA" rograms.
6t is not clear to me whether this is the first ste of YTwelve Tone 5$stemsX in killing CA" in later
versions of CA/.:A"/. 6 believe doing so will be a big mistake+ because CA" is one of the
features+ which make the difference with cometitive the roducts.
:hen $ou use a standard editor or a word rocessor to comose CA" rograms+ use the following
settings. 5et TA9 sacing to .1, inch+ set the age left and right margins to .!, each and if $ou have
the otion+ select an evenHsaced font instead of a roortional font. The CA" editor used an even
saced font so doing the same in $our alternate editor allows $ou to see closer to the final result this
wa$. 5ave $our file as Yplain teAtX or Y;?411 teAtX deending on how it is worded. 8icrosoft
:ord !000 for instance+ will normall$ add the Y.T>TX to the file name. 7ou can force a Y.4;=Y
e%tension to the file b$ entering the filename W including the e%tension CA" W within double
'uotes. ..g. use Y5ave AsX+ select file t$e T4T+ and enter Y'rogra* na*e.)alX. Program name is
the name of $our CA" rogram.
2ther editors which can be used without the aboveHmentioned solution for 85 :ord+ areQ 1otead
in :indows >8icrosoft? and :ordPro >"otus?.
Ton Valkenburgh
( Programming techni'ues
6 will here resent standard software rogramming conventions and techni'ues. The$ are not
uni'ue+ but essential in making rograms+ which can be maintained+ and understood also b$ other
rogrammers. Also $ou need to realiPe that after a coule of $ears man$ software rogrammers do
not understand their own rograms an$more.
All here rovided samle rograms can be found on httQ<<www.86*6H/it.nl. =nless otherwise
stated the e%amles can be found in a `6P file calledQ DCA" rogram samles.PiE.
The rogram e%amles will hel $ou to understand the rogramming rules of CA".
(.1 Conventions
$.1.1 Pro*ram hea8er
The &eader of a rogram must rovide the following in formationQ
Program nameT
Co$right statementT
Version+ with date of creation+ and if the version is a revision of an earlier versionQ an
e%lanation of the changesT
Purose of the rogramT
3e'uired user actions+ e.g. selection of the to be modified eventsT
6nut arameters.
"et us look at a simle rogram that disla$s the version of CA"Q
; Yhow version-cal
; (c) /opyright 20 !- 1al2enburgh
; 1ersion 1-13 +ugust 20* /hec2 whether version is 2- or higher
; 1ersion 1-3 Fay 20
;
; !his routine shows the /+G version-
; "nput parameters* $one
;
(do
(include #need2-cal%) ; 'e(uire version 2- or higher of /+G
;Vet the version and display it
(pause P!he version of /+G is* P (< 1E'Y"E$ 1) #-%( = 1E'Y"E$ 1))
) ; end of do
; end of program
1otice that this rogram of two statement starts with the DdoE functionT it contains more than one
statement. 1o declarations are neededT no variables are used.
3un this rogram to check the version of CA". 6n 521A3 ) $ou will get 100. #or a resentation in
the formatQ version .1.1+ $ou need to divide DV.35621E b$ 10 and use the remainder of
YEV.35621D divided b$ 10X after the dot.
Ton Valkenburgh
The first function is a check on the CA" version. *o alwa$s include such a test. ..g. $ou ma$ have
decided that $ou guarantee $our rograms onl$ for CA" levels 10.0 and higher. &owever+ $ou want
to make it available via 6nternet. 6t is then ke$ to include a test on CA" version 10.0. The
X<eed2%.)alX rogram W shied with Cakewalk W can easil$ be changed into a Y<eed&%%.)alX
rogram. A more generic solution is given in chater (.0 Q Y9uilding an include librar$X.
The Di(E function ma$ be difficult to read. &owever+ $ou can make it more readable in the
following wa$Q
if (== Event-:ind $E!E)
; then
(some function)
; else
(another function)
) ; end of if
To get a good icture of the nestled functions+ 6 alwa$s add to the closing arenthesis a comment
likeQ
) ; end of do
) ; end of while
5ometimes 6 even tell in the comment the condition of e.g. the while function.
6 also have the habit to end m$ rograms withQ
; end of program
The reason is that if $ou have a rogram that e%ceeds more than one age+ $ou are sure that the last
age on $our desk is reall$ the last age of $our rogram. 6n all below shown e%amles+ we will use
this convention. 6n YProgram skeleton.calX >chater 0Q Y.%amlesX? $ou can find the base for
creating $our CA" rograms.
$.1.2 Var"a#le names
Variable names must be meaningful and eas$ to remember.
To ensure that the name 6 use+ cannot be or become H in later versions H an internal name of CA"+ 6
alwa$s use a lowercase character indicating the t$e of variable.
n/hannel
This variable is the channel numberT therefore+ it begins with YnX.
9elow 6 give m$ convention for the t$e indicationQ
T"pe First
)hara)ter
9oolean b
1umber n
3aw time r
Te%t t
Cakewalk Alication "anguage Programming ;uide !.doc -0<101
Ton Valkenburgh
T"pe First
)hara)ter
(.! .rror handling
6t often has been said that !0 J of a rogram is functional code+ and 80 J is code for handling
e%cetional situations. This indicates how imortant error handling is. .seciall$ if $ou want to
make $our rogram available to other users+ it is imortant to test on e%cetional situations+ and
rovide clear error messages.
1ot checking whether the user has rovided the e%ected inut ma$ result in an hang u in
CA/.:A"/.
6f the user must select D.ventsE to be able to run $our rogram+ then $ou should test whether
D.ventsE are selected. 2ut of range values of velocit$+ itch+ etc. can give ver$ une%ected results.
6t is ke$ to include these tests in $our rogram to avoid e%cetional situations.
$.2.1 Check"n* the mark"n* of Events
5ometimes rograms hang if no D.ventsE have been selected >marked?. Therefore+ $ou must test
whether D.ventsE are selected. A simle rogram can be used for the test. 6 have written a generic
include rogram for the test. This rogram will count the events+ and return in a variable the
number of events. The calling rogram rovides the kind of event in the variable YnEventY. "et us
look at this include rogram
))
.
;
; Z+Events mar2ed-calZ
;
; (/) /opyright 20 !- 1al2enburgh
; 1ersion 1-3 Ectober 20
;
; @urpose
; "nclude program that counts the number of mar2ed Events-
; Events with the same Event-!ime in the same trac2 are counted as E$E-
;
; "nput parameters* nEvent Event-:ind to be chec2ed
; Eutput* nEvent/ount $umber of events
;
(do
; 1ariable declarations of locals
(dword [r@revious ) ; @revious Event-!ime
; Yet Event count Xero3 \ust to be sure
(= nEvent/ount )
; search for Events
))
#or an e%lanation of the naming convention of the variables see chater (.0Q Y9uilding an include
librar$X.
Ton Valkenburgh
(forEachEvent
(if (== Event-:ind nEvent) ; nEvent has been provided by
; the calling program
(do
(if (NN (== Event-!ime ) (== nEvent/ount ))
; then
(= nEvent/ount 1) ; first event on time Xero
; else
(if (J= Event-!ime [r@revious)
(do
(++ nEvent/ount) ; count
(= [r@revious Event-!ime)
) ; end of do
) ; end of if
) ; end of if
) ; end of do
) ; end of if
(undef [r@revious) ; remove definition
) ; end of do
; end of program
D.ventsE at the same D.vent.TimeE in the same track are counted as one. This allows $ou to see a
chord as one event. The calling rogram can test whether the count is Pero. This will look likeQ
(int nEvent $E!E) ; Event for chec2ing whether they are mar2ed
; Vet the number of mar2ed notes
(include P+Events mar2ed-calP)
; /hec2 whether notes has been mar2ed
(if (== nEvent/ount )
(do
(pause P$o note mar2ed3 process terminatedP)
(e)it)
) ; end of do
) ; end of if
The rogram I,Events *arked.)alX is art of the include librar$. 5ee also chater (.0Q
Y9uilding an include librar$X.
$.2.2 Prevent"n* over9ran*e Pro#lems
5omething ver$ odd haens when $ou send some event arameters negative or over their allowed
limits. The effect is referred to in comuter circles as aliasing. :hat this means is the value
assigned to the variable will be something that aears unrelated to the actual value that should
have been stored there. #or e%amle+ suose in the act of scaling a note velocit$+ the value goes
Cakewalk Alication "anguage Programming ;uide !.doc -!<101
Ton Valkenburgh
negative. This negative value is then entered into the se'uence as the noteXs velocit$ even though
itXs imossible for a note to have a negative velocit$. 1ow $ou look at that note in the YEventX view
and notice that its value is indeed a ositive number+ but seemingl$ unrelated to the results of the
e'uation that generated it. The value has been YaliasedX. 9ecause the Ypo)ketX for a velocit$ value
cannot hold a negative number+ the Ynegative signX of the value has been stried awa$ and the
remaining bits that made u the negative number were left behind as a bogus ositive number. .ven
though most of the time attemting to lace a number that is too large for a variable will result in an
error message+ driving a result negative will often go unnoticed b$ CA". To revent aliasing and
over range error messages+ it is imortant to add over range checking to an$ user inut and
calculation that can result in a variable going over or under allowable limits.
$.2.2.& 1nput range )he)king
7ou must alwa$s realiPe that e%ternal and internal values can be different. ..g. Channel numbers
range 1 through 1- e%ternall$+ but are internall$ resented as 0 through 1,.
That means $ou ask the user to inut a channel between 1 and 1,+ ensures checking the range+ and
converts the value for internal use b$ decreasing it with 1.
6n $our inut statement $ou set the inut range that is allowed for the field $ou ask the user to
rovideQ
(get"nt n/hannel #/hannel = # 1 1L)
(55 n/hannel) ; internally /+G uses ? 1T
This will ensure that the channel will be within a valid range+ and that $ou will use the correct
internal CA" value.
$.2.2.2 'reventing internal over8range errors
6f $ou calculate values e.g. ke$ velocit$+ $ou must ensure that the result within a valid range+ e.g.
between 0 and 1!0 for velocities. 9elow 6 show $ou what 6 mean. "etXs sa$ weXre scaling
velocities. At the end of the scaling formula siml$ addQ
(some calculation that scales velocities)
(if (6 velocity ) (= velocity )) ;/orrect negative velocities-
(if (7 velocity 12K) (= velocity 12K)) ;/orrect velocities that overrange-
(and go on with your program)
These two e%tra lines of code test for+ in the first+ the variable Xvelo)it"X being less than Pero+ in
other words+ a negative number. 6f this is found to be so+ Yvelo)it"X is set e'ual to Pero. 6n the
second+ if Yvelo)it"X is greater than 1!0+ then it is set e'ual to 1!0. This wa$+ no matter what result
$our scaling formula generates+ the value ultimatel$ assigned to Yvelo)it"X will be within the
allowable range for that arameter. 7ou can of course also add a warning message+ to ensure the
user is noticed that an over range situation occurred.
(.) 8athematics
Calculations can give une%ected results within CA"+ because CA" does not have floating oint
calculations. All calculations within CA" are done with whole numbers+ and that means $ou must
be ver$ carefull$ with creating formulas within CA". "et me show with an e%amle how $our
rogram can give different results+ while the formulas in both cases are correct. 6n the e%amle
below both calculations give the same result.
T ; 12 < 1 = L
Cakewalk Alication "anguage Programming ;uide !.doc -)<101
Ton Valkenburgh
T < 1 ; 12 = L
"et us now look at the two CA" rogramsQ
(< (; T 12) 1)
This e%amle gives as resultQ M.
(; (< T 1) 12)
This e%amle gives as resultQ %.
The reason is that , divided b$ 10 gives in CA" 0 with , as remainder. 6f we do not want to e%and
our calculation with using the remainder+ we will get the wrong answer.
6n most cases the remainder is not imortant for CA" rograms. 7ou can avoid this roblem b$
doing the multilication before the division. 8ake sure that the variables can hold the largest value
during the calculations. 6f needed+ use a DdwordE or DlongE variable.
(.( 5ending 5754 messages
&ere 6 will describe how to send 5754 messages to the s$nthesiPer. 6 will use an e%amle rogram
that switches the ;eneral 86*6 mode of $our s$nthesiPer. The 5754 message for switching the
;8 mode of $our s$nthesiPer isQ
D
30
; indentifies Yystem E)clusive message start
KE ; ", number* Rniversial $on5realtime message
KD ; ,evice ",* Croadcast
3T
U ; Yub ", number 1* Veneral F"," Croadcast
3L
)) ; YRC ", number 2* indicates VF mode( VF1=13 VF2=33 VF off=2)
DK ; EE] * end of e)clusive
:ith the CA" function Dsend1D1E we can send the 5754 message. CA" can onl$ handle
decimal numbers. Therefore+ we must convert the he%adecimal numbers into decimal.
The user will be asked for selection ofQ ;81+ ;8 ! of off. :e assume that the s$nthesiPer is
connected on ort 1+ which is true in most cases. #urther this small rogram is clear enough.
; ZVF Fode-calZ
;
; (/) /opyright 2T !- 1al2enburgh
; 1ersion 1-3 Debruary 2T
;
; @urpose
; Ywitching between VF modes of a F"," device-
;
; "nput parameters* ZVF Fode (VF 1=13 VF 2=23 Eff=)Z
; Eutput* Veneral F"," message to synthesiXer
;
(do
; 1ariable declarations
)(
All numbers are in he%adecimal format.
),
This must be according to the secific instrument. 5ee the owners manual of the instrument.
)-
This must be according to the secific instrument. 5ee the owners manual of the instrument.
Cakewalk Alication "anguage Programming ;uide !.doc -(<101
Ton Valkenburgh
(int n/+G1ersion 31) ; re(uired /+G version
; !est on /+G version
(include P+need version-calP) ; terminate if version is too low
;
(int n@ort ) ; assumes your synthesiXer is on port 1
(int n/hannel 1T) ; any number is o23 it will be ignored
(int nFode 1) ; Fode
; YIY] message contents
(int n",number 12L) ; Rniversial $on5realtime Fessage (=KEB)
(int n,evice", 12K) ; Croadcast (=KDB)
(int nYub",1 U) ; Veneral F"," message (=UB)
(int nYub",2 1) ; Veneral F"," 1 En (=1B)
;
; @rogram
(get"nt nFode PVF Fode (VF 1=13 VF 2=23 Eff=) P 2)
(switch nFode
(= nYub",2 2); VF 2
2 (= nYub",2 3); VF off
) ; end of switch
; send Veneral F"," message
(sendF"," n@ort n/hannel YIY] n",number n,evice", nYub",1 nYub",2)
) ; end of do
; end of program
(., 5witch Tree 8enus
:hen 6 introduced the Dswit)hE function in chater !.(.10Q Control flow functions+ 6 touched on the
idea of using a Dswit)hE tree to control a menu. The e%ecution of this concet is ver$ simle. "ook
at this e%amleQ
(int mode )
(get"nt mode #Yelect @rogram Iou >ish !o 'un # 3)
(switch mode

(do
(a bunch of stuff that ma2es up a /+G program)
) ; end of do
1
(do
(another program the user could run)
) ; end of do
2
(do
(you get the idea)
Cakewalk Alication "anguage Programming ;uide !.doc -,<101
Ton Valkenburgh
) ; end of do
mode
(do
(the last of the program selections)
) ; end of do
) ; end of switch
6n this e%amle+ we have used Dswit)hE as a menu driver. The user selects which of four CA"
rograms the$ wish to run and the tree icks out the right one based on the value of Y*odeX.
&owever+ what about this e%amleQ
(forEachEvent
(switch $ote-:ey
3T
(+ $ote-:ey 1)
3S
(+ $ote-:ey 2)
0U
(+ $ote-:ey S)
$ote-:ey
(5 $ote-1el 1)
) ; end of switch $ote-:ey
5uose we have a general 86*6 ercussion track selected. &ere we start a D(orEa)hEventE loo
and filter out ever$thing e%cet note events using the Di(E. 1ow we set u a Dswit)hE tree that
erforms a secial change on certain notes+ in this case it changes Acoustic 9ass drum notes >note
number ),? to 9ass *rum a1 notes b$ adding a 1 to the note number. 6f the loo finds an Acoustic
5nare note >a)8?+ it adds ! to it and it becomes an .lectric 5nare note. An$ Crash C$mbal a1 notes
>a(9? it finds are changed to Crash C$mbal a! notes+ and ever$thing else+ including native 9ass
*rum a1+ .lectric 5nare and Crash C$mbal a! notes are lowered in velocit$ b$ 10 units to make the
changed notes stand out a bit. As $ou can see+ in this case we needed an Yi( all else (ailsX tra so we
donXt have to list a case for ever$ single note in the drum kit.
(.- 6mlementing 2nH"ine hel in a CA" rogram
As odd as it ma$ seem+ there is a wa$ to rovide the user of $our CA" rograms a set of simle
instructions that the$ can look at or not as the$ feel necessar$. This can be done through the use if a
DwhileE loo enclosing a grou of DpauseE dialogs. 2ne ver$ useful reason to emlo$ this
techni'ue is due to the imlementation of resets in a rogram. 6n this wa$+ the user can choose
from one of several resets that autoHconfigure the rogram for secific oerations+ choose to enter
all arameters b$ hand or choose to view a series of YHelpX bo%es that describe the resets and offer
other ertinent information. &ere is an e%amle of some code that will generate the hel bo%es.
(int preset 51) ;,eclare the preset variable-
(while (== preset 51) ;Yo long as preset e(uals 51---
(do ;do the following3 starting with a re(uest
; for user input-
(get"nt preset #Yelect @reset Fode or Bit E$!E' to review a list of presets # 51 K)
Cakewalk Alication "anguage Programming ;uide !.doc --<101
Ton Valkenburgh
(if (== preset 51) ;"f the default value is still in #preset%---
(do ;display the following #pause% bo)es-
(pause #$ote Wualification @reset Gist * =Yet +ll 1ariables Cy Band 1=Ypot +pply%)
(pause #FE$E@BE$"/ !rac2 preset 2=Wuarter $otes or Cigger 3=+ll Gong $otes%)
(pause #0=Enly Dirst $ote in a @hrase T=Enly Gast $ote in a @hrase%)
(pause #@EGI@BE$"/ !rac2 presets L=+ll $otes K=Enly Gast $ote of 'uns%)
) ; end of do3 nesting the #pause% statements-
) ; end of if
) ; end of do
) ; end of while
6n the first line+ we declare a variable that we will use as our reset selection variable. 6t is
initialiPed to H1 so that in the inut dialog that follows+ the user can siml$ hit .1T.3 to select this
default value and thus read the YHelpX bo%es.
After declaring YpresetX+ we start a DwhileE loo that continues to loo for as long as YpresetX is H1.
1e%t is that inut dialog where the user can enter a reset number from 0 to 0 or kee the default
value of H1 and read the YHelpX. The Di(E function triggers if the value of YpresetX is still H1. 6f is
isnXt+ then the Di(E is b$assed and we return to the to of the DwhileE loo where the condition for
the loo fails and e%ecution immediatel$ roceeds with the line of code after the DwhileE looXs
closing arenthesis. 6f YpresetX is still H1+ then the Di(E condition asses and we e%ecute its nested
functions which consist of a series of DpauseE statements containing some useful information in
their te%t arguments. The user reads this information+ and from it decides which reset the$ wish to
select. After the last DpauseE dialog bo%+ the Di(E e%its and we come back to the to of the DwhileE
loo.
The variable YpresetX still e'uals H1+ so we start the loo again. This time+ the user will decide on a
reset based uon what the$ read in the DpauseE bo%es. The value is entered during the Dget1ntE
statement. The Di(E now fails because YpresetX has been set to a value other than H1. The DwhileE
loo likewise fails for the same reason and the rogram continues+ likel$ with a Dswit)hE tree to
rocess the userXs selection in the YpresetX variable.
(.0 9uilding an include librar$
6f $ou are going to use CA" a lot+ it might be a good idea to look into constructing a librar$ of CA"
modules that erform secific Y*i)roX tasks and use them as building blocks to make larger CA"
rograms. 7ou can also build slightl$ different versions of a basic rogram that each erforms the
same task but with different reset arameters or focus.
There is + however+ an imortant consideration if $ou use this function within a loo like
D(orEa)hEventE or DwhileE. This is because each time the loo is run+ CA" has to go searching for
the included rogram+ load it and run it. .ven with the included rogram residing in the disk cache
memor$+ this can be a ver$ time consuming rocess and will slow down e%ecution of $our arent
CA" rogram considerabl$. "oos in the included rograms can contain such loos without
degradation of erformance.
6f $ou are going to make this idea work+ $ou must be organiPed about it. *ecide on some
conventions and stick to them.
2ne convention might be to make sure all local variables $our Din)ludeE rograms declare are
named fundamentall$ different from the wa$ $ou name variables in arent rograms. This will
revent an$ YVariable redefinedX erors from oing u at run time.
6f the arent rogram needs ro ass arameters to the Din)ludeE rogram+ the$ must share
variables. To ensure general use of include rograms re'uire a ver$ strict naming convention to
Ton Valkenburgh
avoid roblems.
6n addition+ $ou should use the Dunde(E function to Iunde(ineX the local variables used within the
include rogram+ and not used to ass through to the arent rogram. This will revent une%ected
interaction between Din)ludeE rograms.
6t will hel if the Din)ludeE rograms can eas$ be recogniPed in $our folders+ therefore+ also here a
good naming convention hels.
All these asects of assing data back and forth between arent rograms and their included child
rograms should follow a set of rotocols. /ee names of variables consistent b$ function so that as
$ou write a new arent+ it will easil$ dovetail into $our current scheme. =se the same structure for
assembling data to be assed to an$ included rogram and collecting returned data. *ocument in
the header the inut and outut arameters.
There is one other consideration worth mentioning. An Din)ludeE function will use u a nesting
level on its own+ not to mention an$ nesting levels created b$ the included rogram. CA" can onl$
handle a limited
)0
nesting levels before issuing an Y.valuation stack overflowX error. /ee included
rograms ver$ efficient and donXt run Din)ludeE functions if the$ themselves will be nested ver$
dee within a function of a arent rogram.
&erewith m$ set of librar$ conventionsQ
1te* Rule
1ame of Din)ludeE rogram 1ame starts with G
"ocal variable names in Din)ludeE rogram 1ame start with b
9elow 6 show how the rogram I,need version.)alX will look like with these conventions.
; +need version-cal
; (/) 20 !- 1al2enburgh
; /ourtesy* this program is based on the by !welve !one Yystems
; provided Zneed2-calZ
; 1ersion 1-3 +ugust 20
; !his library (include) program chec2s whether the version of /+G is
; e(ual or higher than the level indicated in the input parameter
;
; input parameters* n/+G1ersion level on which must be tested
; output parameters* none
;
(if (6 1E'Y"E$ n/+G1ersion)
(do
(pause P!his program re(uires /+G version P (< n/+G1ersion 1) P-P (= n/+G1ersion 1))
(e)it)
) ; end of do
) ; end of if
; end of program
3emarksQ
9ecause 6 use rogram code from somebod$ else+ 6 mention that in m$ headerT
)0
The number of allowed nested Din)ludeE rograms is not secified b$ YTwelve Tone 5$stemsE.
Ton Valkenburgh
The calling rogram rovides the inut arameter W re'uired level of CA" H via a variable
Yn4;=VersionX. The rogram tests and returns if ok+ or e%its with an aroriate message to
the user if the level is lower than the inut arameter. Also note that the rogram does not start
with the Ddo- function. The Di(- statement includes all other statementsT
This include rogram has no local variables.
Ton Valkenburgh
, Tis+ and workHarounds
1ot ever$thing about CA" is straightforward. There are allot of asects of CA" that are
undocumented and in some cases+ wrong documented. There are subtle features to some functions
that donXt resent themselves on the surface. 7ou can do things with CA" that wouldnXt occur to
$ou [ust offHhand. Then again there are the 'uirks in CA" that make $ou want to ull $our hair outL
6n an attemt to forestall unnecessar$ baldness among CA" users+ 6 wish to rovide $ou with some
of the fruits of m$ own hair ulling sessions with CA". /ee in mind that there must be at least as
much that 6 have $et to discover. Perhas with the collective efforts of all of us CA" rogrammers+
we can kee each other sane.
&ere is m$ oening contribution to this cause. 2ne thing 6 wish to conve$ as a sort of disclaimer is
that $ou ma$ never see some of these reorts of strange behavior. 5ome of them 6 m$self have onl$
seen once or twice and erhas the$ are a result of some odd conflicts in the registr$ or whatever. 6
still feel comelled to mention them Z=5T 61 CA5. someone else out there comes u against the
same roblem. This wa$+ the$ will have at least been briefed on the ossibilit$ and can take action
accordingl$. #act is+ 6 hoe nobod$ ever runs across the oddities that are listed here+ but $ou will at
least some of them+ believe meL
Alwa$s remember CA" rograms can be u to )!0-8 characters long W including comments. 6 do
not know whether $ou can solve this b$ utting the code in searate rograms and include these
rograms in $our main rogram. =ntil now+ 6 never reached this limit.
,.1 CA" Comatibilit$
Comatibilit$ can be uwards and downwards.
*ownwards comatibilit$ is easier+ because $ou can test with all revious versions W if available H
of CA". &owever+ making $our rogram downwards comatible ma$ limit $ou to the lowest
functionalit$. Also $ou ma$ discover that certain functions work out differentl$ in the various
levels of CA".
=wards comatibilit$ is more difficult to guarantee. &owever+ b$ following a strict disciline $ou
can increase the comatibilit$. :hether $ou succeed or not succeed is than more deendent on the
'ualit$ of the CA" develoers. &istor$ has shown that eseciall$ the menu functions ma$ be
incomatible due to additional functionalit$.
0.1.1 Do/n/ar8s compat"#"l"ty
9$ and large+ an$thing $ou write with CA" on a s$stem running Cakewalk version ) should load
and run fine on an$ version after it. The same alies to steing u from version (+ ,+ - etc. to an$
higher version. &owever >and this should come as no surrise?+ the reverse is not true. 1ot onl$ are
some functions different or even unavailable in earlier versions+ but also the s$stem itself can
imose limitations.
5omething to kee in mindT if $ou are writing code that will be using event constants that are
onl$ recogniPed b$ later versions of CA"+ and $ou want the code to be backwards comatible
with earlier versions+ $ou cannot reference these constants b$ name but b$ the number the$
e'ual. 6f $ou use the name+ the versions of CA" that donXt suort them will give $ou an error
message and refuse to run. 2n the other hand+ if $ou use the number+ then CA" will siml$ use
this number and dismiss the result without issuing an error. #or e%amle+ suose $ou wish to
hunt for 3P1 events in a rogram that otherwise is [ust as useful in Cakewalk versions other
than - or above. 6f $ou use a function likeQ
(if (== Event-:ind '@$)
Ton Valkenburgh
CA" versions below - will go bell$Hu. 2n the other hand+ if $ou write it like thisQ
(if (== Event-:ind U)
CA" versions - and above will still resond DT3=.E if the$ find an D3P1E event. 2ther
versions of CA" ma$ siml$ return results during the comarison that reflect the$ were either
unsuccessful in finding an event that doesnXt e%ist in an$ se'uence that could be loaded into that
version of Cakewalk+ or the$ found something the$ donXt know b$ name but never the less
sotted b$ value.
&owever+ realiPe that the develoers of CA" can change the internal values in later versions. 6t
is a good rogramming ractice to use )onstants onl" b" na*e and not b$ value. This will
ensure uwards comatibilit$ of $our rograms.
2ne of the most obvious came to ;len when he was working with one of his CA" rograms
called Y4ross(ade.)alX. &e wrote it in version ) and had to lace some limitations on it due to
s$stem constraints.
After reworking it in version 0+ it no longer ran in version )+ not because he had added features
not suorted b$ version )+ but because it overran the abilities of the version ) runHtime
interreter.
&e added two more nesting levels to the rogram+ and then he added the abilit$ to select YnoneX
for the amount of attack and<or deca$ time in the cross fade of each note.
2n version 0+ this was a great new feature but in version ) it generated an Y.valuation stack
overflowX error due to the addition of the new and deeer nesting of some functions. &is
indentionXs had gone from 8 to 10 tabs dee in the code te%t and version ) siml$ canXt kee
track of that man$ calls.
6n that he realiPed he would have to have searate versions of Y4ross(ade.)alX for version ). &e
also included in the new version the abilit$ to deselect the target track and select a new target
track for erforming the volume event integration on the cloned area+ a feature imossible in
version ) because there is no wa$ to deselect the blue8highlighted track.
Another aroach ;len could have taken was to build in his rogram a test on the CA" version+
and based on the outcome of the test e.g. include a rogram variant for that secific CA"
version.
&erewith another e%amleQ in later Cakewalk versions $ou can deselect all tracks and select
new ones through CA" even though if $ou were to read the CA" hel in these later versions it
will tr$ to convince $ou that the DTra)k?ele)tE function doesnXt work an$ more H wrongLLL 6t
works [ust fine. There are some limitations to it now+ like the fact that some functions+ the
DinsertE function for one+ will not honor the >DTra)k?ele)tE? function unless it is within a
>D(orEa)hEventE? loo. 6f $ou tr$ to use >DTra)k?ele)tE? and it doesnXt work+ $ou ma$ have
[ust run into this limitation.
Another consideration is a minor kink in the CA" e%ecution s$stem in versions 0 and 8. 6f $ou
load a CA" rogram or otherwise attemt to use CA" without a Y.BR:X file loaded into the
worksace+ there is no wa$ of running the CA" rogram. .ven clicking on the DRunE icon in
CA" View will have no effect at all. The onl$ time this is a roblem if $ou have cleared the
worksace and then want to load some files or format some default worksace to $our liking in
one ste b$ running a CA" rogram that re configures ever$thing [ust so. 7ou can forget itL
7ou must load so*ething into the worksace first+ even if itXs [ust a default blank worksace.
1ow $ou can run $our CA" setHu rogram. This isnXt a roblem when $ou first load Cakewalk
as $ou are given a default blank worksace as soon as the rogram finishes loading. 6t is onl$ a
roblem if $ou have closed ever$thing and the worksace is comletel$ vacant.
As a 'uick aside+ some functions W as mentioned above H such as the new+ advanced YEditX
menu functions cannot run on a Cakewalk version ) s$stem+ and some of them ma$ not run on
Ton Valkenburgh
versions ( or , if the$ contain version - arguments. /ee this in mind+ and if $our rogram
re'uires a more advanced CA" s$stem than !.0+ $ou will have to call similar rograms to test
for DV.35621E being less than )1+ (0 or -0 deending on the oint where $ou wish the test to
fail.
At the ver$ start of a CA" rogram+ itXs a good idea to DincludeE the small XGneed version.calX
rogram W see chater (.0Q Y9uilding an include librar$X H that tests the version level of the CA"
s$stem the user is running and makes sure that it is sufficient for running the rogram. 6f the
test in YGneed version.calX fails+ the entire CA" s$stem aborts and all e%ecution stos.
0.1.2 :p/ar8s compat"#"l"ty
To ensure uwards comatibilit$ $ou must alwa$s use internal CA" names instead of the
values. ..g. never use Y1((X instead of D12T.E+ because the develoers of CA" ma$ decide to
change internal numbers.
Another asect is+ tr$ to understand the CA" functions ver$ thoroughl$. 6f $ou tr$ to
understand functions b$ e%erimenting with trial and error+ $ou ma$ end in using a bug instead
of a meant functionalit$. 6f the CA" develoers fi% this bug later+ $our rogram will not work
an$more.
=nfortunatel$ CA" is so badl$ documented that sometimes $ou need the trial and error
aroach.
This does not mean that $ou will not have an$ roblems when $ou ugrade to a higher level of
Cakewalk. "et me give an e%amleQ
6n Cakewalk Pro Audio when $ou mark one note+ the D#romE and DThruE variables are e'ual+
with e%cetion of the last note in the se'uence. :ith the last marked note the difference
between the DThruE and D#romE variables is the note duration.
6n Cakewalk 521A3 the difference between the DThruE and D#romE variables is alwa$s the
note duration.
,.! *etails of event se'uences
6f $ou assign a 86*6 channel to a track+ events on that track will be broadcast over that channel
even if the event has a different channel assignment within its data attern. This is wh$ $ou can
bounce events from track ! on channel ! to track ( on channel ( and have them all go out on
channel (.
7ou can see this oddit$ if $ou e%amine a track b$ selecting the YEvent =istX view and look at
events that were bounced from another track. The$ will likel$ be allocated to a different
channel than the events native to the track. &owever+ all of them will outut to the channel for
that track roviding one has been selected. 6f $ou were to select none >88? for the track channel
b$ inserting a Y%X+ then the events would be broadcast on whatever channel their event data
sa$s.
This is good to know because events on a track can be segregated for editing b$ changing their
86*6 channel without reall$ changing the channel the$ will be broadcast to. 9e aware that even
though we call the 86*6 channels 1 through 1-+ CA" internall$ calls them channels 0 through
1,.
Although it ma$ not seem imortant on the surface+ different events have different amounts of
data associated with them. :hile all events have a time+ at which the$ are to be broadcast+ and
a channel the$ are set to broadcast over. 1ote events will also have a itch+ velocit$ and
duration as art of their data content or a controller event will have a controller number and a
controller value. All data associated with an event will be referred to as one or more of its
YvariablesX+ because these values can be read and changed in the editing rocess. :hen writing
Ton Valkenburgh
CA" rograms+ one of the easiest mistakes to make is to forget what event t$e has what kinds
of variables.
A note event has a duration variable associated with it. As a result+ when the note is sent over
86*6+ a Y<ote OnX command will be sent at the startHtime of the note+ and a searate Y<ote
O((X command >usuall$ another Y<ote OnX command but with a velocit$ of Y%X? is sent after the
duration time has elased. Therefore+ even though the note is disla$ed as one event in the
se'uence+ it results in the broadcasting of two searate 86*6 commands in order to satisf$ its
urose. 6f $ou have ever Y'asted with repla)eX a measure over a note that e%tended from the
revious measure into the one being asted over+ $ou ma$ have e%erienced a stuck note due to
the confusion that can be caused b$ overwriting a sustained Y<ote O((X.
,.) Correcting se'uences which do not look se'uential
521A3 suorts the concet of Y4lipsX within a track. Y=inked 4lipsX can be used to create
reetitive Y4lipsX. The use of Y=inked 4lipsX across tracks+ however+ ma$ be seen b$ $our CA"
rogram as out o( se7uen)e.
6f $our CA" rogram is sensitive to the se'uence of the D.ventsEevents $ou must combine the clis
in one track. #or further information the 521A3 manual and hel files.
,.( #orcing Version - >.dit6nterolate? To =se 8arkers
As mentioned several times elsewhere+ the DEdit1nterpolateE function doesnXt work correctl$ in
version -. 6n other versions+ it resonds to the D#romE and DThruE marker values without an$
roblem+ oerating onl$ on the selected ortion of the se'uence defined b$ these markers. 6n
version -+ DEdit1nterpolateE will not resond to the markers and will oerate on an entire track
from beginning to end regardless of the values in D#romE and DThruE.
As it turns out+ it is ossible to switch the DEdit1nterpolateE functionXs resonse to the D#romE and
DThruE markers back on. ;len discovered this 'uite b$ accident one da$ and this is how ;len did it.
Zust before the function statement+ $ou add a air of du**" statements that donXt have an$ use as
CA" oerations+ but somehow forces the DEdit1nterpolateE function that follows to use the
markers. Zust t$e in these two lines above the >.dit6nterolate 1? function as shownQ
(= Drom Drom)
(= !hru !hru)
(Edit"nterpolate 1)
2nl$ now will CA" honor the values in these markers. This can lead to some real confusion in
writing CA" rograms using DEdit1nterpolateE if $ou arenXt aware of this oddit$ which is+ even
more oddl$+ comletel$ undocumented. Also+ kee in mind that $ou must do this [ust before ever$
single DEdit1nterpolateE function in $our rogram+ as one instance of these du**" statements
isnXt enough to condition all of the interolation functions in a rogram. #or convenience+ if $ou are
writing code that needs to be ortable across several versions of Cakewalk+ [ust make it a ractice
of writing DEdit1nterpolateE functions as mini macros of three linesT the two dumm$ statements
and the interolate statement. 6n other versions of CA"+ the e%tra statements will have no effect+
neither good nor bad. 6n version -+ the$ will save $our buttL
,., .%licit and imlicit track selection
#rom version ) to 521A3+ there have been changes along the wa$ in the reresentation of selected
tracks. 6n Cakewalk $ou have e%licit and imlicit selected tracks. This can sometimes create
confusion. 6n ever$ version+ one track is alwa$s imlicitl$ selected regardless of an$ other action.
Ton Valkenburgh
The behaviour of Cakewalk with regard to e%licit and imlicit selected track can create confusion.
6n the icture below $ou can see the different track situations for 521A3Q
Track 1Q an e%licit selected trackT
Track !Q an imlicit selected trackT
Track )Q a not selected track.
6n the various Cakewalk versions the tracks ma$ be identified differentl$ from 521A3.
.%licitl$ selected tracks are shown b$ their track numbers highlighted in blue if $ou are using the
default colors.
The imortant thing about an imlicitl$ selected track is+ that with no e%licitl$ selected tracks
available+ the imlicitl$ selected track will be the default focus of man$ actions that the user can
take including+ for e%amle+ oening the YEvent =istX view. 2n the other hand+ e%licitl$ selected
tracks are the onl$ ones sub[ect to the userXs editing actions and most of the oerations of CA"
rograms.
6f $ou erform an edit or run a CA" rogram in Cakewalk version )+ the imlicitl$ selected track
will alwa$s be affected along with an$ other tracks that might be e%licitl$ selected. The drag is
that although an$ e%licitl$ selected track can be selected and likewise deselected at will+ either b$
clicking on the track or b$ e%ecuting the >DTra)k?ele)tE? function from CA"+ the imlicitl$
selected track cannot be deselected+ onl$ changed from one track to another b$ the user.
=nfortunatel$+ it is e'uall$ sub[ect to an$ actions about to befall the e%licitl$ selected tracks. 6t
imossible to have no selected track in Cakewalk ). This is not true for the other versions. 6n
versions ( till 521A3+ the imlicitl$ selected track is mostl$ not sub[ect to editing or CA" actions
unless it is also e%licitl$ selected
)8
.
This selection characteristic can lead to roblems when running a CA" rogram that oerates on
several tracks and must therefore be free to select and deselect these tracks as needed. As these
tracks are selected+ acted uon+ deselected and other tracks selected+ the imlicit selected track will
be e'uall$ affected each time. An e%amle is a rogram that selects a range of tracks and sets all of
the events on each track to a uni'ue 86*6 channel number. 9ecause this rogram selects the tracks
one at a time and then erforms an interolation on them+ the imlicit selected track is also
interolated over and over each time some other track is selected and oerated on. The solution is to
oerate on all e%licitl$ selected tracks first and then deselect all other tracks and interolate the
events in the imlicit selected track last. This has the effect of undoing all of the undesired
interolations the track was sub[ected to while each of the others were selected and oerated on.
There ma$ be cases when an action is carried out that cannot be undone in this manner. 6n cases
such as this+ it is imortant that the user ensures that the imlicit selected track is an emt$ track so
)8
6n 521A3 the DinsertE function inserts+ if not in a D(orEa)hEventE loo+ in the imlicit selected track.
Ton Valkenburgh
that as CA" selects tracks for editing+ these e%licitl$ selected tracks are the onl$ ones with an$
data that will be affected.
,.- =sing the CA" View :indow
The look and functionalit$ of the CA" editor W for versions of Cakewalk before 521A3 H has not
changed much from version to version with the e%cetion of one feature known as Yparentheses
kissingX which 6 will e%lain later and the addition in version 0 >finel$L? of te%t cut and aste
editing functions. Aside from this detail+ the following discussion will al$ e'uall$ for all versions
of Cakewalk from ) through 8.
0.2.1 Enter"n* CA; <e.t
The CA" editor has been otimiPed for writing CA" code in two wa$s. #irst+ the tab ke$
causes the cursor to indent [ust enough to hel kee nested functions looking neat and readable.
The indention is onl$ two characters wide so itXs ossible to have long strings of multil$
indented te%t and still not run off the end of the age. As $ou use the YEnterX ke$+ the cursor
will start on the ne%t line at the same indention oint as the line [ust above. This makes entering
nested code a breePe. To back u one indention level+ [ust hit the Y!a)kspa)eX ke$ once and the
cursor will move to the left coming to rest at the revious indention oint. This makes it eas$ to
lace the closing arentheses for functions at the roer indention oints that corresond to
their oening arentheses.
The other otimiPation is the Yparentheses kissingX feature. :hat this feature does is hel the
rogrammer check to see if the closing arenthesis the$ are entering corresonds to the
e%ected oening arenthesis. The wa$ this works is that as a closing arenthesis is t$ed in+
the editor will briefl$ scroll u to and highlight the oening arenthesis that the editor
associates with it. 6f the oening arenthesis is the one the rogrammer e%ected to see+ then
the code is Yin phaseX 6f the highlighted arenthesis is one that the rogrammer didnXt e%ect to
see+ then the code is Yout o( phaseX and the rogrammer has either left out or added in too man$
arentheses somewhere in the rogram. This is a ver$ valuable checkHu device+ and it is a real
shame that it was removed starting with version ,+ and continuing with version -. The roblem
is that the editor will onl$ highlight an oening arenthesis if it is visible in the window along
with the closing arenthesis being t$ed in. The editor will no longer scroll back through the
code to disla$ the section where the oening arenthesis is located if itXs out of view. This
flaw has been corrected for version 0.
There is an arra$ of buttons at the bottom of the CA" editor screen in versions ) through -. The
YOpenX+ Y?aveX and Y?ave;sX buttons need no elaboration. The$ work much the same as for
an$ :indows alication. The Y<ewX button clears the editor >$ou are romted to save an$
unsaved work+ of course? and disla$s a default temlate that consists of an oening D2doE
function+ an indented D16"E lace holder and a closing arenthesis. The D16"E is highlighted
blue+ meaning that an$thing entering the editor either from the ke$board or b$ recording a
macro will delete and relace it. Therefore+ $ou can [ust start t$ing in $our code and it will
begin at the first indention oint and on the first line directl$ beneath the D2doE. 5o long as $ou
do not force the cursor be$ond it+ $our code will also sta$ [ust above the closing bracket for that
oening D2doE. The YRunX button starts e%ecution of whatever code is resent in the editor. The
YRe)ordX button is a bit different in that once it is set into motion+ it changes into a Y?topX
button. This button starts and stos the 8acro recording feature of CA".
6n versions 0 and 8+ the CA" view has taken on the standard look of an$ :indows 9, te%t
editor. All file and edit oerations+ including an YCndoX feature+ are available from the standard
droHdown menus at the to of the screen which take on a CA" conte%t when the CA" view
has focus >6ts title bar is blue?. #rom these menus+ $ou can create a Y<ewX work area+ load and
save files in the usual manner and access the te%t editing features. The YRe)ordX Y?topX and
Ton Valkenburgh
YRunX functions are now controlled b$ a set of transort buttons [ust above the te%t window and
oerate as one would e%ect.
Zust as $ou can now have multile worksaces oen in versions 0 and 8+ $ou can have multile
CA" rograms oen too. 7ou must be careful not onl$ which CA" window has focus when
$ou run a rogram+ but also which song has focus. 2therwise+ $ou could end u running the
CA" rogram on the wrong songL
0.2.2 ="88en traps "n the CA; e8"tor
#rom time to time+ 6 will be writing code and get an error that 6 canXt clear no matter what 6 do.
#or e%amle+ 6 ma$ get a Y8issing one or more closing arenthesesX error and not be able to
find the offending art of the rogram. There were times when 6 have had to scra the entire
rogram and reHenter all of the code again in order to get it to run+ even though the old and new
code are identical to the e$e. As it turns out+ the$ ma$ not be identical to the CA" interreter.
Things that the e$e canXt see in the editor window are lain as da$ to the interreter.
6 have discovered that 6 could have what aears to be bulletHroof code and still not be able to
clear a Y8issing one or more closing arenthesesX error. 6n fact+ 6 tried once to remove entire
chunks of a rogram to make it go awa$ onl$ to be left with
(do
) ; end of do
and still 6 got the errorL 6 then added the D16"E so that it read
(do
$"G
) ; end of do
[ust like $ou see when $ou first oen the CA" view+ and still it was there. 6 ended u saving the
fragment to disk along with a co$ of the same fragment after erforming a Y<ewX+ then looked
at both with a he% editor to see wh$ one would run >not do an$thing+ but at least it would run?
and the other wouldnXt. :hat 6 discovered surrised the hell out of meL The onl$ difference was
that the working code had two line feeds at the end and mine did not. 6 went back to m$ full
rogram+ added two line feeds at the end and 9.&2"*L 6t ranL
5ometimes a YCA" .rror 001Q 5$nta% errorX will cro u and disla$ a chunk of te%t from a
comment line. 6 have found that using double semicolons at the start of the offending comment
line will clear it. 6 do not know wh$+ it [ust does. There have been other times when no matter
what 6 do+ 6 still got some sort of error or another+ and the onl$ wa$ 6 could solve this roblem
was to remove some or all of the comment lines in the rogram. There have been times when 6
have had to wie the screen clean and enter the code all over againL Again+ 6 donXt know wh$
this is true+ but it is. Perhas a stra$ nonHdisla$ing b$te somehow finds its wa$ onto the
screen. 7ou cannot see it+ but CA" does and siml$ cannot figure out what to do with it. The
onl$ solution is to clear some of the te%t >and resumabl$ the bogus b$te with it?+ and start
over. This has not haened often+ but it has haened more than once to me in both versions )
and -. 6t has also haened to other eole 6 know.
6f $ou fail to indent the lines after the oening G2doE in a rogram b$ at least one tab sace+ $ou
ma$ get errors. 6t seems that CA" needs these tab characters in the code to kee the functions
strait and thus interret the code correctl$. As a rule+ this isnXt a roblem in that good
rogramming ractice will dictate the use of tabs to indent each nesting level as the code is
entered and so this roblem should never arise. &owever+ if $ou get in a hurr$ to test some
small fragment and in $our haste fail to indent at least one tab sace in ever$ line e%cet for the
oening D>doE and closing D3E+ $ou ma$ not get the code to run even if it is otherwise flawless.
6f $ou check the section where 6 discuss the DdoE function+ $ou will see mention of another
strange 'uirk in the CA" s$stem. 6 had a section of code in one rogram made u of cascading
Ton Valkenburgh
Di(E statements like soQ
(if (something or another----)
(if (some more stuff---)
(if (yet another statement---)
(do
(a bunch of stuff---)
(and so on---)
(and so forth---)
) ; end of do
) ; end of if
) ; end of if
) ; end of if
#or some reason+ CA" would not see the final Di(E or an$ of the code nested under it. 6 got no
error message or an$ other indication of a roblem+ it was siml$ ignored regardless of the
outcome of the Di(E statement above it. 6n order to test for CA" even going to the code+ 6 added
a DpauseE statement to sto the rogram and let me know if CA" had gotten that far. 6n order to
use the DpauseE+ 6 had to add a DdoE to the stack of statements like so.
(if (something or another---)
(if (some more stuff---)
(do
(pause #found the "D statementJ%)
(if (yet another statement---)
(do
(a bunch of stuff---)
(and so on---)
(and so forth---)
); end of do
); end of if
); end of do
); end of if
); end of if
After adding the DdoE and DpauseE+ the rogram worked erfectl$. 6 couldnXt figure it out+ but 6
went ahead and removed the e%tra DdoE and DpauseE as well as the closing D3E 6 had added for
the DdoE and again the rogram stoed working. 6 finel$ went back and ut the DdoE back in
without the DpauseE and ever$thing was fine. 6 know that the DdoE is unnecessar$ according to
the s$nta% of CA"+ and $et the rogram would not run without it. ;o figureL 6f this ever
haens to $ou while cascading a bunch of Di(E functions+ tr$ adding a DdoE to the sot where
CA" seems to be getting lost. 6t might be all $ou need to make things right.
9elieve it or not+ 6Xve had situations where the order of variables in a comarison involving
Pero had an effect on the abilit$ of a function to generate an outcome. This sometimes will not
workQ
(if (7 count)
but if $ou rewrite it like thisQ
(if (6= count )
Ton Valkenburgh
it will run [ust fine. 6t seems that there are times when lacing the Pero first and then the other
variable will cause trouble.
6 must mention one more thing. 6 started la$ing >a bit roughl$+ 6 must admit? with CA" in
version 0 one da$ and caused it to enter some funk$ mode where ever$ function caused a DCA"
.rror 001Q 5$nta% errorE to be reorted. All 6 could do was to restart Cakewalk and ever$thing
was fine. 6 never could reroduce this roblem a second time+ but [ust to be safe+ if $ou ever get
into a situation where CA" or an$ other art of Cakewalk stos obe$ing the rules+ save $our
work+ shut down and restart. That does the trick 99J of the time. #or those 1J cases+ restart
:indowsL
6n case $ou might be curious+ there are wa$s of crashing Cakewalk through the CA" editor. 6f+
for e%amle+ $ou take a Y<ewX CA" screen in version - and in lace of the D16"E t$e in >if ?
and hit the YRunX ke$+ $ou will get a :indows s$stem error and Cakewalk will shut down. 6f
$ou reall$ want to be malicious+ tr$ setting the variable D1owE to a ver$ large )! bit valueL
5uosedl$+ the marker variables are double words+ which mean the$ should be able to hold
an$ )! bit number from 0 to over ( million. &owever+ if $ou tr$ to set D1owE to an$ number
near this ma%imum value+ not onl$ will Cakewalk generate a s$stem error+ but if $ou kee reH
oening Cakewalk and doing it again+ $ouXll eventuall$ blow it right out of the waterL :hen
$ou restart Cakewalk the ne%t time+ $ouXll discover it has forgotten its 86*6 inut assignments.
6 gather :indows still thinks there is an oen co$ of Cakewalk running and refuses to oen
the same 86*6 devices for another instance of the rogram. 6n an$ event+ 6 thought it rudent to
restart :indows when it haened to me. 9$ the wa$+ all of these roblems were corrected in
version 0.0. 5o far+ 6 have not found an$thing in CA" that will make this bab$ fall.
2ne other thing worth mentioning. ;lenXs fellow CA" hacker *ean 9rewer in 5outh Africa
told him about a CA" rogram he had written to chase down dulicate events that wouldnXt run
even though it was+ b$ all aearances+ flawless. 6t ket giving him Y.%ression too comle%X
errors. ;len did some la$ing around with it and discovered there is a limit to the number of
functions a CA" rogram can handle. That limit is !,-. 6f $ou have more than !,- functions+
$ou will generate the error. &ere is the la$out of *eans rogram+ edited for saceQ
(do
(!rac2Yelect 1 51)
(= Drom )
(= !hru T)
(a bunch of edit filter setup functions)
(say3 about 1 or 12 altogether)
(Edit,elete0 1 1 1 )
(!rac2Yelect 1 51)
(= Drom )
(= !hru T)
(a bunch of edit filter setup functions)
(say3 about 1 or 12 altogether)
(Edit,elete0 1 1 1 )
(another section li2e those above)
(more sections li2e those above)
Ton Valkenburgh
) ;end of do
Altogether there were 11 such grous of functions+ each grou made u of an$where between 8
and 1, functions. To make a long stor$ short+ there were !-1 functions between the oening
D2doE and the closing D3E. 6 tried his suggested+ though as $et untried fi% of grouing each
section in its own set of D2doE nests like soQ
(do
(do
(!rac2Yelect 1 51)
(all of the functions in this group)
) ; end of do
(do
(another group of functions)
) ; end of do
(do
(another group)
) ; end of do
(do
(and the same for all 11 groups)
); end of do
) ; end of do
And so on and so on for all 11 grous. 6t ran without error. 1ow the rogram was made u of
onl$ 11 functions instead of !-1 functions. 6t [ust so haened that each of those 11 functions
nested between 8 and 1, other functions+ but now CA" did not care. 6t was not a matter of how
man$ functions total there were+ but [ust how man$ nests there were. To further address this
issue+ 6 removed all of those D2doE nests and then counted !,, functions before adding the
D2doE. 6t still worked. 6 moved the D>doE one more function down to go between the !,-
th
and
!,0
th
and the error returned. 5o long as onl$ !,- functions were resent+ the !,, functions lus
the one D2doE function nesting the rest of them+ ever$thing was cool and the rogram ran. There
is likel$ a limit to the number of nested functions that a CA" rogram can deal with in this wa$
also+ thus utting an uer limit on the total number of functions of an$ configuration that CA"
will tolerate+ but 6 have not been able to find that limit. 6 do know that CA" version ) will onl$
allow 10 nesting levels >nests within nests within nests? and that :indows )! bit versions will
accet more than this before giving an error. 2therwise+ the true limits of CA" are there for $ou
to e%lore. 5end me an email if $ou find another boundar$ and 6 will add the information to this
document.
0.2.3 5ecor8"n* !acros
2nce the YRe)ordX button in the CA" view
)9
window is clicked+ man$ of the mouse and ke$board
actions $ou take involving the 8enu toolbar or the YTra)k. View will result in the generation of
CA" code in the editor worksace. As $ou have seen from the above discussion of YenuX
functions+ there are man$ oerations in CA" that correlate directl$ with actions that can be taken
from the toolbar. :hen $ou click YRe)ordX+ the CA" view window disaears and $ou are laced
back in one of the se'uencer views. #rom here+ $ou can carr$ out normal oerations on the
)9
1ot available in 521A3 an$more.
Ton Valkenburgh
se'uence oblivious to the fact that CA" is recording some of $our actions as rogram code. This
recording will continue until $ou switch back to the CA" view and click Y?topX.
:hat $ou will see in the editing window as a result of recording is first a comment line declaring
Y?tart o( re)ordingX followed b$ an$ actions $ou took that are recordable as CA" functions. After
these function statements is another comment line stating YEnd o( re)ordingX. All of the arguments
for each function will be resent in the form of numbers that reflect an$ data and whatever bo%es
were checked or in force at the time the menu command was invoked. As recorded+ these CA"
statements have ver$ limited use outside the secific conditions at the time the$ were recorded. 6n
order to use these macros to carr$ out their actions under different conditions+ man$ of the
arguments will have to be edited and relaced with variables. 2nce $ouXre ha$ with whatever
$ou have recorded and edited+ $ou can save it as a Y.4;=X file and can be run at will like an YEditX
menu feature.
0.M.+.& 're8setting Edit Fun)tions Csing a)ro Re)ord
As 6 mentioned earlier+ setting u some of the YEditX menu functions can be a real ain in the butt+
eseciall$ if the filters are involved. :e can save ourselves some ma[or t$ing b$ using the 8acro
record feature to pre8write most of the needed code. :hat we would do is lace the cursor at the
oint in the CA" rogram code where we want the function to go+ and then click the YRe)ordX
button. After doing so+ the disla$ will leave the CA" view and go to the last view window $ou
were in. 1ow select a track with some events in it and set the #rom and Thru markers to an$ art of
the track containing events+ if the$ arenXt alread$. ;o to the .*6T menu and do the followingQ
#or Cakewalk )+ click on the edit feature $ou want to ut in $our CA" rogram and set the
check bo%es and window values as $ou might want them. Check YCse Event FilterX if $ou will
need to filter the edit. 6f $ou checked YCse Event FilterX+ $ou will be resented with the filter
window. 8ake whatever selections $ou what CA" to use when $our rogram is run.
Re*e*ber+ the settings $ou make here will be in force ever" ti*e the rogram runs so make
sure $ou know what $ou want the function to doL #or an$ arguments that will eventuall$ be
filled in b$ variables in the rogram+ donXt worr$ what values the$ are set for now+ as those
values will be relaced during editing. Click YOkX to comlete the oeration. After finishing
with the edit+ go to the YEditX menu and click YCndoX to reair whatever $ou [ust did to $our
se'uence >unless $ou like what $ou did and want to kee the change?. 1ow fli back to the
CA" view and click the Y?topX button.
#or Cakewalk ( or higher+ from the YEditX menu+ oen the Y?ele)tX subHmenu and then the Y!"
FilterX otion. 5et u $our filter even if it is nothing more than clicking the Y;llX button. 1ow
click on the editing feature $ou wish CA" to run and fill in the bo%es and windows as needed.
2therwise+ the same rules for the window contents al$ as noted for Cakewalk version ) as
discussed above. Afterwards+ erform the same YCndoX from the edit menu to restore $our
se'uence and then sto the macro recording.
1ow $ou must edit the resulting functions CA" has laced in $our rogram. 3elace the
numbers in the marker arguments with D#romE and DThruE+ the variable names $ou wish to use
or the functions that will result in the times $ou wish to be in effect when the edit runs. *o the
same for the values of YminX and Yma%X as needed for an$ Y?etFilterRangeX functions that
re'uire them. This also alies if $ou will be using variables for an$ of the other arguments.
As we discussed in the chater regarding YEditX menu functions for Cakewalk version -+ a
macroHcreated DEdit1nterpolateE function will onl$ work for marker variables D#romE
e'ualing 0+ and DThruE e'ualing D.ndE regardless of what $ou change the D#romE and DThruE
values to. 6n other words+ the macro will oerate on the entire length of the track and cannot be
set to oerate on onl$ a segment instead+ at least not directl$. 6n order to force CA" to
Ton Valkenburgh
recogniPe values for the markers other than 0 and D.ndE+ we must reface the
DEdit1nterpolateE function with two du**" statements >see chater ,.(Q Y#orcing Version -
>.dit6nterolate? To =se 8arkersX for a discussion of this aroach?. Place these du**"
statements [ust before each DEdit1nterpolateE function in $our rogram. This will have no
effect in versions other than -+ but will activate the necessar$ marker recognition in version -
thus assuring ortabilit$ of $our code.
<ote: that it aears that $ou must use these du**" statements for ever" such function+ not
[ust the first.
Also remember that most CA" (.0 functions need to have the markers set u beforehand and
the CA")0 functions re'uire the markers as arguments. Also remember that the CA" ).0
functions will work in all versions of Cakewalk whereas CA" (.0 functions will not work in
Cakewalk version ). 6f $ou want $our code to be backward comatible and $ou record $our
macros in version ( or above+ $ou must rewrite the functions to turn them into CA" ).0 format.
=nfortunatel$+ this ma$ mean it will be easier to write the code b$ hand and forget about
macros.
0.2.$ >host ,n <he !ach"ne
6f $ou ever enter a bunch of code into the editor and it siml$ will not run+ donXt be too
alarmed. #irst of all+ $ou must tr$ to take the error message seriousl$ and attemt to address the
offending code. &owever+ if $ou have followed all of the rules and the code still will not fl$+
$ou ma$ have run into one of man$ strange effects of the CA" editor. 5ee the chater ,.-.!Q
Y&idden tras in the CA" editorX for details. As far as legitimatel$ issued error messages go+
some of the more common ones are+ Y8issing one or more closing arenthesesX+ Y.%ected
closing 'uoteX+ Yunknown pro)edureX+ YCA" .rror 00)Q :rong number of argumentsX+ YCA"
.rror 001Q 5$nta% errorX and the infamous Y.valuation stack overflowX. 6f $ou reall$ iss it off+
$ou can end u with a :indows Y'rote)tion FaultX and<or :indows Y1llegal Operation
errorX+ which will shut Cakewalk right down and ma$be even :indows with itL This is not
CakewalkXs fault. 6f $ou hose $our code so badl$ that it chokes the s$stem+ then $ou robabl$
deserved itL Cakewalk+ roerl$ installed+ is ver$ stable under :indows+ and this is sa$ing allot
considering that :indows before :indows !000 isnXt e%actl$ the 3ock of ;ibraltar. As far as
the internal CA" errors+ these can be dealt with.
The error about the closing 'uotes is eas$ to fi%. Zust hunt through $our code until $ou find a
missing set of 'uote marks. There is nothing secial about that. The Dunknown rocedureE and
Ds$nta% errorE messages can usuall$ be traced to a t$o somelace. Perhas $ou didnXt use a
caital letter when $ou needed to+ or there ma$ be a variable without a ke$word somelace.
Take $our time looking for these things. 6f $ouXre told $ou have the Dwrong number of
argumentsE+ then look for an incomlete function. Another cause+ believe it or not+ can be the
failure to indent roerl$. 7ou should alwa$s indent at least one tab sace awa$ from the left
margin after the oening D>doE no matter what. 6f $ou donXt+ this is one wa$ CA" can e%ress
its dissatisfaction with $ou. 6f $ou imort $our te%t from a word rocessor+ $ou might be
dealing with hidden characters that will not disla$ on the screen but never the less are seen b$
CA" at run time. 6f $ou can narrow the roblem down to a line or two+ it a$s to [ust delete
them and reenter the code.
An Y.valuation stack overflowX is a bit harder to clear. 6t could even mean scraing the
rogram all togetherL This message is an indication that CA" is being asked to [uggle too man$
balls at once. 6t can result from a statement that is too comle%. 5litting the statement u into a
grou of simler nested functions can solve this. 2n the other hand+ $ou ma$ be declaring too
man$ variables. Tr$ to make some of them do double dut$ or use the DundefE function to clear
some variables after the$ have fulfilled their destinies and then declare some more as needed. 6f
$ou run too man$ nests in one function+ this will cause it. 7ou can tell if $ou have done so if
$ou have reached a oint where a statement is indented over so far as to be half wa$ across the
screenL 6f $ou canXt reorganiPe $our code to reduce the number of nests in this oor function+
Ton Valkenburgh
$ou ma$ have to rethink $our entire ro[ect. 8a$be $ouXre asking too much of CA" and $ou
need to create a simler version of the rogram.
This brings us to Y8issing one or more closing arenthesesX. 7ou might think this would be an
eas$ error to clear+ but itXs not all the time. A missing arenthesis can be ver$ hard to sot. "ife
is a bit easier using versions where Darentheses kissingE works. 2ne can alwa$s backsace
over a arenthesis and then reHenter it and see what oening arenthesis is highlighted. After
going back through the code doing this ever$ few lines+ the outHofHhase statement will
eventuall$ show itself b$ causing the wrong oening arenthesis to highlight. 1ow+ itXs a bit
more of a hassle with versions , and -. This is a good reason to be ver$ diligent in oneXs
indenting. 5ometimes the indention level being off is the big clue to where the missing
arenthesis needs to go. :hatXs more+ there are times when this error can occur and there be
nothing at all wrong with the arentheses. Take a look at the e%amles 6 cite in the chater
,.-.!Q Y&idden tras in the CA" editorX.
,.0 =nder the influence
;len has several versions of Cakewalk on the same comuter. 1otabl$+ he has version )+ version -
and version 0. As a bit of background+ he started out with version ) on a )8- running :indows for
:orkgrous ).11 and later installed it on a (8- running the same version of :indows. 2ver time+
he installed :indows 9, release A on that (8-. Around *ecember of 1990+ he obtained a co$ of
version -.01 and installed it into another director$ of the (8- and ran both versions so he could
comare features as art of writing this CA" tutorial. &e remembered noticing that the CA" editor
of version - lacked the abilit$ to erform YparenthesesX when the oening arenthesis was off the
screen. &e was a bit disaointed with this because he found the feature ver$ useful in debugging
CA" code. This aside+ he soon after ugraded to a Pentium and :indows 9, release 9. Again+ he
installed both coies of Cakewalk on his s$stem+ first version ) and then version -. 2ne da$+ he
went back to version ) to do use the full$ oerational arentheses kissing feature on a CA"
rogram he was troubleshooting+ and it was goneLLL That is to sa$ that the feature in version ) now
works e%actl$ like it does in version -. 5omehow+ version - has )onta*inated version ) to the
oint that version ) has started taking on some of version -Xs characteristics.
&e did not know how this haened+ but he tried it on another Pentium he had in the bedroom and
sure enough+ as soon as he installed version -+ version ) lost arentheses kissing. &e tried
uninstalling version - and reinstalling version ) but the contamination remains to this da$ on both
comuters. .ven now that he had installed version 0 beta on one of them with arentheses kissing
restored+ he still has the roblem with version ). &e has also tried installing version ) on other other
)8- and (8- comuters running :indows ).11 and ever$thing is fine. &e has installed on another
(8- running :indows 9, release A and have full arentheses kissing. &e even installed it on a
Pentium Pro running :indows 9, release 9 and had no trouble. &e then installed version - on the
Pentium Pro s$stem and version ) was )o*pletel" una((e)tedLL ;o figureL
This ma$ seem like a small thing to be worried about+ but let me sa$ that the arentheses kissing
henomenon is the onl$ contamination effect he has noti)ed. 2ther subtle changes are ma$be not
noticed. 6 donXt know how likel$ it is that this cross )onta*ination would haen on $our or an$
other s$stem+ but at least be aware that if $ou have multile versions of Cakewalk on the same
comuter+ odd things might haen.
,.8 CA" interactions with digital audio
This is going to be a small chater in that 6 have onl$ noticed one bit of odd behavior running a
CA" rogram on a 86*6 track and then having some strange effect on digital audio tracks. 6 have
noticed in version 8 that allot of things will cause the audio effects YReturnX knobs to reset to the
full YO((X osition if $ou fail to take an oening snapshot at the start of a ro[ect. Among these
Ton Valkenburgh
causes is running CA" on a 86*6 track with the Console View oen even if that view does not
have focus >its blue Title 9ar is gra$?. 6t doesnXt haen all of the time+ [ust like closing a ro[ect
and reoening it doesnXt alwa$s move that knob to YO((X+ but sometimes it will. 6 canXt lock down
an$ reeatable attern+ it [ust haens once in a while. 6f $ou ever run a CA" rogram and after
starting la$back notice that $our audio tracks have gone dr$+ erhas the au%1 YReturnX knob has
been reset. 6 have made it a habit to record all audio Console View and effects settings in the songXs
Y1n(oX age and kee it udated as 6 edit. 6tXs good to also include an$ settings for $our audio card
mi%er or outboard mi%er too.
,.9 *etails on 3P1 and 13P1 Controller .vents
6f $ou want to kee the D3P1E event function and still want a convenient wa$ of changing itch
bend deth from the .vent "ist view+ the following chart should rove valuable. To change the
bend deth for most ;eneral 86*6 comatible s$nthesiPers+ $ou would issue ) controller events.
The first would be controller number 100 with a value of 0. The second would be controller number
101 also with a value of 0+ and the last would be controller number - with a value corresonding to
the number of semitones $ou want the bend range to have. 5ome instruments also re'uire a forth
controller event to terminate the string. 6t is controller )8 with a value of 0. The D3P1E event that
does the same thing will have two digits associated with it. The first will be a arameter value of 0
and the second will be a data value number e'ual to the number of semitones of bend deth
multilied b$ 1!8. #or e%amle+ if $ou wanted to set the bend deth to lus or minus an octave+ or
1! semitones+ the controller se'uence would beQ
/ontroller 13 value of
/ontroller 113 value of
/ontroller L3 value of 12
/ontroller 3S3 value of (not always needed)
The same [ob would be done b$ the single D3P1E event having a arameter value of 0 and a data
value of 1,)-. The following chart outlines all 3P1 data values for bend deth ranges from G<H 1 to
G<H !( semitones. 6n all cases+ the 3P1 arameter value is 0.
!end Depth
2,N8 se*itones3
R'< Data
Valu2Depth > &2O3
1 1!8
! !,-
) )8(
( ,1!
, -(0
- 0-8
0 89-
8 10!(
9 11,!
10 1!80
11 1(08
!end Depth
2,N8 se*itones3
R'< Data
Valu2Depth > &2O3
1! 1,)-
1) 1--(
1( 109!
1, 19!0
1- !0(8
10 !10-
18 !)0(
19 !()!
!0 !,-0
!1 !-88
!! !81-
Ton Valkenburgh
!end Depth
2,N8 se*itones3
R'< Data
Valu2Depth > &2O3
!) !9((
!end Depth
2,N8 se*itones3
R'< Data
Valu2Depth > &2O3
!( )00!
6f $ou have been using Cakewalk version - or higher+ $ou ma$ be aware of the D3P1E and
D13P1E events. These events are clusters of combined multile DC21T32"E events that
have been converted into a single event.
The drawback is that most of us are used to working with the controller events as is and have
no desire to learn some obno%ious formula to convert D3P1E events back and forth when we
need to view or edit them. An e%amle is the wa$ Cakewalk will take the three controller
events that make u a itch bend deth setting message and stuff them into one D3P1E event.
:hat if $ou want to change the bend deth on that track\ &ow do $ou change this D3P1E
event to reflect the change in the value b$te of the third controller event\ :ell+ without a
calculator and a few minutes of valuable time+ $ou cannot. 9ut more imortant is that CA"
rograms cannot access these events an$more. &owever+ there is a wa$ around the roblem.
9$ adding a statement to the YTT??E5.1<1X file in the CA/.:A"/c521A3 director$+ we
can instruct Cakewalk not to combine clusters of controller events into D3P1E and D13P1E
events. 2en YTT??E5.1<1X in the <otepad editor and locate the heading B2PT6215C.
=nder this heading add the line+
!ranslate'@$=
and save the file. 1ow restart Cakewalk and the D3P1E event will never darken $our
se'uence againL 1ote that if $our se'uence has native D3P1E events alread$ in it+ the$ will
aear as such. This change does not force Cakewalk to decomile D3P1E events that are
resent in a se'uence+ [ust revents it from generating them out of clusters of related
controller events. #or those who want to kee the D3P1E event and still want to change bend
deth from the .vent View+ see above for a chart of D3P1E values that correlate to itch
bend deth values.
,.10 &elful Tis for =sing the *"" #unction
9$ 8ehmet 2konsar Aug )+ 1999
;eneral Q The e%eriments were done with Cakewalk ver.8 and *elhi).
0.17.1 Data <ypes?
61T.;.35 Q *ata sent b$ CA" as t$e DintegerE must be declared as Yb"teX+ YwordX+
Ys*allintX+ YlongintX+ etc in the DD==D code. 3andom data is received if the DD==E declares
integer too.
5T361; Q An$ strings must be declared as null terminated Y)harX arra$s in the DD==E.
0.17.2 Parameters?
2ne can send ! arameters at most when calling a service in a DD==E. The third arameter+ if
an$+ does not generate an error but random data is sent.
Ton Valkenburgh
0.17.3 !emory !ana*ement?
As far as 6 know there is no wa$ to make the call to DD==E persistent or stati)+ even though
the DD==E is called b$ 521A3 >not the CA" rogram?+ the DD==E is removed from
memor$ as soon as the corresonding line in the CA" code has been rocessed. This is
because CA" is interreted and not comiled+ and it does not rovide the ossibilit$ to make
a ersistent call to a DD==E. This fact+ combined with CA"Xs own limitations+ makes it
imossible to send a bunch of data to the DD==E all at once. 6f the DD==E is to be used to
write to a file+ 521A3 kees hands on the file which can be oened+ written to and closed
onl$ once and then cannot be reoened again without closing 521A3 altogether. There is no
roblem calling the DD==E from within a loo+ though this will slow down the rogram.
0.17.$ !"scellaneous?
The arguments for the call to a DD==E must include the full ath name even if the CA" file
making the call is in the same director$ with the DD==E. This ath can be either a long name
or an YO.+ DO?Y t$e ath names. 6t seems+ the$ both work. #or sa(et" reasons 6 ket with
the *25 t$e definitions.
Ton Valkenburgh
- CA" .rror and #76 messages
9efore CA" even starts to run a rogram+ it goes through and makes sure the code is correct
enough to convert into machine instructions. 6f there are errors that revent the rogram from
being interreted+ CA" stos there and issues a message. =ntil now+ nothing has been done to
the se'uence. 2n the other hand+ if the code can be at least interreted+ then CA" starts
running it. 6f there is an error at a certain oint in the rogram+ CA" ma$ ver$ well have
alread$ done something to $our se'uence and so an YCndoX will be necessar$ to return the
status 'uo before $ou attemt to fi% and run the rogram again. To be safe+ if a CA" rogram
doesnXt erform e%actl$ as e%ected+ erform as man$ YCndoX oerations as necessar$ to
erase all actions taken b$ CA".
Another aroach is to save $our se'uence+ and then run the CA" rogram. 6f there is an error
use the YEs)apeX ke$ and reload $our se'uence without saving the da*aged one.
;len has taken this list of error messages from e%amining the te%t ortions of CakewalkXs
version ) rogram file :61CA/...4. with 85 :ord and hunting for the areas that contain
CA" related te%t. 6t ma$ not be comlete+ ma$ contain errors that donXt belong to CA" and
ma$ not reflect the full range of error messages available to later versions of Cakewalk.
&owever+ with no documentation >as is true with a great deal of CA"? and m$ own
e%erience torturing CA"+ this is what he and 6 have come u with.
Attemt to change constant
1aturall$+ $ou cannot reHassign the value of a constant like D12T.E or a readHonl$ variable
DT68.9A5.E+ and attemting to do so leads to this error. As a rule+ constants in CA" are in
all cas to make them eas$ to distinguish from variables.
CA" .rror 001Q 5$nta% error
CA" understands $our words+ but not the wa$ $ou have them arranged. Perhas $ou have
confused a ke$word with a variable or arranged the comonents of a statement incorrectl$.
CA" .rror 00!Q *ivide b$ Pero
1eedless to sa$+ if $ou ask CA" to divide b$ Pero+ it wonXt be ha$. 3ather than give $our
rocessor a coronar$ tr$ing+ CA" tras such e'uations and issues this error message.
CA" .rror 00)Q :rong number of arguments function2name
31
=nless $ou genuinel$ left out an argument in a statement+ this error is usuall$ caused b$ not
having the closing arenthesis of a nested section of code in the roer sot. 7ou likel$ have
the arenthesis somewhereT otherwise $ou would receive a D8issing one or more closing
arenthesesE error. 8a$be $ou [ust ut it in the wrong lace and so now some Di(E function
has a YthenX+ an YelseX and a stra$ e%tra art+ or a mathematical statement is being asked to
oerate on three arguments instead of two.
(0
6f the error is within a menu function $ou will not get the funcionRname.
Ton Valkenburgh
CA" .rror 00(Q=nknown rocedure procedure2name
5everal things can cause this. 7ou ma$ have mist$ed a ke$word. Perhas $ou have two
statement elements running together without a sace between them like >Gthis that? instead of
>G this that?. 8isarranged arentheses or sets of arentheses without a sace between them
will also cause this error. 9asicall$+ CA" cannot understand some word in $our code.
CA" .rror 010Q T$es do not match
6f $ou tr$ to use variables for functions unsuited for their t$e class+ CA" will let $ou know.
6f $ou attemt to lace a negative number in a DwordE variable or tr$ to erform time
functions on an integer variable+ $ou are likel$ to see this error.
CA" .rror 01(Q Value out of range
This error message lets $ou know that $ou have attemted to generate a value that e%ceeds the
range of the variable. /ee in mind that even though an integer can hold a certain value+ the
variables relating to $our se'uence ma$ not. ..g. a D1ote./e$E must be between 0 and 1!0.
CA" .rror 0!1 Program called >e%it?
This message is not an error+ but confirms that CA" has e%ecuted an DeAitE function and is
aborting.
CA" .rror 0!!Q =ser ressed cancel
This is not an error either+ but confirms that CA" has interceted the user ressing the
YEs)apeX ke$ or clicking a Y4an)elX bo% from a dialog bo% and is therefore shutting down.
CA" .rror 0!)Q Cannot oen include file file2name
CA" cannot find the file $ou have asked to be included in a rogram. This is likel$ because of
a mist$ed file name or because the file in 'uestion is in a director$ other than the one where
CA" is looking. CA" will look in the director$ where the currentl$ running rogram is stored
if no ath is secified. 6f a full ath is given+ CA" will look there instead.
Cannot load *$namic "ink "ibrar$
7ou have asked CA" to use a service from a DD==E file+ but CA" cannot find the file. The
causes are the same as listed above.
Command is disabled on the menu
&ere+ $ou have asked CA" to erform a YenuX function that is currentl$ gre$ed out in the
menuXs droHdown list such as attemting to do an YEdit'asteX with nothing in the cliboard.
Ton Valkenburgh
.valuation stack overflow
There is a limit on not onl$ how comle% a line of code can be+ but also on how man$ nest
levels $ou can build in one function. 6f $ou kee nesting Di(E after Di(E after DdoE after DdoE+
sooner or later $ou will get this error. &aving too man$ variables declared+ will also generate
this resonse.
.%ression too comle%
6t is one thing to tr$ to be efficient b$ utting as much code into one function as ossible. 6t is
something else entirel$ to build e%ressions that are so )o*pound that CA" cannot run them.
*o not tr$ to do ever$thing in one line of code. =se the nest maker DdoE if $ou need to do
much in one argument or having a large number of functions at the same level.
.%ected closing 'uote
This is lane enough. 6f $ou use 'uotes to enclose a string or a message+ then forgetting one
or more of them will cause this error.
8iscellaneous error
6Xve never seen this+ but 6 guess if $ou stum CA" comletel$+ $ou ma$ receive it.
8ismatched arentheses
Assuming $ou have the correct number of oening and closing arentheses+ $ou ma$ not have
arranged them roerl$. This error message tells $ou to reHe%amine $our code for outHofHlace
arentheses.
8issing one or more closing arentheses
This is the message $ou are likel$ to see most often. CA" counts the number of left brackets
and right brackets in $our rogram+ and if the numbers do not match+ $ou get this error. 1ot
getting this error does not guarantee that $our arentheses are on the right laces+ [ust that the
counts match. 7ou can also get this error b$ not having ! line feeds following the last closing
arenthesis at the end of $our rogram.
1ot valid in >for.ach.vent? or bod$ e%ression
This is the oosite of the above error. There are some things that $ou [ust canXt do while
CA" is scanning a se'uence. An e%amle is attemting to run YEditX menu functions during a
loo.
2ut of memor$
6 have never seen this error+ and 6 have written some big rograms. 6 guess a oint can be
reached where $ou overflow the sace CA" has to work with or insert so man$ new notes that
$our se'uence is too big to sta$ in memor$. ;o bu$ some more ra*. 6tXs [ust too chea these
da$s to be caught with not enough memor$ to get a [ob done.
Ton Valkenburgh
Proc does not e%ist in *$namic "ink "ibrar$
CA" found the DD==E file all right+ but $ou have sulied arguments that do not oint to a
valid service within that file.
Program called >error?
6f $ou set u a function to call the DerrorE function in the event of some condition+ CA" will
disla$ this message and then abort.
=ndef of undefined variable
6f $ou attemt to e%ecute the Dunde(E function to erase a variable from memor$ and there is
no such variable to begin with+ $ou will see this error.
=nknown variable
Aarentl$ $ou either attemted to use a variable name that hasnXt been declared or $ou
mist$ed the name of one that has.
Valid onl$ in >for.ach.vent? or bod$ e%ression
The oeration $ou are tr$ing to erform can onl$ be done within a D(orEa)hEventE loo.
These are things like the DdeleteE function.
Variable redefined
7ou have attemted to declare a variable that has alread$ been declared. 2ne wa$ to get this
error is if $ou include a rogram that declares a variable with the same name as one declared
in the arent rogram. To kee this from haening+ make it a habit to use different
caitaliPation for variables $ou declare in rograms $ou intend to Din)ludeE in other
rograms.
Ton Valkenburgh
0 .%amles
The e%amle rograms can be found in the PiHfile YCA" rogram samles.PiX.
Addition.cal
Purose To show the basic s$nta% of CA" with user interactions.
=sage Adds two integers entered b$ the user.
3emark 1one
86*6H
functions
1one
;8 8ode.cal
Purose 5witches the ;8 mode of the s$nthesiPer.
=sage 3un the rogramQ
.nter the ;8 8odeQ ;81F1+ ;8!F!+ ;8 offF0.
3emark
86*6H
functions
5$stem e%clusive message
Program skeleton.cal
Purose The base for creating a rogram.
=sage 2en the skeleton+ and save it with the name of the to be created rogram.
3emark Adat the skeleton to $our own needs. 3ename it+ because otherwise it
ma$ be relace b$ m$ skeleton+ when $ou get a new version of the samle
file.
86*6H
functions
1one
5how version.cal
Purose To show the structure of rograms with rogram header and comments.
=sage 3unning the rogram will disla$ the version of CA".
3emark 1one
86*6H
functions
1one
Timebase.cal
Purose To show the DT68.9A5.E value of CA".
=sage 3unning the rogram will disla$ the DT68.9A5.E value.
Ton Valkenburgh
Timebase.cal
3emark 6n certain >sub? versions of 521A3 DT68.9A5.E does not match with
the Yti)ks per 7uarter noteX+ which can be set b$ the user. This rogram
allows $ou to check whether DT68.9A5.E is the same as the setting of
Yti)ks per 7uarter noteX.
86*6H
functions
1one
Ton Valkenburgh
8 "ibrar$
The librar$ rograms can be found in the PiHfile Y86*6H/it librar$.PiX.
G!H! meter.cal
Purose 6ndicates a change in the velocit$ of marked notes according to the
osition in a measure with
!
<
!
meter.
6nut
arameters
6nteger YnVelRe(XQ Velocit$ reference >0 K 1!0?
6nteger YnDeltaVelXQ 3andom delta on velocit$ in J >0 K ,?
2utut
arameters
1one+ however+ the
note velocit$ of marked notes have been changed.
3emark 1ote ositions must be within grid.
86*6H
functions
1one.
G)H( meter.cal
osition in a measure with ^ meter.
6nut
arameters
2utut
arameters
1one+ however+ the note velocit$ of marked notes have been changed.
86*6H
functions
1one.
G(H( meter.cal
(
<
(
meter.
6nut
arameters
2utut
arameters
86*6H
functions
1one.
Ton Valkenburgh
G-H8 meter.cal
-
<
8
meter.
6nut
arameters
2utut
arameters
86*6H
functions
1one.
G9H8 meter.cal
9
<
8
meter.
6nut
arameters
2utut
arameters
86*6H
functions
1one.
GConstant.cal
Purose To rovide ro[ect constants which are not standard included in CA".
6nut
arameters
1one.
2utut
arameters
:ord Y!E;TT14:?XQ 9eat duration in ticks.
6nteger YE;?!E;T?XQ 8easure duration in beats.
:ord YE;?T14:?XQ 8easure duration in ticks.
3emark The best lace for this include rogram is before the declarations of the
variables in the calling rogram.
2nl$ one meter in the se'uence is suortedT it will use the meter at the
start of the se'uence.
<ote &: The rovided constants are not reall$ constants+ but variables.
7ou must not change the value within $our rogram.
<ote 2: <ot (or new develop*ents. The DG8eter.calE include rogram
must be used. 6t rovides more functionalit$.
Ton Valkenburgh
GConstant.cal
86*6H
functions
1one.
GController.cal
Purose To insert or relace 86*6 controllers at the marked area of one track..
6nut
arameters
6nteger Yn4ontrol<u*XQ Controller number
5tring Yt4ontrol<a*eXQ Controller name
2utut
arameters
6nteger YnDire)tionXQ indicates whether controlers went u >1?+
down >H1? or did not change >0?
3emark The user of the calling rogram must mark the area in a track where to
insert the controllers.
Option &: 8ark the note>s? and<or event>s? in the staff or event list anel
where the controller>s? must be insertedQ
3un Ythe rogramX+ and
.nter the Controller number
(1
>0 .. 1!0?T
.nter the choice for single insert or multile inserts >0..1?T
.nter the value of the controller >0.. 1!0?T
#or multile inserts enter the end value of the controllerT
#or multile inserts enter the beat value >1 ..-(?.
Option 2: 8ark the range where $ou want to insert the controllersQ
3un Ythe rogramX+
.nter the Controller number >1..1!0?+
.nter the re'uested start value >0..1!0?+
.nd value >0..1!0?+
and beat value >1..-(?.
The beat value indicates how the controllers will be inserted. The rogram
calculates the insert time b$ dividing the beat with the entered value.
86*6H
functions
*eendent on inut.
G.vents marked.cal
Purose To count number of marked events.
6nut
arameters
6nteger YnEventXQ .vent kind
2utut
arameters
6nteger YnEvent4ountXQ 1umber of .vents
3emark .vents with the same D.vent.TimeE in the same track are counted as one
(1
Can also be rovided b$ the calling rogram itself.
Ton Valkenburgh
G.vents marked.cal
event.
86*6H
functions
1one.
G8eter.cal
Purose To rovide meter variables which are not standard included in CA". The
content of the variables are deendent on the osition in the 86*6
se'uence.
6nut
arameters
*ouble word Yr'ositionXQ Position in the se'uence in raw time
2utut
arameters
:ord Y!eatTi)ksXQ 9eat duration in ticks.
6nteger Yeas!eatsXQ 8easure duration in beats.
:ord YeasTi)ksXQ 8easure duration in ticks.
:ord YeterXQ meter in the format 100I4G7. 6n which 4<7 indicates the
meter. ..g. ^ becomes )0(.
3emark This include rogram re'uires+ that the variables are declared with the
include rogram DG8eter declarations.calE .
This include rogram can be used multile times in a>n include? rogram.
8ultile meters within a 86*6 se'uence are suorted.
86*6H
functions
1one.
G8eter declarations.cal
Purose To declare the ublic variables for the include rogram DG8eter.calE.
6nut
arameters
1one.
2utut
arameters
:ord Y!eatTi)ksXQ 9eat duration in ticks.
6nteger Yeas!eatsXQ 8easure duration in beats.
:ord YeasTi)ksXQ 8easure duration in ticks.
:ord YeterXQ meter in the format 100I4G7. 6n which 4<7 indicates the
meter. ..g. ^ becomes )0(.
3emark The best lace for this include rogram is before the declarations of the
variables in the calling rogram.
2nl$ one meter in the se'uence is suortedT it will use the meter at the
start of the se'uence.
<ote: These rovided variables will me filled in b$ the include rogram
DG8eter.calE .
86*6H
functions
1one.
Ton Valkenburgh
Gneed version.cal
Purose To test whether the version number is e'ual or higher than the indicated
number.
6nut
arameters
6nteger Yn4;=VersionXQ the version number W without the dot H on which
must be tested.
2utut
arameters
1one.
3emark 6f the version of CA" is too low+ the rogram gives a message to the user+
and terminates.
86*6H
functions
1one.
Ton Valkenburgh
9 6nformation sources
Cakewalk Pro Audio =serXs ;uideT
Cakewalk 521A3 =serXs ;uideT
Cakewalk Pro Audio Y&elX filesT
Cakewalk 521A3 Y&elX #ilesT
Cakewalk PowerLT 5cott 3. ;arrigusT
:indows 8ulti 8edia Programming 3eference.
Ton Valkenburgh
10 *ocument conventions
A consistent method of highlighting is used in this document. &ere+ 6 give the aroachQ
Y1ormal between single 'uotesX ;rous words+ to mark it as a single itemT
!old 6dentifies imortant itemsT
Y!old between single 7uotesX 3efers to 521A3 functions+ 521A3 error
messages+ arameter names+ CA" files+
:indows functions+ :indows error
messagesT
D!lue !old between double 7uotesE 3efers to CA" functionsT
=nderlined items 6dentifies h$erlinks.
10.1 9ackus 1auer #orm
The notation of the functions of CA" are artl$ following the the 9ackus 1auer #orm >91#?.
&ere we will give the used s$mbols of 91#.
@4A 6dentifies an oerandT
B4C 4 is otional. 2tional oerands are denoted b$ BCT
B 4 B7CC 4 and 7 are otional. The se'uence is imortant.
B4 B7C KC 4 and 7 are otional. The se'uence is imortant. 8ore arameters
are ossible.
@4AK@7A 4 and 7 are re'uired. The number of oerands deends on the
function.
Ton Valkenburgh
11 6nde%
!<! meter................................................9!
)<( meter................................................9!
(<( meter................................................9!
-<8 meter................................................9)
9<8 meter................................................9)
Addition.................................................90
Assignment #unctions............................!,
9ackus 1auer #rom................................98
9.ATT6C/5....................................9)+ 9,
91#........................................................98
9oolean functions...................................),
9uffer functions......................................)0
CA" editor.............................................0,
CA" .rror messages..............................8-
CA" View :indow................................0,
C&A1A#T.............................................10
Chanaft.Val............................................10
Checking of .vent marking....................-1
C&23*..................................................18
Comatibilit$..........................................00
Constant.................................................9)
C21T32".............................................18
Control flow functions............................)-
Control.1um...........................................18
Control.Val.............................................18
Controller...............................................9(
Controller .vents....................................8(
Conventions............................................,9
*ata T$es.............................................8(
*eclaration 5tatements...........................!)
dela$.......................................................()
delete......................................................)1
digital audio............................................8!
*""........................................................(1
*"" #unction.........................................8(
doK..................................................1!+ )0
dword...............................................1-+ !(
.ditControl#ill.......................................(,
.ditCo$................................................(,
.ditCo$(0............................................(,
.ditCut...................................................(,
.ditCut(0...............................................(-
.dit*elete(0...........................................(-
.dit#it6mrov.........................................(-
.dit#it6mrov(0.....................................(-
.dit#itTo Time.......................................(-
.dit#itToTime..................................(0+ (8
.dit;rooveOuantiPe...............................(0
.dit;rooveOuantiPe(0...........................(8
.diting....................................................,8
.dit6nterolate..................................(8+ 0)
.dit"ength..............................................(8
.dit"ength(0..........................................(9
.ditPaste...........................................(9+ ,0
.ditPaste(0.............................................(9
.ditOuantiPe...........................................,0
.ditOuantiPe(0.......................................,0
.dit3etrograde.......................................,1
.dit3etrograde(0...................................,1
.dit5lide.................................................,1
.dit5lide(0.............................................,1
.ditTransose.........................................,1
.ditTransose(0.....................................,1
.ditVelocit$5cale...................................,!
.ditVelocit$5cale(0...............................,!
.nd.........................................................!1
.rror handling........................................-1
.rror 8essages...........................................
Attemt to change constant................8-
Cannot load *$namic "ink "ibrar$. . .80
Cannot oen include file....................80
Command is disabled on the menu.....80
*ivide b$ Pero....................................8-
.valuation stack overflow..................80
.%ected closing 'uote......................88
.%ression too comle%.....................88
8iscellaneous error............................88
8ismatched arentheses....................88
8issing one or more closing
arentheses.....................................88
1ot valid in >for.ach.vent? or bod$
e%ression......................................88
2ut of memor$...................................88
Proc does not e%ist in *$namic "ink
"ibrar$...........................................88
Program called >error?........................89
Program called >e%it?..........................80
5$nta% error........................................8-
T$es do not match............................89
=ndef of undefined variable...............89
=nknown rocedure...........................80
=nknown variable..............................89
=ser ressed cancel............................80
Valid onl$ in >for.ach.vent? or bod$
e%ression......................................89
Value out of range..............................80
Variable redefined..............................89
:rong number of arguments..............8-
.vent.Chan.............................................1-
.vent./ind.............................................10
Ton Valkenburgh
.vent.Time.............................................!0
.vents.....................................................1-
.vents marked........................................9(
e%it..........................................................()
.4P3.55621........................................18
#A"5....................................................!1
#ile.%tract..............................................,(
#ile8erge...............................................,(
#ile1ew..................................................,(
#ile2en.................................................,(
#ile5ave..................................................,(
#ile5aveAs.............................................,(
for.ach.vent..........................................!!
format.....................................................!9
#rom.......................................................!1
#unctions................................................!!
getTime..................................................!0
get:ord..................................................!0
;host 6n The 8achine............................81
;8 8ode...............................................90
;oto5earch.............................................,(
;oto5earch1e%t.....................................,,
&A63P61...............................................18
&andling of event se'uences..................1(
&idden tras...........................................0-
ifK.........................................................)9
6mlicit...................................................0)
include..............................................(1+ -0
inde%.......................................................)0
6nut functions.......................................!-
6nut range checking..............................-)
insert.......................................................)0
intK.................................................1,+ !(
6nternal overHrange errors.......................-)
/.7A#T................................................18
/e$aft./e$.............................................18
/e$aft.Val..............................................18
"65P.......................................................11
long...................................................1-+ !(
"736C....................................................18
makeTime.........................................()+ ((
8athematical functions..........................)1
8athematics...........................................-)
8C6........................................................19
8.A59.AT5..................................9)+ 9,
8emor$ 8anagement............................8,
8enu functions.......................................((
8enus.....................................................-,
message..................................................!0
8eter................................................9)+ 9,
8eter declarations..................................9,
8iscellaneous functions.........................()
8usical time functions...........................(!
16".........................................................((
12T......................................................19
1ote.*ur.................................................19
1ote./e$................................................19
1ote.Vel.................................................19
1ow........................................................!1
2nH"ine hel..........................................--
2utut functions.....................................!0
2verHrange Problems..............................-!
Parameters..............................................8(
PATC&...................................................19
Patch.9ank.............................................19
Patch.1um..............................................19
ause......................................................!8
Program skeleton....................................90
Programming..........................................,9
random...................................................))
3ecording 8acros..................................09
3elational functions................................))
3eset#ilter..............................................,!
send86*6...............................................!9
se'uences that arenXt se'uential..............0)
5et#ilter/ind..........................................,!
5et#ilter3ange........................................,)
5ettingsChannelTable.............................,,
5ettings8etronome................................,,
5ettings8idi6n........................................,,
5ettings8idi2ut.....................................,,
5ettings8idiThru...................................,,
5ettings3ecord#ilter...............................,,
5how version..........................................90
string.................................................1-+ !,
switch.....................................................(0
5$nta%.....................................................11
5754...............................................!0+ -(
5754*ATA..........................................!0
T.4T.....................................................!0
Thru........................................................!1
Timebase..........................................!!+ 90
T68.9A5.............................................!1
Tis+ and workHarounds..........................00
TrackActive............................................,-
Track9ank..............................................,-
TrackChan..............................................,-
Track/e$................................................,-
Track1ame.............................................,-
TrackPan................................................,-
TrackPatch..............................................,-
TrackPort................................................,-
Track5elect.............................................,-
TrackTime..............................................,0
TrackVelG..............................................,0
TrackVolume..........................................,0
Ton Valkenburgh
T3=......................................................!!
undef......................................................!,
Variable names.......................................-0
Version.............................................0!+ 9-
V.35621..............................................!!
:AV.....................................................!0
:&.."..................................................!0
:heel.Val..............................................!0
while.......................................................)8
word.................................................1-+ !,
H HK........................................................)!
HK..........................................................)1
LFK........................................................)(
IK..........................................................)!
<K..........................................................)!
<FK........................................................!-
MM.........................................................),
JK........................................................)!
JF..........................................................!-
GK.........................................................)1
GG...........................................................)!
GF...........................................................!-
@K.........................................................)(
@F...........................................................)(
F F..........................................................))
FK.........................................................!,
AK.........................................................),
AF...........................................................),
NNK..........................................................)-

Cakewalk Application Language Programming Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Cakewalk Application Language Programming Guide

Încărcat de

Drepturi de autor:

Formate disponibile

The

Cakewalk Application Language Programming Guide

S-ar putea să vă placă și