File Menu Functions

We will now discuss the FILE menu functions. They work exactly like the corresponding commands as executed from the FILE pull down menu on the tool bar. The main difference is that these functions not only carry out the requested operation, but return a result code of TRUE or FALSE (in other words, 1 or 0) depending on whether or not the operation was successful. This can make for some very "C" like code. I'll explain as we look at the functions.

 

(FileNew "template")

This will clear the project space and load the template file whose name appears in quotes. If no template name is given, the user is prompted to supply one at run time. If the template listed as the argument or supplied by the user cannot be found, or if the operation is canceled by the user, the function should return a FALSE or 0 value and the "Normal" template is loaded instead. If the "Normal" template cannot be found, a blank project space is created with normal properties. Be sure to use only the name of the template and don't embellish it with a drive letter, path or extension. You notice that in the line above I say "should return FALSE". As it turned out with my copies of Cakewalk Pro 3 and Cakewalk Pro Audio 6, 7 and 8, I received a TRUE or 1 return code when the function both failed and worked properly. Take note of this and other odd behavior with several of the other TRACK menu functions especially when used in versions 6 and above.

 

(FileOpen "filename")

This works as you might expect. If there is no file name supplied as an argument, the user is prompted to enter one at run time. Do yourself a favor and use the entire path, drive letter and all, with the file name. Sometimes it will work with just the name depending on what directory CAL is logged onto at the time the instruction is carried out, but to save yourself trouble later, just use the whole path each time you enter a file name for any of these FILE functions. Remember to enclose the entire name in quotes. The result codes work through version 6. A TRUE or 1 is returned if the file is opened and a FALSE or 0 is returned along with the little "Cannot Find or Open File" error box if things go wrong. This can come in handy as an abort trap should CAL fail to locate a file. Here is an example of an auto-abort feature that stops CAL if a file fails to load:

 

(if (== (FileOpen "E:\work\av\midi\intro.wrk") 0) (exit))

If the file is there, then it loads and the "if" condition fails, bypassing the "exit" function and continuing with whatever follows the "if" statement. If the file cannot be loaded, the little error box appears followed by the box confirming the encountering of the "exit" command and CAL stops. In version 7, the function returns TRUE for both success and failure with a file name argument supplied. If no argument is supplied and the user is forced to choose a file from the dialog box, the function returns NIL. The bug for the return codes has been fixed for version 8 so long as the file name is supplied as an argument. If no name is supplied and the dialog box is used to select a file, version 8 still returns NIL for success or failure.

 

(FileSave)

This function has no arguments, but saves the current project using the current path and file name. Under Cakewalk 3, the function returns TRUE for success and FALSE for failure. This allows the trapping of unsuccessful saves in CAL. However, in versions 6 and above, both conditions return NIL, or no result at all. Someplace in between these two versions, this feature was removed from this function.

 

(FileSaveAs "filename")

This saves the project under a new name. Again, be sure to use the entire path for the file name argument. If none is supplied, the user will be prompted for one at run time. In versions 6 and above, if an argument is supplied, the result codes returned are TRUE for success and FALSE for failure. If no argument is supplied and the user must use the traditional "Save As" dialog box, a NIL codes is returned regardless of the outcome. This may also be true in versions 4 and 5, but I have not tested them. In version 3, result codes are returned as expected whether an argument is supplied or not. I have noticed on my system that in version 7 that if you (FileSaveAs) a .WRK file as a MIDI file in any of the 4 MIDI formats, sometimes the file is written with a zero file length. The file is, however, intact and loads and plays fine, just has a zero file length. This can also happen when using the "Save As" feature from the FILE menu. Another thing versions 7 and 8 do when using this function. If you use a file name argument but fail to provide an extension to that file name, CAL will not add one on for you. The resulting file will be saved to disk with no extension. Cakewalk will, however, load the file back in without protest. You just will not be able to see the file listed in the OPEN dialog because Cakewalk will not display files names unless they have an extenuation that Cakewalk recognizes. You will have to key in the file name by memory, but it will load. Using the "Save As" feature of the FILE menu will add a WRK extention to a file name if you don't provide one. Another bug was pointed out to me by Jerry Malcolm, who tells of a flaw in all versions past version 3. If you try to (FileSaveAs) a file and in the argument provide a .MID extension, the file will be saved with that extension but will, in fact, still be formatted as a Cakewalk file and not a standard MIDI file. This has been corrected for version 8.

 

 (FileMerge "filename")

This function, like the menu option of the same name, loads the file name in quotes supplied as the argument into the clipboard where it can be pasted into the current project. When no argument is listed, the usual dialog box is presented for the user to browse for the file. TRUE is returned for a successful load and FALSE is returned in the event the load fails or the user aborts the action. As of version 7, this feature and the companion feature below are no longer supported in the Cakewalk drop-down menu. These CAL functions will still work, but the manual operations have been rendered obsolete through the availability of drag-and-drop file handling combined with the ability to have open more than one project at a time..

 

(FileExtract "filename")

As a complementary action to the above function, this function takes the contents of the clipboard and saves it to the path and file name listed in quotes as the argument. If no argument is supplied, the user is prompted to enter a path and name with the usual dialog box. This function returns a TRUE for a successful save and FALSE for a failure or user abort. In version 6, no result code is returned if no argument is supplied. Version 7 returns proper result codes with or without an argument.

 

Next Topic

Top Of Page