The look and functionality of the CAL editor hasn't changed much from version to version with the exception of one feature known as "bracket kissing" which I will explain later and the addition in version 7 (finely!) of text cut and paste editing functions. Aside from this detail, the following discussion will apply equally for all versions of Cakewalk from 3 through 8.
The CAL editor has been optimized for writing CAL code in two ways. First, the tab key causes the cursor to indent just enough to help keep nested functions looking neat and readable. The indention is only two characters wide so it's possible to have long strings of multiply indented text and still not run off the end of the page. As you use the ENTER key, the cursor will start on the next line at the same indention point as the line just above. This makes entering nested code a breeze. To back up one indention level, just hit the BACKSPACE key once and the cursor will move to the left coming to rest at the previous indention point. This makes it easy to place the closing brackets for functions at the proper indention points that correspond to their opening brackets.
The other optimization is the "bracket kissing" feature I alluded to elsewhere. What this feature does is help the programmer check to see if the closing bracket they are entering corresponds to the expected opening bracket. The way this works is that as a closing bracket is typed in, the editor will briefly scroll up to and highlight the opening bracket that the editor associates with it. If the opening bracket is the one the programmer expected to see, then the code is "in phase" or all of the brackets line up. If the highlighted bracket is one that the programmer didn't expect to see, then the code is "out of phase" and the programmer has either left out or added in too many brackets somewhere in the program. This is a very valuable check-up device, and makes the fact that it was fowled up starting with version 5 and continuing with version 6 a real shame. The problem is that the editor will only highlight an opening bracket if it is visible in the window along with the closing bracket being typed in. The editor will no longer scroll back through the code to display the section where the opening bracket is located if it's out of view. This flaw has been corrected for version 7.
There is an array of buttons at the bottom of the CAL editor screen in versions 3 through 6. The OPEN, SAVE and SAVE AS buttons need no elaboration. They work much the same as for any Windows application. The NEW button clears the editor (you are prompted to save any unsaved work, of course) and displays a default template that consists of an opening "(do" function, an indented "NIL" place holder and a closing bracket. The "NIL" is highlighted blue, meaning that anything entering the editor either from the keyboard or by recording a macro will delete and replace it. Therefore, you can just start typing in your code and it will begin at the first indention point and on the first line directly beneath the "(do". So long as you don't force the cursor beyond it, your code will also stay just above the closing bracket for that opening "(do". The RUN button starts execution of whatever code is present in the editor. The RECORD button is a bit different in that once it is set into motion, it changes into a STOP button. This button starts and stops the Macro recording feature of CAL. More about this in a moment.
In versions 7 and 8, the CAL view has taken on the standard "look" of any Windows 95 text editor. All file and edit operations, including an UNDO feature, are available from the standard drop-down menus at the top of the screen which take on a CAL context when the CAL view has focus (Its title bar is blue). From these menus, you can create a "new" work area, load and save files in the usual manner and access the text editing features. The "Record" "Stop" and "Run" functions are now controlled by a set of transport buttons just above the text window and operate as one would expect. Now for a very important new feature. Just as you can now have multiple workspaces open in versions 7 and 8, you can have multiple CAL programs open too. You must be careful not only which CAL window has focus when you run a program, but also which song has focus. Otherwise, you could end up running the CAL program on the wrong song!
If you want to use a different editor or a word processor to compose CAL programs, use the following settings. Set TAB spacing to .15 inch, set the page left and right margins to .25 each and if you have the option, select an even-spaced font instead of a proportional font. The CAL editor used an even spaced font so doing the same in your alternate editor allows you to see closer to the final result this way. Save your file as "plain text" or "ASCII text" depending on how it's worded, with a .TXT extension. The reason I recommend this is that some word processors, MS Word 97 for instance, will add the .TXT to the file name no matter what. If you try to force a .CAL extension to a program you're writing that you have called, say, LOWNOTE, then instead of getting LOWNOTE.CAL, you'll get LOWNOTE.CAL.TXT which means you'll have to change it anyway. If you're sure your word processor will save a pure text file with a .CAL extension, then go for it! Otherwise, just use .TXT and change it in File Manager or Explorer to .CAL before you attempt to open it in the CAL editor or try to run it from Cakewalk. Also note that the tab spacing can be somewhat goofy after exporting a program from a word processor to the CAL editor due to the nature of formatting word processors use that don't always translate well into plain ASCII text. Be prepared to do some fine tuning once you open such a program in the CAL editor. However, the availability of clip-board editing features and spell checking for the comments in a full blown word processor is worth the inconvenience for users of Cakewalk before 7.
Once the RECORD button in the CAL VIEW window is clicked, many of the mouse and keyboard actions you take involving the Menu toolbar or the Track View will result in the generation of CAL code in the editor workspace. As you have seen from the above discussion of MENU functions, there are many operations in CAL that correlate directly with actions that can be taken from the toolbar. When you click RECORD, the CAL view window disappears and you are placed back in one of the sequencer views. From here, you can carry out normal operations on the sequence oblivious to the fact that CAL is recording some of your actions as program code. This recording will continue until you switch back to the CAL view and click STOP.
What you will see in the editing window as a result of recording is first a comment line declaring "Start of recording" followed by any actions you took that are recordable as CAL functions. After these function statements is another comment line stating "End of recording." All of the arguments for each function will be present in the form of numbers that reflect any data and whatever boxes were checked or in force at the time the menu command was invoked. As recorded, these CAL statements have very limited use outside the specific conditions at the time they were recorded. In order to use these macros to carry out their actions under different conditions, many of the arguments will have to be edited and replaced with variables. Once you're happy with whatever you have recorded and edited, you can save it as a .CAL file and can be run at will like an EDIT menu feature.
As I mentioned earlier, setting up some of the EDIT MENU functions can be a real pain in the butt, especially if the filters are involved. We can save ourselves some major typing by using the Macro record feature to "pre-write" most of the needed code. What we would do is place the cursor at the point in the CAL program code where we want the function to go, then click the "RECORD" button. After doing so, the display will leave the CAL view and go to the last view window you were in. Now select a track with some events in it and set the From and Thru markers to any part of the track containing events, if they aren't already. Go to the EDIT menu and do the following.
For Cakewalk 3, click on the edit feature you want to put in your CAL program and set the check boxes and window values as you might want them. Check "Use Event Filter" if you will need to filter the edit. If you checked "Use Event Filter", you'll be presented with the filter window. Make whatever selections you what CAL to use when your program is run. REMEMBER, the settings you make here will be in force EVERY TIME the program runs so make sure you know what you want the function to do! For any arguments that will eventually be filled in by variables in the program, don't worry what values they are set for now, as those values will be replaced during editing. Click "OK" to complete the operation. After finishing with the edit, go to the EDIT menu and click "UNDO" to repair whatever you just did to your sequence (unless you like what you did and want to keep the change). Now flip back to the CAL view and click the "STOP" button.
For Cakewalk 4 or higher, from the EDIT menu, open the "Select" sub-menu and then the "By Filter" option. Set up your filter even if it is nothing more than clicking the "ALL" button. Now click on the editing feature you wish CAL to run and fill in the boxes and windows as needed. Otherwise, the same rules for the window contents apply as noted for Cakewalk version 3 as discussed above. Afterwards, perform the same UNDO from the edit menu to restore your sequence and then stop the macro recording.
Now you must edit the resulting functions CAL has placed in your program. Replace the numbers in the marker arguments with "From" and "Thru", the variable names you wish to use or the functions that will result in the times you wish to be in effect when the edit runs. Do the same for the values of "min" and "max" as needed for any "SetFilterRange" functions that require them. This also applies if you will be using variables for any of the other arguments.
As we discussed in the section regarding EDIT MENU functions for Cakewalk version 6, a macro-created EditInterpolate function will only work for marker variables "From" equaling 0 and "Thru" equaling "End" regardless of what you change the "From" and "Thru" values to. In other words, the macro will operate on the entire length of the track and cannot be set to operate on only a segment instead, at least not directly. In order to force CAL to recognize values for the markers other than 0 and "End", we must preface the EditInterpolate function with two "dummy" statements (see the section called Tips, Techniques and Work-Arounds under the sub-heading Forcing EditInterpolate To Use Markers for a discussion of this approach). Place these "dummy" statements just before each EditInterpolate function in your program. This will have no effect in versions other than 6, but will activate the necessary marker recognition in version 6 thus assuring portability of your code. Note that it appears that you must use these "dummy" statements for EVERY such function, not just the first.
Also remember that most CAL40 functions need to have the markers set up beforehand and the CAL30 functions require the markers as arguments. Also remember that the CAL30 functions will work in all versions of Cakewalk whereas CAL40 functions will not work in Cakewalk version 3. If you want your code to be backward compatible and you record your macros in version 4 or above, you must rewrite the functions to turn them into CAL30 format. Unfortunately, this may mean it will be easier to write the code by hand and forget about macros.
If you ever enter a bunch of code into the editor and it simply will not run, don't be too alarmed. First of all, you must try to take the error message seriously and attempt to address the offending code. However, if you have followed all of the rules and the code still will not fly, you may have run into one of many hauntings in the CAL editor. See the section called Hidden Traps In The CAL Editor on the Tips, Techniques and Work-Arounds page for details. As far as legitimately issued error messages go, some of the more common ones are, "missing one or more closing parentheses", "expected closing quote", "unknown procedure", "wrong number of arguments", "syntax error" and the infamous "evaluation stack overflow". If you really piss it off, you can end up with a Windows Protection Fault and/or Windows 95 Illegal Operation error which will shut Cakewalk right down and maybe even Windows with it! This is not Cakewalk's fault. If you hose your code so badly that it chokes the system, then you probably deserved it! Cakewalk, properly installed, is very stable under Windows and Windows 95, and this is saying allot considering that Windows 95 isn't exactly the Rock of Gibraltar. As far as the internal CAL errors, these can be dealt with.
The error about the closing quotes is easy to fix. Just hunt through your code until you find a missing set of quote marks. Nothing special about that. The "unknown procedure" and "syntax error" messages can usually be traced to a typo someplace. Perhaps you didn't use a capital letter when you needed to, or there may be a variable without a keyword someplace. Take your time looking for these things. If you're told you have the "wrong number of arguments", then look for an incomplete function. Another cause, believe it or not, can be the failure to indent properly. You should always indent at least one tab space away from the left margin after the opening "(do" no matter what. If you don't, this is one way CAL can express its dissatisfaction with you. If you import your text from a word processor, you might be dealing with hidden characters that will not display on the screen but never the less are seen by CAL at run time. If you can narrow the problem down to a line or two, it pays to just delete them and reenter the code.
An "evaluation stack overflow" is a bit harder to clear. It could even mean scrapping the program all together! This message is an indication that CAL is being asked to juggle too many balls at once. It can result from a statement that is too complex. This can be solved by braking the statement down into a group of simpler nested functions. On the other hand, you may be declaring too many variables. Try to make some of them do double duty or use the "undef" function to clear some variables after they have fulfilled their destinies and then declare some more as needed. If you run too many nests in one function, this will cause it. You can tell if you have done so if you have reached a point where a statement is indented over so far as to be half way across the screen! If you can't reorganize your code to reduce the number of nests in this poor function, you may have to rethink your entire project. Maybe you're asking too much of CAL and you need to create a simpler version of the program.
This brings us to "missing one or more closing parentheses". You might think this would be an easy error to clear, but it's not all the time. A missing parentheses can be very hard to spot. Life is a bit easier using versions where "bracket kissing" works. One can always backspace over a bracket and then re-enter it and see what opening bracket is highlighted. After going back through the code doing this every few lines, the out-of-phase statement will eventually show itself by causing the wrong opening bracket to highlight. Now, it's a bit more of a hassle with versions 5 and 6. This is a good reason to be very diligent in one's indenting. Sometimes the indention level being off is the big clue to where the missing bracket needs to go. What's more, there are times when this error can occur and there be nothing at all wrong with the brackets. Take a look at the example I cite in the Hidden Traps In The CAL Editor section of the Tips, Techniques and Work-Arounds page.