ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / WINDOWS / MISC / CMDP72D.ZIP / CMDPOST.MA$ < prev next >

Wrap

Text File | 1992-02-26 | 213.0 KB | 8,837 lines

Command Post 7.0 User's Manual 31-May-90 For IBM, PC/XT, PC/AT, PS/2 and compatibles Wilson WindowWare 2701 California Ave SW ste 212 Seattle, WA 98116 Orders:(800) 762-8383 Support: (206) 937-9335 Fax: (206) 935-7129 Copyright 1988-1990 by Morrie Wilson. All rights reserved. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Wilson WindowWare. Information in this document is subject to change without notice and does not represent a commitment by Wilson WindowWare. The software described herein is furnished under a license agreement. It is against the law to copy this software under any circumstances except as provided by the license agreement. U.S. Government Restricted Rights Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013. Contractor/manufacturer is Wilson WindowWare/2701 California Ave SW /ste 212/Seattle, WA 98116 Trademarks IBM, PC/XT, PC/AT, and PS/2 are registered trademarks of International Business Machines Corporation. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. Windows is a trademark of Microsoft Corporation. PageMaker is a trademark of Aldus Corporation. PubTech and BatchWorks are registered trademarks of Publishing Technologies, Inc. JELL-O is a registered trademark of General Foods Corporation. Command Post is a trademark of Wilson WindowWare. ii CONTENTS CONTENTS CONTENTS iii INTRODUCTION v System Requirements v About This Manual v Notational Conventions v Acknowledgements vi GETTING STARTED 1 TEN-MINUTE TOUR 3 Selecting and navigating 4 File Management 6 Directory Management 12 Changing the View 14 Housekeeping Functions 16 Edit System Configuration... 20 System Menu Box 21 The Command Post Clock 23 YOUR OWN MENUS 25 What is a Menu File? 25 How to Create a Simple Menu 25 Enhancing Our Menu 26 An Enhancement for Safety 27 The Major Functions 28 Running a Program 28 Getting Info from the User 29 Displaying Information 30 Other Useful Functions 31 COMMAND POST MENU LANGUAGE 35 Menu Structure 35 Menu Items 35 Language Components 36 Constants 36 Identifiers 37 Variables 37 Keywords Are Reserved 38 Operators 38 Precedence and eval order 39 Comments 39 Statements 39 Substitution 40 Language Directives 41 Function Parameters 41 Error Handling 41 iii CONTENTS The Functions & Statements 42 Inputting Information 42 Displaying Information 42 File Management 42 Directory Management 43 Disk Drive Management 43 Window Management 43 Menu Management 44 Program Management 44 String Handling 45 Arithmetic Functions 45 Clipboard Handling 46 System Control 46 CPML FUNCTION REFERENCE 51 Introduction 51 Abs 52 TextBox 128 Version 129 WinClose 132 APPENDIX A Browser 146 APPENDIX B CmdPost and Win 3.0 149 Command Post as Your Shell 149 APPENDIX C Programming Tricks 151 Fun With Filenames 151 Making a Free-Floating Menu 152 Program is Already Running 152 Working With Lists 152 Conditional Branching 153 The Command Post Clock 154 APPENDIX D Predefined Constants 155 APPENDIX E Errors 157 Minor Errors 157 Moderate Errors 157 Fatal Errors 158 Index 160 iv INTRODUCTION INTRODUCTION Command Post 7.0 helps you end some of the drudgery of day-to-day tasks when working in Microsoft Windows. How many times have we tired of changing drives, moving through two subdirectories, finding an executable file from among 43 other filenames, double clicking on it, selecting File/Open, then searching for another directory in the listbox because our document happens to be in a different directory than the program! With Command Post you can automate that knowledge of where to move around the disk, which directories to go to, which files you want to work on, what size you prefer your window to be, and so on. System Requirements Command Post 7.0 requires an IBM PC or compatible with a minimum of 640k memory running Microsoft Windows version 2.03 or higher. About This Manual This manual is divided into five sections: First is Getting Started (pg. 1), where we tell you how to install the program. Then we offer a Ten-Minute Tour of the default File Manager window (pg. 3). Next is an introduction to creating Your Own Menus (pg. 25), after which you can start making your own individual routine easier. Then we go into a full description of the Command Post Menu Language (CPML) (pg. 33), and a comprehensive CPML Function Reference (pg. 47) to assist you in making more complex and intelligent menus. Notational Conventions Throughout this manual, we use the following conventions to distinguish elements of text: ALL-CAPS Used for filenames. Boldface Used for important points, programs, function names, and parts of syntax that must appear as shown. System Used for menu names as they appear to the user. Small fixed-width Used for menu program sample code. v INTRODUCTION Acknowledgements Command Post 7.0 designed & written by Morrie Wilson. Additional programming by Michael Davis & Jennifer Palonus. User's Manual designed by Jennifer Palonus. Written by Jennifer Palonus & Morrie Wilson. Our thanks to the many beta-testers for their invaluable comments & suggestions. vi GETTING STARTED GETTING STARTED Command Post is quite easy to install. You will find an appropriate diskette in your Command Post package. Take the diskette and insert it into your floppy drive. The Command Post installation program is itself a Windows application, so make sure Windows is running. If you are in Windows version 2.03 or 2.11: From the MS-DOS Executive, click on the A: or B: drive icon, depending on which floppy drive you used. A directory listing will appear for the Command Post diskette. Doubleclick on the filename INSTALL.EXE. Follow whatever instructions Install gives you. If you are in Windows version 3.0: From the Program Manager, doubleclick on the File Manager icon to run it. When File Manager starts, click on the A: or B: drive icon, depending on which floppy drive you used. A directory tree will appear for the Command Post diskette. You should see a root directory icon. Doubleclick on this icon and a list of filenames will appear. Find the filename INSTALL.EXE and doubleclick on it. Follow whatever instructions Install gives you. Either Version: Install will create the necessary files and place them into a directory it will prompt you for. If Command Post is already run- ning it will close it down it before trying to copy the new program file over the old one. As the installation program finishes it will display the #READ- ME.1ST file. You should take the time to read this file as it contains any late-breaking information about your copy of Command Post. 1 TEN-MINUTE TOUR TEN-MINUTE TOUR Command Post starts up in a window with a listing of the current directory and a menu across the top. All Command Post menus are completely customizable, and defined in a separate "menu file". We've included a default menu file CMDPOST.CPM that creates a menu similar to the Windows 2.x MS-DOS Executive, with some improve- ments. This is what you get if you run Command Post without specifying a menu file. After the default menu, you may see custom menu items that have been defined in a second menu file. Command Post's default menu file calls the file CMDUSER.CPM to get you started: The Command Post window shows your disk drives, the current directory's path, and the filenames and subdirectories in the current directory. 155 TEN-MINUTE TOUR Selecting and navigating Action Mouse Keyboard Click on Type Ctrl + Select a directory icon desired drive Drive with the left letter. button. ________ Click on Use arrow keys Select a desired to place File filename with selection box left button. over desired file. OR: Press first letter of filename to move selection box to next file with that letter. ________ Click on Press the Shift Select additional key while Addn'l filenames with moving Files the left button selection box while pressing over a range of the Shift key. filenames. OR: Click on Press the Ctrl additional key while filenames with moving the right selection box button. over filenames you don't want OR: Drag mouse to select. over a group of additional filenames with the right ________ button pressed. Doubleclick on Place selection Run a desired .EXE box over Program filename. desired program or datafile and OR: press Enter. Doubleclick on datafile name if it has an [extensions] association in WIN.INI 4 TEN-MINUTE TOUR Same as running Same as running Load an a program, a program, Icon except press except press the Shift key Shift+Enter. while clicking ________ the filename. Doubleclick on Place selection Go to a desired subdir- box over Subdirec- ectory name desired tory with the left directory and button. press Enter. ________ Click on Press the Go to a desired Backspace key. Parent directory in Directory the current path string (next to the drive icons) with the left button. 5 TEN-MINUTE TOUR Let's look at the default menu items: File Management Run... Load... These selections launch a pro- gram. Run... starts it as a "normal" window, i.e. not full- screen. Load... starts the program as an icon. In either case a dialog box is displayed asking you for the name of the file you want to start. Whichever file is currently highlight- ed in the directory listing is the default. Browse This menu item runs the Command Post Browser program to view the selected file. This program lets you view the file in a variety of ways. The default is to show the file in Windows' "ANSI text" mode: 6 TEN-MINUTE TOUR Initial Browser View - ANSI Text You can also view the file as "ASCII text", which interprets some special characters differently: Options/ASCII text Browser gives you the ability to filter which lines you view with its Hide & Seek commands. You can hide or show specific lines by entering a word to look for. For instance, the menu item Hide & Seek/Show if... displays this dialog box: ...and (in this example) shows only the lines containing the word "modem": 7 TEN-MINUTE TOUR You can also view a file in hexadecimal format: Options/Hex dump A comprehensive discussion of the Command Post Browser program can be found in Appendix A -- Browser (pg. 142 ). Copy... This menu item lets you copy the selected files to another filename, directory, or drive. A dialog box appears for you to specify the destination pathname. The default is the current directory. 8 TEN-MINUTE TOUR Rename/Move... This selection lets you rename the selected files to another name, or to move them to another directory or drive. If you are moving files you may rename them in the process. Delete File... This menu item lets you delete the selected files. A dialog box will appear to confirm you really want to delete them. Print... This copies the selected file to any standard non-postscript printer. It prompts you for the device to print to. This command is meant to be used with text files only; it doesn't attempt to format the file or otherwise interpret it. 9 TEN-MINUTE TOUR Size of selected files This menu item displays a message box showing you how much space is taken up by the selected files: 10 TEN-MINUTE TOUR Freespace on drives This menu displays a message box showing you how much space is available on your hard drives: Space on A and size of files Space on B and size of files These commands display message boxes showing you how much space is taken up by the selected files vs. how much space is available on your floppy drives: These menu selections are especially useful when you are preparing to copy files to a floppy disk and want to know if you have enough space to receive the files. Extensions... Windows gives you the ability to double-click on a data filename and automatically run a program with it based on the data file's extension. For instance you can doubleclick on a .CRD file and the Cardfile program will pop up and load the file you chose. The "association" between .CRD files and the Cardfile program is stored in the [extensions] section of the WIN.INI file. The File/Extensions... menu displays a dialog box allowing you to add or change the association between the selected file's extension and a program. If you change the association line the new relationship will be recorded in the WIN.INI file. The next time you doubleclick on the file (or any other file with that extension), the associated program will be run with it. This is much simpler than bringing up Notepad and editing the WIN.INI file to change the association. Exit Windows This menu item ends your Windows session. It has the same effect as choosing File/Exit in the MS-DOS Executive screen in Windows version 2.11 or closing the Program Manager in Windows v3.0. 11 TEN-MINUTE TOUR Directory Management Create Directory... This menu item lets you create a subdirectory under the current one: Delete Directory... This menu item lets you delete a subdirectory of the current one: Change Directory... This selection changes the current directory to one you specify: 12 TEN-MINUTE TOUR You can also change directories by doubleclicking on a subdirectory name, clicking on the pathname above the file listing, or pressing backspace to go back up to the parent directory. Format Diskette... This selection formats a diskette in one of your floppy drives by calling the MS-DOS Format program. The first time you choose Format Diskette... after installing Command Post, you are asked what kind of floppy drives your system has. Command Post saves this information in the WIN.INI file for the next time you choose Format Diskette... . 13 TEN-MINUTE TOUR Directory Tree When you select the Dir/Directory Tree menu item, a window is displayed which graphically shows the directory structure of the current drive. You can scroll through the structure, and then click on the directory you want to change to. If you click on a directory with the right button, a whole new Command Post window appears with that directory listed. You can also change the current disk drive by selecting Disks from the directory tree window. Changing the View 14 TEN-MINUTE TOUR Short Long View/Short displays only the filenames, while View/Long also displays the size, and date & time modified. All Partial... Programs These selections determine which filenames are shown. All displays all files in the current directory. Partial... displays a dialog box where you specify one or more wildcarded filenames to show: Selecting Programs shows only those files with an extension of .BAT, .COM, .EXE, or .PIF. By Name, By Date, By Size, By Kind, Unsorted These selections specify how to sort the files in the display. The default is to sort by Name. Sorting by Date shows the most-recently modified files before the older ones. Sorting by Size shows the largest files first. Sorting by Kind displays the files by their extensions. Unsorted produces a list in the same order as you would get from a dir listing in MSDOS. Window Arranging The right column of the View menu contains the window arranging functions. There are four ways Command Post can arrange application windows on the screen for you: 1 Stack 2 Arrange 15 TEN-MINUTE TOUR 3 Arrange in Rows 4 Arrange in Columns Selections 5 through 8 are the same as 1 through 4 except the Command Post window is minimized. When you specify Arrange in Rows and you have more than four open windows, or if you specify Arrange in Columns and there are more than three open windows, Command Post will revert to Arrange. Housekeeping Functions Command Post You can launch a second copy of Command Post while the first is running. This way you can view more than one directory at a time. Also, when you choose File/Copy... or File/Rename/Move..., the destination pathname defaults to the "other" Command Post's directory. Control Panel This selection runs the Windows Control Panel: 16 TEN-MINUTE TOUR Windows 2.11 Control Panel Windows 3.0 Control Panel Clipboard This menu item runs the Windows Clipboard viewer: DOS Prompt This selection runs COMMAND.COM to enable you to work in DOS directly. You can press ALT+ESC to switch back and forth between Windows and DOS, and when you are through using the command-line interface you type "exit" from the DOS prompt to return to Windows. Get Help Cardfile This menu item runs Cardfile with the handy Command Post help file. This gives you a quick reference to all the Command Post Menu Language (CPML) functions and statements. 17 TEN-MINUTE TOUR Reset Options... This menu item lets you change the screen-blanker time, default File/Print... printer device, and installed-disk drive options. System Information This selection shows a message box containing numerous pieces of information about your Windows installation. Program Manager This selection calls up the Windows 3.0 Program Manager. File Manager This selection invokes the Windows 3.0 File Manager. Print Manager This selection runs Windows 3.0 Print Manager. Windows Setup This menu item runs the Windows 3.0 Setup program. This lets you review your current Windows setup configuration and change it if necessary. Edit Command Post Menus This menu item displays a listbox containing all the .CPM files in the current directory: 18 TEN-MINUTE TOUR It then starts the Windows Notepad with the .CPM file you chose: In order to actually use the updated menu file you must select Reload Menu from Command Post's system-box menu. 19 TEN-MINUTE TOUR Edit INI Files This menu item lets you edit a Windows initialization file. If you are using Windows v3.0 you must keep track of multiple .INI files. You will see a listbox containing all the .INI files in the current directory: It then starts the Windows Notepad with the .INI file you chose: If you are running Windows v2.11 there is only one initialization file, WIN.INI, so you will be put directly into Notepad when selecting the menu. Edit System Configuration... This selection runs the Windows 3.0 System Editor. The System Editor allows you to edit the AUTOEXEC.BAT, CONFIG.SYS, WIN.INI, and SYSTEM.INI files. This menu item is disabled if you are running Windows 2.x. 20 TEN-MINUTE TOUR System Menu Box We've made some changes to the system menu box at the upper-left corner of the Command Post window. There are, of course, the standard items: Restore, Move, Size, Minimize, Maximize, Close, (in Windows v3.0) Switch To..., and About Command Post.... In addition we've added: Enter License Info Use this selection to enter your license number and ID when you register your copy of Command Post. Registering brings you wonderful benefits: - Gets rid of that pesky reminder window that comes up every few menu selections. - Entitles you to one hour free telephone support for 90 days. - Gets you the latest version of Command Post. - Gets you your own copy of this manual. - Encourages the authors of this program to continue bringing you new and better products instead of breaking down and getting a real job. Reload Menu This is the selection you must choose after making changes to an active menu file in order to enable the changes. 21 TEN-MINUTE TOUR Exit Windows This is the same as selecting Exit Windows from the File menu. (the second column) The right-hand column of entries contains the names of all the open application windows. You can switch to one of these programs by doubleclicking on its title in the menu. 22 TEN-MINUTE TOUR The Command Post Clock When Command Post starts up you will see a small window in the lower right-hand corner of the screen with the Command Post version number. This window can also act as a digital clock which shows the date, and the time as HH:MM or HH:MM:SS. You can also use the clock to jump back to Command Post if its window is hiding behind something else. Action Mouse Keyboard Click with the Select Change right mouse "CmdPost display button. Clock" from the Command Post system menu's right- hand column. Type a space. Clock's dis- play will toggle from none to HH:MM:SS to HH:MM. Select and Select Close drag slightly. "CmdPost When it is Clock" from inverted, type the Command ALT-F4. Post system menu's right- hand column. Type ALT-F4. Drag with left (not Move mouse button. available) Doubleclick (not Show with the right available) system mouse button. info Doubleclick (not Jump to with the left available) Command button. Post If the Command Post Clock is set to display the time as HH:MM:SS, it will always be visible regardless of any other window at the same location. 23 YOUR OWN MENUS YOUR OWN MENUS The default Command Post menus provide good, basic file-management functions. But the real power in Command Post comes when you add menu items suited to your own needs and preferences. Custom menus are your chance to put Command Post to work in just the way you want. They allow you to change directories and launch applications with just the parameters you need - all from a simple menu choice. You can offer options to the user and save yourself (and others) the task of memorizing your disk layout. There are many possibilities, but we'll start with the simplest and probably most useful task, starting programs, after examining the menu file. What is a Menu File? Menus are defined in ASCII text files (the kind created by Notepad) with the extension .CPM. If you don't specify a .CPM filename when you run Command Post, it uses the default menu file CMDPOST.CPM. You can also bring up another copy of Command Post using a different menu file by double- clicking on any .CPM filename from within Command Post. Every menu file contains menu names which show up on the Command Post menu bar, and menu items in the dropdown menus. For each menu item you'll have one or more lines of commands which Command Post will execute when you choose that item. Your menu will "feel" just like a regular Windows menu, but it will manage things in a way tailored to suit your needs. How to Create a Simple Menu Let's assume you want to keep the default menus Command Post gives you and add your own onto the end of the menu bar. CMDPOST.CPM contains the definitions for the File, Dir, View, and Main menus. It calls another menu file, CMDUSER.CPM, for the custom menus. CMDPOST.CPM contains some very complex programming and is worth taking a look at sometime. For now however let's just stick to modifying CMDUSER.CPM. Using Windows Notepad, open the CMDUSER.CPM file. You can do this by selecting Edit CPM Files from the Main menu. Scroll down to the end of the file. We're going to add a new menu specifically for desktop publishing applications. First off, let's name our new menu. Starting in the first column (at the far left), type: &DTP Apps 25 YOUR OWN MENUS Because it begins in column 1, this entry defines a menu name. The "&" is optional--it defines an Alt-key combination for the entry; Alt-D in this example. It will appear on the Command Post menu bar as "DTP Apps".. Since we intend to use PageMaker for our projects, we'll define a menu item which lets us launch it. On the next line, beginning in the second column (one space in), type: &PageMaker 4.0 Since it begins in column 2, Command Post knows it defines a dropdown menu item. Below this menu item we will enter the commands which let you launch PageMaker. These begin in column 5 or more (or you can tab once). There are almost a hundred functions and commands in the Command Post Menu Language(CPML), but it takes only a few to get started. Well, what did we do to start PageMaker before we had Command Post? We had to make sure we're in the proper drive, find the PageMaker executable file, and doubleclick or run it. We can put those steps in our PageMaker menu with the DirChange and Run functions: &DTP Apps &PageMaker 4.0 DirChange("d:\pm\docs") Run("pm.exe","") DirChange("d:\pm\docs") tells Command Post to change to the D: drive and find the \PM\DOCS subdirectory. Run("pm.exe", "") tells Command Post to launch the PM.EXE application, with no parameters passed to it. Our simple menu is complete. Now save the file and exit Notepad. Then choose Reload Menu from Command Post's system menu box so our new menu will take effect. Enhancing Our Menu Let's imagine that we have a special publishing project ("The Waldorf Salad Cookbook" - should sell millions) that we've been working on over a series of months. It has its own subdirectory, D:\PM\WALDORF, and several PageMaker files - CHPTR1.PM4, CHPTR2.PM4, etc. We would like to have a separate menu item for each chapter so we can start PageMaker with the chapter already loaded. We always use PageMaker at full-screen, so we'd rather not have to press the Maximize box whenever the program starts. Also, we would like to launch the CLIPBRD.EXE utility as an icon, since we check the clipboard often. Let's create the first menu item , which will follow the generic PageMaker 4.0 item we created above. Since this is a submenu item, it starts in column 2: 26 YOUR OWN MENUS PM-&Waldorf DirChange ("d:\pm\waldorf") RunZoom ("pm.exe", "chptr1.pm4") RunIcon ("clipbrd.exe","") Our menu item now does a lot of work for us. The RunZoom command has a new parameter, "chptr1.pm4", which tells PageMaker which file to load when it starts up. The command RunIcon launches the Clipboard viewer as an icon. We could define more menu items for the other chapters, and find ourselves getting to work faster and easier than before. Not to mention helping other people work on the project without getting lost in our particular directory structure. An Enhancement for Safety After spending 45 hours on CHPTR1.PM4, we start to worry a bit about losing our work. We decide to make a diskette backup of our chapter at the beginning of each session. We'll make it a part of the menu! It now looks like this: PM-Waldorf Ch &1 DirChange ("d:\pm\waldorf") ;Backup the current file first... Pause ("Backup Chapter 1","Put Backup disk in Drive A:") FileCopy ("Chptr1.pm4","a:chptr1.pm4",@FALSE) RunZoom ("pm.exe", "chptr1.pm4") RunIcon ("clipbrd.exe","") Our menu changes to the proper directory, and now displays a dialog box with the title "Backup Chapter 1", prompting the user to "Put Backup disk in Drive A:". The Pause function also creates OK and Cancel buttons which let the user get out of the menu item (where did I put that disk???) or continue. If OK is clicked, FileCopy copies the source file CHPTR1.PM4 to the destination A:CHPTR1.PM4. The @FALSE is a CPML constant which specifies that we do not want to prompt the user if the file already exists in the target directory. It's a good idea to put comments in the file when you're trying to accomplish something complex. Comments start with a semicolon; the rest of the line is ignored. This menu item is getting a bit complicated, but look at what we've accomplished. You've automated the backup process, and made it hard to forget. You don't have to memorize all those manual steps, and you don't have to teach them to others. Menus make your life easier, and in this case let you sleep easier too! 27 YOUR OWN MENUS The Major Functions There are almost a hundred functions and commands that make up CPML. But you can create powerful custom menus right away with these eleven: Running a Program You can launch applications in a number of ways: RunIcon (program-name, parameters) Starts a program as an icon at the bottom of the screen. (See pg. 107) Example: &Utilities &Clock RunIcon ("Clock", "") Run (program-name, parameters) Starts a program in a "normal" window. Windows decides where to place the application's window on the screen. (See pg. 105) Example: &Word Processing Edit &MyFile Run ("Notepad", "myfile.txt") RunZoom (program-name, parameters) Starts a program as a full-screen window. (See pg. 108) Example: &Accounting The &BIG spreadsheet RunZoom ("Excel", "bigsheet.xls") 28 YOUR OWN MENUS Getting Information from the User Often you need to have the user enter extra information before you can process a menu request. Here are the simplest ways to do that: AskYesNo (title, question) Displays a dialog box with a given title, posing a question to the user, who may click a Yes, No, or Cancel button. (See pg. 50) Example: &Utilities Delete MyFile... Cont = AskYesNo ("My Menu", "You REALLY want to do this?") Terminate (Cont==@NO, "", "") FileDelete ("MyFile.txt") AskLine (title, prompt, default) Displays a dialog box with a given title, which prompts the user for a line of input. Returns the default if the user just presses the OK button. (See pg. 48) Example: &Word Processing &Edit a file... TheFile = AskLine ("Edit File", "Filename:", CurrentFile()) Run ("Notepad", TheFile) ItemSelect (title, list, delimiter) Displays a listbox filled with items from a list you specify in a string. The items are separated in your string by a delimiter character. Very useful in conjunction with FileItemize, DirItemize, and WinItemize. (See pg. 91) Example: &DTP Apps PM-&Waldorf Project DirChange ("d:\pm\waldorf") WFiles = FileItemize ("chptr*.pm4") TheFile = ItemSelect ("Select A Chapter", WFiles, " ") RunZoom ("pm.exe", TheFile) 29 YOUR OWN MENUS Displaying Information It's easy to display information to the user: Message (title, text) This command displays a message box with a title and text you specify, until the user presses the OK button. (See pg. 97) Example: &Miscellany Show &Date && Time DT = DateTime () Message ("Current Date & Time", "It is now %DT%") Pause (title, text) This command is similar to Message except an exclamation-point icon appears in the message box, and the user can press OK or Cancel. If they press Cancel, the menu item exits. (See pg. 103) Example: &Daily Utilities &Delete .BAK files Pause ("Delete Backups", "Last chance to stop!") ;if it gets this far, they pressed OK... FileDelete ("*.bak") Terminate (expression, title, message) This command stops processing the menu item if the expression is true. If either the title or the message are not null strings (""), then a message box is displayed to alert the user to what has happened. (See pg. 122) Example: &Restricted Operations &Payroll History UsersPW = AskLine ("*RESTRICTED*","Enter your password:","") ;assuming executive's password already saved in WIN.INI: RealPW = IniRead ("MyCompany", "Executive PW", "") Terminate (UsersPW!=RealPW, "ERROR", "Wrong Password!") ;if they got this far, they gave correct password: RunZoom ("Excel.exe", "Personel.xls") 30 YOUR OWN MENUS Other Useful Functions CurrentFile ( ) Returns the name of the selected file (the one with the dotted rectangle around it) from the Command Post window. (See pg. 57) Example: &Editing Run &Notepad with selected file Run ("Notepad", CurrentFile()) DirChange (pathname) Changes the directory to the pathname specified. (See pg. 62) Example: &Miscellany &Run some program not in path DirChange ("c:\some\dir\not\in\path") Run ("Obscure.exe","") 31 COMMAND POST MENU LANGUAGE COMMAND POST MENU LANGUAGE Menu Structure Menus are defined in a menu file. Each menu file consists of one or more lines of menu statements. Each line is terminated with a carriage return / line feed (CRLF) combination and can be up to 256 characters long. There are two main parts of a menu file: The first section, which is optional, is the initialization code. This section is executed once when the menu is first loaded and run. It's located before the first menu item declaration. The remainder of the menu file consists of menu item titles and their associated statements. The code under each menu title is executed when the corresponding menu item is selected. Execution begins at the first statement under a menu item and continues up to the definition of the next item. Menu Items Menu titles can consist of letters, digits, spaces, punctuation marks; in fact any displayable ANSI characters your text editor can create. There are special characters you can use to modify the appearance of items in the menus. & Causes the following character to be underlined in the menu item. The user can select the item by pressing the ALT key with the character instead of using the mouse. | In a main menu, puts this item on a new line. | In a dropdown menu, this item starts a new column. _ Used to create a horizontal bar (in dropdown menus only). Most CPML commands carry out functions based on your menu selections. However there are a few functions (summarized on pg. 42) that can alter the characteristics of the menu titles themselves. For instance you can put a checkmark next to a menu, or disable and gray it. In order to identify a menu item within a CPML statement, each menu item you define has an associated menu name. The menu name is built using only the letters and digits that make up the menu title. Menu names are case-insensitive; you don't have to worry about how the actual menu title is capitalized in order to identify it. 33 COMMAND POST MENU LANGUAGE For menu items in a popup menu, the menu name consists of its parent menu's name, plus the popup menu item's name concatenated at the end. These menu names are valid as soon as the menu file is loaded, so you can use the menu management functions in the initialization code before the menus even appear. Example: PW=AskLine ("","Enter your password:", "") ;assuming the resident guru's pw is already in WIN.INI: RealPW = IniRead ("Our Company", "Tech Guru PW", "") Terminate (PW==RealPW, "Access", "You have FULL access") MenuChange("SystemUtilitiesCleanupDir", @DISABLE) MenuChange("SystemUtilitiesEditBatFiles",@DISABLE) MenuChange("SystemUtilitiesEditWinIni", @DISABLE) Message ("Access", "You have LIMITED access") &System Utilities ;name = "SystemUtilities" &Cleanup Dir ;name = "SystemUtilitiesCleanupDir" ... &Edit BAT Files...;name = "SystemUtilitiesEditBatFiles" ... &Edit WIN.INI ;name = "SystemUtilitiesEditWinIni" ... Language Components The statements you write to execute the menu items are constructed from constants, variables, operators, functions, commands, and comments. Constants The programming language supports both integer and string constants. Integer Constants Integer constants are built from the digits 0 through 9. They can range in magnitude from negative to positive 231 -1 (approximately two billion). Constants larger than these permissible magnitudes will produce unpredictable results. Examples of integer constants: 1 -45 377849 -1999999999 34 COMMAND POST MENU LANGUAGE String Constants String constants are comprised of displayable characters bounded by quote marks. You can use double quotes ("), single quotes ('), or back quotes (`) to enclose a string constant, as long as the same type of quote is used to both start and end it. If you need to imbed the delimiting quote mark inside the string constant, use the delimiting quote mark twice. Examples of string constants: "a" `Betty Boop` "This constant has an imbedded "" mark" 'This constant also has an imbedded " mark' Predefined Constants The programming language has a number of built-in integer constants that can be used for various purposes. These start with the @- sign, and are case-insensitive (although we prefer to use ALL CAPS). Some predefined constants: @FALSE @TILE @NO @TRUE @STACK @YES A list of all the predefined constants can be found in Appendix D: Predefined Constants. Identifiers Identifiers are the names supplied for variables, functions, and commands in your program. An identifier is a sequence of one or more letters or digits that begins with a letter. Identifiers may have up to 30 characters. All identifiers are case insensitive. Upper- and lowercase charac- ters may be mixed at will inside variable names, commands or functions. For example these statements all mean the same thing: AskLine (MyTitle, Prompt, Default) ASKLINE (MYTITLE, PROMPT, DEFAULT) aSkLiNe (MyTiTlE, pRoMpT, dEfAuLt) Variables A variable may contain an integer, a string, or a string representing an integer. Automatic conversions between integers and strings are performed as a matter of course during execution. 35 COMMAND POST MENU LANGUAGE If a function requires a string argument and an integer argument is supplied, the variable will be automatically modified to include the representative string. If a function requires an integer argument and a string argument is supplied, an attempt will be made to convert the string to an inte- ger. If it does not convert successfully, an error will result. Keywords Are Reserved "Keywords" are the predefined identifiers that have special meaning to the programming language. These cannot be used as variable names. CPML keywords consist of the functions, commands, and predefined constants. Some examples of reserved keywords: beep dirchange @Yes filecopy Operators The programming language operators take one operand ("unary operators") or two operands ("binary operators"). Unary operators (integers only): - Arithmetic Negation (Two's complement) + Identity (Unary plus) ~ Bitwise Not. Changes each 0 bit to 1, and vice-versa. ! Logical Not. Produces 0 (@FALSE) if the operand is nonzero, else 1 (@TRUE) if the operand is zero. Binary arithmetic operators (integers only): * Multiplication / Division mod Modulo + Addition - Subtraction << Left Shift >> Right Shift & Bitwise And | Bitwise Or ^ Bitwise Exclusive Or (XOR) && Logical And | | Logical Or Binary relational operators (integers and strings): > Greater-than >= Greater-than or equal 36 COMMAND POST MENU LANGUAGE < Less-than <= Less-than or equal == Equality != or <>Inequality Assignment operator (integers and strings): = Assigns evaluated result of an expression to a variable Precedence and evaluation order The precedence of the operators affect the evaluation of operands in expressions. Operands associated with higher-precedence operators are evaluated before the lower-precedence operators. The table below shows the precedence of the operators. Where operators have the same precedence, they are evaluated from left to right. Operator Description ( ) Parenthetical grouping ~ ! - + Unary operators * / mod Multiplication & Division + - Addition & Subtraction << >> Shift operators < <= == >= > != <> Relational operators & ^ | Bit manipulation operators && | | Logical operators Comments A comment is a sequence of characters that are ignored when processing a menu item. A semicolon (not otherwise part of a string constant) indicates the beginning of a comment. All characters to the right of the semicolon are considered comments and are ignored. Blank lines are also ignored. Examples of comments: ;This is a comment abc=5 ;This is also a comment Statements The statements of a menu specify what to do when the menu item is selected. Assignment Statements Assignment statements are used to set variables to specific or computed values. Variables may be set to integers or strings. 37 COMMAND POST MENU LANGUAGE Examples: a=5 value=Average(a,10,15) location="Northern Hemisphere" World = strcat(location," ","Southern Hemisphere") Control Statements Control statements are generally used to execute system management functions and consist of a call to a command without assigning any return values. Examples: run("clock.exe","") delay(5) winclose("Clock") Exit Substitution The menu language has a powerful substitution feature which inserts the contents of a string variable into a statement before the line is parsed. To substitute the contents of a variable in the statement, simply put a percent-sign (%) on both sides of the variable name. Examples: MyCmd="DirChange('C:\')" ;set MyCmd to a command %MyCmd% ;execute the command ...or consider this one: IniWrite ("PC", "Owner", "Jenny") ... Owner = IniRead ("PC", "Owner", "somebody") message ("", "This is %Owner%'s PC") will produce this message box: To put a single percent-sign (%) on a source line, specify a double percent sign(%%). This is required even inside quoted strings. 38 COMMAND POST MENU LANGUAGE Language Directives A "language directive" is a command to the CPML interpreter, as opposed to a menu statement. These begin with a pound-sign ("#") in column 1. Currently there is only one directive recognized by Command Post: #NextFile. This directive tells the CPML interpreter to append another .CPM file to the current one before building the menus. You can append only one extra menu file in this way. Function Parameters Most of the functions and commands in the language require parameters. These come in three types: Integer String Variable name CPML performs automatic conversions between strings and integers, so in general you can use them interchangeably. Integer parameters may be any of the following: An integer (i.e. 23) A string representing an integer (i.e. "23") A variable containing an integer A variable containing a string representing an integer String parameters may be any of the following: A string An integer A variable containing a string A variable containing an integer Error Handling There are three types of errors that can occur while processing a menu item: Minor, Moderate, and Fatal. What happens when an error occurs depends on the current error mode, which is set with the ErrorMode function. There are three possible modes you can specify: @CANCEL User is notified when any error occurs, and then the menu item is cancelled. This is the default. @NOTIFY User is notified when any error occurs, and has option to continue unless the error is fatal. 39 COMMAND POST MENU LANGUAGE @OFF User is only notified if the error is moderate or fatal. User has option to continue unless the error is fatal. The function LastError returns the code of the most-recent error encountered during the current menu item. Minor errors are numbered from 1000 to 1999. Moderate errors are numbered from 2000 to 2999. Fatal errors are numbered from 3000 to 3999. Error handling is reset to @CANCEL at the start of each menu item. The Functions & Statements Inputting Information AskLine (title, prompt, default) Lets user enter a line of information. AskYesNo (title, question) Lets user choose from Yes, No, or Cancel. ItemSelect (title, list, delimiter) Chooses an item from a listbox. TextBox (title, filename) Fills a listbox from text strings in a file. Displaying Information Beep Beeps at the user. Display (seconds, title, text) Momentarily displays a string. Message (title, text) Displays text in a message box. Pause (title, text) Displays text in a message box. Terminate (expression, title, message) Conditionally ends a menu operation, with a notice if desired. File Management CurrentFile ( ) Returns the selected file or subdirectory name. FileCopy (from-list, to-file, warning) Copies files. 40 COMMAND POST MENU LANGUAGE FileDelete (file-list) Deletes files. FileExist (filename) Determines if a file exists. FileItemize (file-list) Builds a list of files. FileLocate (filename) Finds a file within the current DOS path. FileMove (from-list, to-file, warning) Moves files to another set of pathnames. FileRename (from-list, to-file) Renames files to another set of names. FileSize (file-list) Adds up the total size of a set of files. Directory Management DirChange ([d:]path) Changes the current directory. DirGet ( ) Returns the current directory path. DirHome ( ) Returns the initial directory path. DirItemize (dir-list) Builds a list of directories. DirMake ([d:]path) Creates a new directory. DirRemove ([d:]path) Removes an existing directory. Disk Drive Management DiskFree (drive-list) Returns the amount of free space on a set of drives. LogDisk (drive) Changes the logged disk drive. Window Management WinActivate (partial-windowname) Makes an application window the active window. WinArrange (style) Arranges all running application windows on the screen. 41 COMMAND POST MENU LANGUAGE WinClose (partial-windowname) Closes an application window. WinCloseNot (partial-windowname [, partial-windowname]...) Closes all application windows except those specified. WinGetActive ( ) Gets the title of the active window. WinHide (partial-windowname) Hides an application window. WinIconize (partial-windowname) Turns an application window into an icon. WinItemize ( ) Lists all the main windows currently running. WinPlace (x-ul, y-ul, x-br, y-br, partial-windowname) Changes the size and position of an application window on the screen. WinShow (partial-windowname) Shows a currently-hidden application window. WinTitle (partial-windowname, new-windowname) Changes the title of an application window. WinWaitClose (partial-windowname) Waits until an application window is closed. WinZoom (partial-windowname) Maximizes an application window to full-screen. Menu Management IsMenuChecked (menuitem-name) Determines if a menuitem is checked. IsMenuEnabled (menuitem-name) Determines if a menuitem is enabled. MenuChange (menuitem-name, flags) Modifies displayed characteristics of a menuitem. Program Management Run (program-name, parameters) Runs a program as a normal window. RunHide (program-name, parameters) Runs a program in a hidden window. RunIcon (program-name, parameters) Runs a program as an icon. RunZoom (program-name, parameters) Runs a program in a maximized window. 42 COMMAND POST MENU LANGUAGE String Handling Char2Num (string) Returns the ANSI code of a string's first character. IsNumber (string) Determines if a string represents a valid number. Num2Char (number) Converts a number to the ANSI character it represents. StrCat (string[, string]...) Concatenates strings together. StrCmp (string1, string2) Compares two strings. StrFill (string, string-length) Builds a string from a repeated smaller string. StrFix (base-string, padding-string, length) Pads or truncates a string to a fixed length. StrICmp (string1, string2) Compares two strings, ignoring their case. StrIndex (main-str, sub-str, start, direction) Locates a string within a larger string. StrLen (string) Returns the length of a string StrLower (string) Converts a string to all lower-case characters. StrScan (main-str, delims, start, direction) Finds an occurrence of one or more delimiter characters in a string. StrSub (string, start, length) Returns a substring from within a string. StrTrim (string) Trims leading and trailing blanks from a string. StrUpper (string) Converts a string to all upper-case characters. Arithmetic Functions Abs (number) Returns the absolute value of a number. Average (num [, num]...) Returns the average of a list of integers. Max (num [, num]...) Determines the highest number in a list. 43 COMMAND POST MENU LANGUAGE Min (num [, num]...) Determines the lowest number in a list. Random (max) Generates a positive random number. Clipboard Handling ClipAppend (string) Appends a string to the end of the Clipboard. ClipGet ( ) Returns the Clipboard contents into a string. ClipPut (string) Replaces the Clipboard contents with a string. System Control DateTime ( ) Returns the current date and time. Debug (@ON | @OFF) Turns Debug mode on or off. Delay (seconds) Pauses menu execution. Drop (var [, var]...) Deletes variables to recover their memory. EndSession ( ) Ends the current Windows session. Environment (env-variable) Returns the value of a DOS environment variable. ErrorMode (mode) Sets what happens in the event of an error. Execute statement Directly executes a Command Post statement. Exit Exits the current menuitem's operation. IniRead (section, keyname, default) Reads a string from the win.ini file. IniWrite (section, keyname, string) Writes a string to the win.ini file. IsDefined (variable) Determines if a variable is currently defined. IsRunning ( ) Determines if another copy of Command Post is running. 44 COMMAND POST MENU LANGUAGE LastError ( ) Returns the last error encountered. #NextFile filename Links a second Command Post menu file onto the one invoked. OtherDir ( ) Finds the directory of the "other" running Command Post. OtherUpdate ( ) Updates other running Command Post's display. SetDisplay (detail-level, sort-by, masks) Changes how the Command Post File Manager lists files. Terminate (expression, title, message) Conditionally ends a menu operation, with a notice if desired. Version ( ) Returns the version of Command Post currently running. WinVersion (which-level) Gets the version of Windows that is currently running. Yield Pauses menu processing so other applications can process some messages. 45 CPML FUNCTION REFERENCE CPML FUNCTION REFERENCE Introduction CPML gives you almost a hundred functions and control statements, which we describe in detail in this section. We use a shorthand notation to indicate the syntax of the functions. Function names and other actual characters you type are in boldface. Optional parameters are enclosed in square brackets "[ ]". When a function takes a variable number of parameters, the variable parts will be followed by ellipses ("..."). Take for example string concatenation: StrCat (string[, string]...) This says that the StrCat function takes at least one string parameter. Optionally you can specify more strings to concatenate. If you do, you must separate the strings with commas. For each function and control statement, we show you the Syntax, describe the Parameters (if any), the value it Returns (if any), a description of the function, any nonfatal Errors specific to the function, Example code (shown in courier type), and related functions you may want to See Also. 47 CPML FUNCTION REFERENCE Abs Returns the magnitude of the argument. Syntax: Abs (integer) Parameters: "integer" = integer whose absolute value is desired. Returns: (integer) absolute value of argument. Example: DY=abs(y1-y2) Message("Years","There are %DY% years 'twixt %y1% and %y2%") See Also: Average, Max, Min 48 CPML FUNCTION REFERENCE AskLine Prompts the user for one line of input. Syntax: AskLine (title, prompt, default) Parameters: "title" = title of the dialog box. "prompt" = question to be put to the user. "default" = default answer. Returns: (string) user response. Use this command to query the user for a line of data. The entire user response will be returned if the user presses the OK button or the Enter key. If they press Cancel, the menu item processing is cancelled. Example: Name=AskLine("Dessert","Please enter your name","") Dsrt=AskLine("Dessert","Favorite dessert?","Ice Cream") message(strcat(Name,"'s dessert is "),Dsrt) produces: 49 CPML FUNCTION REFERENCE ...and then, if Jenny types "JELL-O" and presses OK: See Also: AskYesNo, Display, ItemSelect, Message, Pause, TextBox 50 CPML FUNCTION REFERENCE AskYesNo Prompts the user for a YES or NO answer. Syntax: AskYesNo (title, question) Parameters "title" = title of the question box. "question" =question to be put to the user. Returns: (integer) @YES or @NO, depending on the button pressed. This command displays a message box with three pushbuttons - Yes, No, and Cancel. If the user presses Cancel, the current menu item is ended so there is no return value. Example: q=AskYesNo('Testing','Please press "YES"') Terminate(q==@YES,"","") Display(3,'ERROR',"I said press 'YES'") produces: ...and if the user presses No: See Also: AskLine, Display, ItemSelect, Message, Pause, TextBox 51 CPML FUNCTION REFERENCE Average Provides the integer average of the arguments. Syntax: Average (integer [, integer]...) Parameters: "integer" = integers to get the average of. Returns: (integer) average of the arguments. Use this command to compute the average of a series of numbers. This function returns an integer value, so there can be some rounding error involved. Errors: 2060 "Average function syntax error" Example: Ave=Average(1,2,3,4,5,6,7,8,9,10,11,12,13) Message("The average is",Ave) See Also: Abs, Max, Min 52 CPML FUNCTION REFERENCE Beep Beeps once. Syntax: Beep Use this command to produce a short beep, generally to alert the user to an error situation. Example: Beep Pause ("WARNING!!!", "You are about to destroy data!") 53 CPML FUNCTION REFERENCE Char2Num Converts the first character of a string to its numeric equivalent. Syntax: Char2Num (string) Parameters: "string" = any text string. Only the first character will be converted. Returns: (integer) ANSI character code. This function returns the 8-bit ANSI code corresponding to the first character of the string parameter. Note: For the commonly-used characters (with codes below 128), ANSI and ASCII characters are identical. Example: ; Show the hex equivalent of entered character &Programming &ANSI Codes InpChar = AskLine("ANSI Equivalents", "Char:", "") Ansi = strsub(InpChar,1,1) AnsiEquiv = Char2Num(InpChar) Message("ANSI Codes","%Ansi% => %AnsiEquiv%") See Also: Num2Char 54 CPML FUNCTION REFERENCE ClipAppend Appends a string to the Clipboard. Syntax: ClipAppend (string) Parameters: "string" = text string to add to Clipboard. Returns: (integer) @TRUE if string was appended; @FALSE if Clipboard ran out of memory. Use this command to append a string to the Windows Clipboard. The Clipboard must either contain text data or be empty for this command to succeed. Example: ; The code below will append 2 copies of the Clipboard con- ; tents back to the Clipboard, resulting in 3 copies of the ; original contents with a CR/LF between each copy. a=clipget() crlf=strcat(num2char(13),num2char(10)) clipappend(crlf) clipappend(a) clipappend(crlf) clipappend(a) See Also: ClipGet, ClipPut 55 CPML FUNCTION REFERENCE ClipGet Returns the contents of the Clipboard. Syntax: ClipGet ( ) Returns: (string) clipboard contents. Use this command to copy text from the Windows Clipboard into a string variable. Note: If the Clipboard contains an excessively large string a (fatal) out of memory error may occur. Example: ; The code below will convert Clipboard contents to uppercase: clipput(strupper(clipget())) a=clipget() message("UPPERCASE Clipboard Contents",a) See Also: ClipAppend, ClipPut 56 CPML FUNCTION REFERENCE ClipPut Copies a string to the clipboard. Syntax: ClipPut (string) Parameters: "string" = any text string. Returns: (integer) @TRUE if string was copied; @FALSE if clipboard ran out of memory. Use this command to copy a string to the Windows Clipboard. The previous Clipboard contents will be lost. Example: ; The code below will convert Clipboard contents to lowercase: clipput(strlower(clipget())) a = clipget () message("lowercase Clipboard Contents",a) See Also: ClipAppend, ClipGet 57 CPML FUNCTION REFERENCE CurrentFile Returns the selected filename. Syntax: CurrentFile ( ) Returns: (string) currently-selected file's name. When Command Post displays the files in the current directory, one of them is always selected. It's the one with the dotted-line box around it. This is different than a "highlighted" file. When a file is highlighted, it shows up in inverse video (usually white-on-black). To find the filenames that are highlighted, see FileItemize. Example: ; Ask which program to run (default = current file): TheFile = AskLine ("Run It", "Program:", CurrentFile()) Run (TheFile, "") See Also: FileItemize, DirGet, DirItemize 58 CPML FUNCTION REFERENCE DateTime Provides the current Date and time. Syntax: DateTime ( ) Returns: (string) Today's Date and time This function will return the current date and time in a pre- formatted string. The format it is returned in depends on how it is set up in the international section of the WIN.INI file: ddd mm:dd:yy hh:mm:ss XX ddd dd:mm:yy hh:mm:ss XX ddd yy:mm:dd hh:mm:ss XX Where ddd is day of the week (e.g. Mon) mm is the month (e.g. 10) dd is the day of the month (e.g. 23) yy is the year (e.g. 90) hh is the hours mm is the minutes ss is the seconds XX is the Day/Night code (e.g. AM or PM) Note: Windows 3.0 provides even more formatting options than this. The WIN.INI file will be examined to determine which format to use. You can adjust the WIN.INI file via the International section of the Control Panel if the format isn't what you prefer. Example: ; assuming the current standard is U.S. ; (i.e. day dd/mm/yy hh:mm:ss AM): Message("Current Date & Time",DateTime()) would produce: 59 CPML FUNCTION REFERENCE Debug Controls the debug mode. Syntax: Debug (mode) Parameters: "mode" = @ON | @OFF Returns: (integer) Previous Debug mode Use this command to turn the debug mode on or off. The default is @OFF. When Debug mode is on, Command Post will display the command just executed, its result (if any), any error conditions, and the next command to execute. The commands are displayed in a special dialog box. As you can see in the Example section following, the dialog box gives the user four options: Next, Run, Cancel and Show Var. Next executes the next statement and remains in debug mode. Run exits debug mode and runs the rest of the program normally. Cancel terminates the current menu item. Show Var displays the contents of a variable whose name the user entered in the edit box. Example: ; Debug example debug(@on) a = 6 q = askyesno("Testing Debug Mode", "Is the Pope Catholic") debug(@off) b = a + 4 produces: 60 CPML FUNCTION REFERENCE ...then, if the user presses Next: ...and if the user presses Yes: ...etc. (If the user had pressed No it would have said "VALUE=>0".) See Also: ErrorMode, LastError 61 CPML FUNCTION REFERENCE Delay Pauses execution a specified amount of time. Syntax: Delay (seconds) Parameters: "seconds" = number of seconds to delay (2 - 15) Returns: (integer) always @TRUE Seconds must be between 2 and 15. Smaller or larger numbers will be adjusted accordingly. Example: Message("Wait","About 15 seconds") Delay(15) Message("Hi","I'm Baaaaaaack") See Also: Yield 62 CPML FUNCTION REFERENCE DirChange Changes the current directory. Can also log a new drive. Syntax: DirChange ([d:]path) Parameters: "[d:]" = an optional disk drive to log onto. "path" = the desired path. Returns: (integer) @TRUE if directory was changed; @FALSE if the path could not be found. Use this command to change the current working directory to another directory, either on the same or a different disk drive. Errors: 1031 "DirChange: Dir not found/changed" Example: DirChange("c:\") textbox("This is your CONFIG.SYS file", "config.sys") See Also: DirGet, DirHome, LogDisk 63 CPML FUNCTION REFERENCE DirGet Gets the Current Working Directory. Syntax: DirGet ( ) Returns: (string) = Current Working Directory. Use this command to determine which directory we are currently in. It's especially useful when changing drives or directories temporarily. Example: ; Get, then restore current working directory OrigDir=DirGet() DirChange("c:\") FileCopy("config.sys","%OrigDir%xxxtemp.xyz", @FALSE) DirChange(OrigDir) See Also: DirHome, OtherDir 64 CPML FUNCTION REFERENCE DirHome Returns directory containing the Command Post EXE file. Syntax: DirHome ( ) Returns: (string) pathname of the home directory. Use this command to determine the location of CMDPOST.EXE. Example: a=DirHome() Message("Command Post Executable is in ",a) See Also: DirGet, OtherDir 65 CPML FUNCTION REFERENCE DirItemize Returns a space-delimited list of the highlighted directories. Syntax: DirItemize (dir-list) Parameters: "dir-list" =a string containing zero or more subdirectory names, which may be wildcarded. Returns: (string) list of directories. This function compiles a list of subdirectories and separates the names with spaces. Which directory names are itemized depends on the "dir-list" parameter: If it is an empty string, all subdirectories highlighted in the Command Post file manager display are included. If there are any directory names or wildcards in the string, all subdirectories matching the pathnames are included regardless of which ones are highlighted. This is especially useful in conjunction with the ItemSelect function, which enables the user to choose an item from such a space-delimited list. Example: ;Verify directory selection: a=DirItemize("") ItemSelect("Directories", a, " ") See Also: FileItemize, WinItemize, ItemSelect 66 CPML FUNCTION REFERENCE DirMake Creates a new directory. Syntax: DirMake ([d:]path) Parameters: "[d:]" = the desired disk drive. "path" = the path to create. Returns: (integer) @TRUE if the directory was successfully created; @FALSE if it wasn't. Use this command to create a new directory. Errors: 1029 "DirMake: Dir not created" Example: DirMake("c:\XXXSTUFF") See Also: DirRemove 67 CPML FUNCTION REFERENCE DirRemove Removes a directory. Syntax: DirRemove (dir-list) Parameters: "dir-list" =a space-delimited list of directory pathnames. Returns: (integer) @TRUE if the directory was successfully removed; @FALSE if it wasn't. Use this command to delete directories. You can delete one or more at a time by separating directory names with spaces. You cannot, however, use wildcards. Errors: 1030 "DirRemove: Dir not removed" Example: DirRemove("c:\XXXSTUFF") DirRemove("tempdir1 tempdir2 tempdir3") See Also: DirMake 68 CPML FUNCTION REFERENCE DiskFree Finds the total space available on a group of drives. Syntax: DiskFree (drive-list) Parameters: "drive-list" = at least one drive letter, separated by spaces. Returns: (integer) the number of bytes available on all the specified drives. This function takes a string consisting of drive letters, separated by spaces. Only the first character of each non-blank group of characters is used to determine the drives, so you can use just the drive letters, or add a colon (":"), or add a backslash ("\"), or even a whole pathname and still get a perfectly valid result. Example: Size = DiskFree ("c d") Message ("Space Available on C: & D:", Size) See Also: FileSize 69 CPML FUNCTION REFERENCE Display Displays a message to the user for a specified time. Syntax: Display (seconds, title, text) Parameters: "seconds" = integer seconds to display the message (1-15). "title" = Title of the window to be displayed. "text" = Text of the window to be displayed. Returns: (integer) always @TRUE. Use this command to display a message for a few seconds, and then continue with processing without user input. The display box may be prematurely canceled by the user by clicking it with a mouse, or hitting any character. Example: name=askline("Desserts", "Please enter your name", "") dsrt=askline("Desserts", "Favorite dessert?", "Ice Cream") display(3,"%name%'s Dessert", dsrt) ...If Jennifer likes pudding, the display statement produces: See Also: Pause, Message, Terminate 70 CPML FUNCTION REFERENCE Drop Removes variables from memory. Syntax: Drop (var, [var]...) Parameters: var = variable names to remove. Returns: (integer) @TRUE. This function removes variables from the language processor's variable list, and recovers the memory associated with the variable (and possibly related string storage). Example: A="A variable" B="Another one" Drop(A,B) ; This removes A and B from memory 71 CPML FUNCTION REFERENCE EndSession Ends the Windows session. Syntax: EndSession ( ) Use this command to end the Windows session. This command is equivalent to closing the MS-DOS Executive window in Windows v2.x, or the Program Manager window in Windows v3.0. Example: &Utilities E&xit Windows Sure = AskYesNo ("End Session", "You SURE you want to exit Windows?") Terminate (Sure==@No, "", "Exit Windows cancelled") EndSession () See Also: Exit, Terminate, WinClose, WinCloseNot 72 CPML FUNCTION REFERENCE Environment Gets a DOS environment variable. Syntax: Environment (env-variable) Parameters: "env-variable" = any defined environment variable. Returns: (string) environment variable contents. Use this command to query the DOS environment. Example: &MsDos Utilities Display &Path ;Display the PATH for this DOS session... CurrPath=Environment("PATH") Message ("Current DOS Path", CurrPath) See Also: IniRead, Version, WinVersion 73 CPML FUNCTION REFERENCE ErrorMode Specifies how to handle errors. Syntax: ErrorMode (mode) Parameters: "mode" = @CANCEL, @NOTIFY, or @OFF. Returns: (integer) previous error setting. Use this command to control the effects of runtime errors. The default is @CANCEL, meaning the execution of the menu item will be cancelled for any error. @CANCEL: All runtime errors will cause execution to be cancelled. The user will be notified which error occurred. @NOTIFY: All runtime errors will be reported to the user, and they can choose to continue if it isn't fatal. @OFF: Minor runtime errors will be suppressed. Moderate and fatal errors will be reported to the user. User has the option of continuing if the error is not fatal. In general we suggest the normal state of the program should be ErrorMode(@CANCEL), especially if you are writing a menu for others to use. You can always suppress errors you expect will occur and then re-enable ErrorMode (@CANCEL). Example: ; Delete xxxtest.xyz. ; If file doesn't exist, continue execution; don't stop: PrevErrMode=ErrorMode(@off) FileDelete("c:\xxxtest.xyz") ErrorMode(PrevErrMode) See Also: Debug, LastError 74 CPML FUNCTION REFERENCE Execute Executes a statement in a protected environment. Any errors encountered are recoverable. Syntax: Execute statement Parameters: "statement" = is (hopefully) an executable statement. Use this command to execute computed or user-entered statements. Due to the built-in error recovery associated with the Execute statement, it is ideal for interactive execution of user-entered commands. Note the Execute statement doesn't operate on a string per se, but rather on a direct statement. If you want to put a code segment into a string variable you must use the substitution feature of the language, as in the example below. Example: CPMLCmd="" ;in autoexec section in beginning . . . &System CP Menu Language Interactive CPMLCmd=AskLine("CPML Interactive","Command:",CPMLCmd) execute %CPMLCmd% 75 CPML FUNCTION REFERENCE Exit Terminates the menu item being interpreted. Syntax: Exit Use this command to prematurely exit a menu process. An exit is implied at the end of each menu item. Example: a = 100 message("The value of a is",a) exit See Also: Pause 76 CPML FUNCTION REFERENCE FileCopy Copies files. Syntax: FileCopy (source-list, destination, warning) Parameters: "source-list" = a string containing one or more filenames, which may be wildcarded. "destination" = target file name. "warning" = @TRUE if you want a warning before overwriting existing files; @FALSE if no warning desired. Returns: (integer) @TRUE if all files were copied successfully; @FALSE if at least one file wasn't copied. Use this command to copy an individual file, a group of files using wildcards, or several groups of files by separating the names with spaces. You can also copy files to any COM or LPT device. "Source-list" may contain * and ? wildcards. "Destination" may contain the * wildcard only. Errors: 1006 "File Copy/Move: No matching files found" 2002 "File Copy/Move: 'From' file illegal" 2003 "File Copy/Move: 'To' file illegal" 2004 "File Copy/Move: Cannot copy/move wildcards into fixed root" 2005 "File Copy/Move: Cannot copy/move wildcards into fixed extension" 3118 "FileCopyMove: Destination file same as source" Examples: FileCopy("c:\config.sys","d:", @FALSE) FileCopy("c:\*.sys","d:devices\*.sys", @TRUE) FileCopy("c:\config.sys","LPT1:", @FALSE) See Also: FileDelete, FileExist, FileLocate, FileMove, FileRename 77 CPML FUNCTION REFERENCE FileDelete Deletes files. Syntax: FileDelete (file-list) Parameters: "file-list" = a string containing one or more filenames, which may be wildcarded. Returns: (integer) @TRUE if all the files were deleted; @FALSE if a file didn't exist or is marked with the READ-ONLY attribute. Use this command to delete an individual file, a group of files using wildcards, or several groups of files by separating the names with spaces. Errors: 1017 "File Delete: No matching files found" 1018 "File Delete: Delete Failed" 2016 "File Delete: File name illegal" Example: WasDeleted = FileDelete ("BadFile") See Also: FileExist, FileLocate, FileMove, FileRename 78 CPML FUNCTION REFERENCE FileExist Tests for the existence of files. Syntax: FileExist (filename) Parameters: "filename" =either a fully qualified filename with drive and path, or just a filename and extension. Returns: (integer) @YES if the file exists; @NO if it doesn't or if the pathname is invalid. This statement is used to test whether or not a specified file exists. If a fully qualified file name is used only the specified drive and directory will be checked for the desired file. If only the root and extension are specified, then all the directories in the DOS PATH statement will be searched for the desired file. Example: ; check for file in current directory Fex=FileExist(strcat(DirGet(),"myfile.txt")) Tex=substr("NOT",1,strlen("NOT")*Fex) Message("MyFile.Txt"," Is %Tex%in the current directory") ; check for file in someplace along path Fex=FileExist("myfile.txt") Tex=substr("NOT",1,strlen("NOT")*Fex) Message("MyFile.Txt"," Is %Tex% in the DOS path") See Also: FileLocate 79 CPML FUNCTION REFERENCE FileItemize Returns a space-delimited list of files. Syntax: FileItemize (file-list) Parameters: "file-list" = a string containing zero or more filenames, which may be wildcarded. Returns: (string) space-delimited list of files. This function compiles a list of filenames and separates the names with spaces. Which filenames are itemized depends on the "file-list" parameter: If it is an empty string, all filenames highlighted in the Command Post file manager display are included. If there are any filenames or wildcards in the string, all files matching the filenames are included regardless of which ones are highlighted. This is especially useful in conjunction with the ItemSelect function, which enables the user to choose an item from such a space-delimited list. Examples: &Edit INI files ;Get which .INI file to edit (meaningful in Win 3.0 only): IFiles= FileItemize("c:\windows\*.ini") IFile = ItemSelect(".INI Files",IFiles, " ") RunZoom ("Notepad", IFile) Drop (IFiles, IFile) See Also: DirItemize, WinItemize, ItemSelect 80 CPML FUNCTION REFERENCE FileLocate Finds file in current directory or along the DOS PATH. Syntax: FileLocate (filename) Parameters: "filename" =root name, ".", and an extension. Returns: (string) fully qualified path name. This function is used to obtain the fully qualified path name of a file. The current directory is checked first, and if the file is not found the DOS path is searched. This function returns the first occurrence of the file. Example: Edit &WIN.INI winini=FileLocate("win.ini") Terminate(winini=="","???","WIN.INI not found") Run("notepad.exe",winini) Exit See Also: FileExist 81 CPML FUNCTION REFERENCE FileMove Moves files. Syntax: FileMove (source-list, destination, warning) Parameters: "source-list" = one or more filenames separated by spaces. "destination" = target filename. "warning" = @TRUE if you want a warning before overwriting existing files; @FALSE if no warning desired. Returns: (integer) @TRUE if the file was moved; @FALSE if the source file was not found or had the READ-ONLY attribute, or the target filename is invalid. Use this command to move an individual file, a group of files using wildcards, or several groups of files by separating the names with spaces. You can also move files to another drive, or to any COM or LPT device. "Source-list" may contain * and ? wildcards. "Destination" may contain the * wildcard only. Errors: 1006 "File Copy/Move: No matching files found" 2002 "File Copy/Move: 'From' file illegal" 2003 "File Copy/Move: 'To' file illegal" 2004 "File Copy/Move: Cannot copy/move wildcards into fixed root" 2005 "File Copy/Move: Cannot copy/move wildcards into fixed extension" 2007 "File Move: Unable to rename source file" 2015 "File Move: Unable to remove source file" Example: FileMove("c:\config.sys","d:", @FALSE) FileMove("c:\*.sys","d:*.sys", @TRUE) See Also: FileCopy, FileDelete, FileExist, FileLocate, FileRename 82 CPML FUNCTION REFERENCE FileRename Renames files. Syntax: FileRename (source-list, destination) Parameters: "source-list" = one or more filenames separated by spaces. "destination" = target filename. Returns: (integer) @TRUE if the file was renamed; @FALSE if the source file was not found or had the READ-ONLY attribute, or the target filename is invalid. Use this command to rename an individual file, a group of files using wildcards, or several groups of files by separating the names with spaces. Note: Unlike FileMove, you cannot make a file change its resident disk drive with FileRename. "Source-list" may contain * and ? wildcards. "Destination" may contain the * wildcard only. Errors: 1024 "File Rename: No matching files found" 1025 "File Rename: Rename failed" 2019 "File Rename: 'From' file illegal" 2020 "File Rename: 'To' file illegal" 2021 "File Rename: Attempt to rename across drive boundary. - Use MOVE instead." 2022 "File Rename: Cannot rename wildcards into a fixed filename root" 2023 "File Rename: Cannot rename wildcards into a fixed filename extension" Example: FileRename("c:\config.sys","config.old") FileRename("c:\*.txt","*.bak") See Also: FileCopy, FileExist, FileLocate, FileMove 83 CPML FUNCTION REFERENCE FileSize Finds the total size of a group of files. Syntax: FileSize (file-list) Parameters: "file-list" = zero or more filenames, separated by spaces. Returns: (integer) total bytes taken up by the specified files. This function returns the total size of the specified files. Note it doesn't handle wildcarded filenames. You can, however, use FileItemize on a wildcarded filename and use the resulting string with as a FileSize parameter. Errors: 3112 "FileSize: File Not Found" Example: Size = FileSize (FileItemize("")) Message ("Size of Highlighted Files", Size) See Also: DiskFree 84 CPML FUNCTION REFERENCE IniRead Reads data from the WIN.INI file. Syntax: IniRead (section, keyname, default) Parameters: "section" = the major heading to read the data from. "keyname = the name of the item to read. "default" = string to return if the desired item is not found. Returns: (string) data from WIN.INI file. This command allows a program to read data from the WIN.INI file. The WIN.INI file has the form: [section] keyname=settings Most of the entries in WIN.INI are set from the Windows Control Panel program, but individual applications can also use it to store option settings in their own sections. Example: ;Find the default output device: a=IniRead("windows","device","No Default") Message("Default Output Device",a) See Also: Environment, IniWrite 85 CPML FUNCTION REFERENCE IniWrite Writes data to the WIN.INI file. Syntax: IniWrite (section, keyname, data) Parameters: "section" = major heading to write the data to. "keyname = name of the data item to write. "data" = string to write to the WIN.INI file. Returns: (integer) always @TRUE. This command allows a program to write data to the WIN.INI file. The "section" is added to the file if it doesn't already exist. Example: &WIN.INI Stuff Modify &LOAD= line ;Change the list of pgms to load upon Windows startup: LoadProgs = IniRead("windows","load","") NewProgs=AskLine("Add Pgm To LOAD= Line", "Add:", LoadProgs) IniWrite("windows","load",NewProgs) See Also: IniRead 86 CPML FUNCTION REFERENCE IsDefined Determines if a variable name is currently defined. Syntax: IsDefined (var) Parameters: "var" = a variable name. Returns: (integer) @YES if the variable is currently defined; @NO if it was never defined or has been dropped. A variable is defined the first time it appears at the left of an equal sign in a statement. It stays defined until it is explicitly Dropped. Example: Def = IsDefined (ThisVar) Terminate (Def==@FALSE, "ERROR!", "Variable not defined") See Also: Drop 87 CPML FUNCTION REFERENCE IsMenuChecked Determines if a menuitem has a checkmark next to it. Syntax: IsMenuChecked (menuname) Parameters: "menuname" =name of the menu item to test. Returns: (integer) @YES if the menuitem has a checkmark; @NO if it doesn't. You can place a checkmark next to a menu item with the MenuChange command, to indicate an option has been enabled. This function lets you determine if the menu item has already been checked or not. Example: ;Assume we've defined a "Misc./Prompt Often" menuitem... Prompt = IsMenuChecked ("MiscPromptOften") IfPrompt = substr(";",1,(Prompt==@FALSE)) execute %IfPrompt% Confirm = AskYesNo ("???", "Do you REALLY want to do this?") execute %IfPrompt% Terminate (Confirm!=@YES, "", "") ;some risky operation the user has just confirmed they want ;to carry out... See Also: IsMenuEnabled, MenuChange 88 CPML FUNCTION REFERENCE IsMenuEnabled Determines if a menuitem has been enabled. Syntax: IsMenuEnabled (menuname) Parameters: "menuname" =name of the menu item to test. Returns: (integer) @YES if the menuitem is enabled; @NO if it is disabled & grayed. You can disable a menu item with the MenuChange command if you want to prevent the user from choosing it. It shows up on the screen as a grayed item. IsMenuEnabled lets you determine if the menu item is currently enabled or not. Example: ;Allow editing of autoexec.bat file only if choice enabled Terminate (!IsMenuEnabled("UtilitiesEditBatFile"), "", "") Run ("Notepad.exe", "c:\autoexec.bat") See Also: IsMenuChecked, MenuChange 89 CPML FUNCTION REFERENCE IsNumber Determines whether a variable contains a valid number. Syntax: IsNumber (string) Parameters: "string" = string to test to see if it represents a valid number. Returns: (integer) @YES if it contains a valid number; @NO if it doesn't. This function determines if a string variable contains a valid integer. Useful for checking user input prior to using it in computations. Example: a = AskLine("ISNUMBER","Enter a number","0") Terminate(!IsNumber(a),"", "You didn't enter a number") See Also: Abs, Char2Num 90 CPML FUNCTION REFERENCE IsRunning Determines if another copy of Command Post is currently running. Syntax: IsRunning ( ) Returns: (integer) @YES if another copy of Command Post is running; @NO if this is the only one. There is no artificial restraint on the number of copies of Command Post you may run at once. Example: a=!(IsRunning()) Is = strsub("not ", 1, 4*a) Message ("", "Another Command Post is %Is% running.") Drop (a, Is) See Also: OtherDir, OtherUpdate 91 CPML FUNCTION REFERENCE ItemSelect Allows the user to choose an item from a listbox. Syntax: ItemSelect (title, list, delimiter) Parameters: "title" = the title of dialog box to display. "list" = a string containing a list of items to choose from. "delimiter" = a string containing the character to act as delimiter between items in the list. Returns: (string) the selected item. This function displays a dialog box with a listbox inside. This listbox is filled with a list of items taken from a string you provide to the function. Each item in the string must be separated ("delimited") by a character, which you also pass to the function. The user selects one of the items by either doubleclicking on it, or single-clicking and pressing OK. The item is returned as a string. If you create the list with the FileItemize or DirItemize functions you will be using a space-delimited list. WinItemize, however, creates a tab-delimited list of window titles since titles can have embedded blanks. Example: &Graphics &PC Paintbrush Files = FileItemize("*.bmp") TheFile = ItemSelect("Bitmap Files",Files, " ") Run("pbrush.exe", TheFile) would produce (depending on what's in the current directory): 92 CPML FUNCTION REFERENCE See Also: AskYesNo, Display, DirItemize, FileItemize, WinItemize, Message, Pause, TextBox 93 CPML FUNCTION REFERENCE LastError Returns the most-recent error encountered during the current menu item. Syntax: LastError ( ) Returns: (integer) most-recent CPML error code encountered. CPML errors are numbered according to their severity. "Minor" errors go from 1000 through 1999. Moderate errors are 2000 through 2999. Fatal errors are numbered 3000 to 3999. Depending on which error mode is active when an error occurs, you may not get a chance to check the error code. See ErrorMode for a discussion of default error handling. Don't bother checking for "fatal" error codes. When a fatal error occurs, the menu item is cancelled before the next CPML statement gets to execute (regardless of which error mode is active). Calling LastError itself resets the last error indicator back to zero. A full listing of possible errors you can encounter in processing a menu item is in Appendix E - Errors. Example: ErrorMode (@OFF) FileCopy ("Data.dat", "c:\backups", @FALSE) ErrorMode (@CANCEL) Terminate (LastError()==1006,"Error","Please call Tech Support at 555-9999.") See Also: Debug, ErrorMode 94 CPML FUNCTION REFERENCE LogDisk Logs (activates) a disk drive. Syntax: LogDisk (drive-letter) Parameters: "drive-letter" = is the disk drive to log into. Returns: (integer) @TRUE if the current drive was changed; @FALSE if the drive doesn't exist. Use this command to change the logged disk drive. This command produces the same effect as if you typed the drive name from the DOS command prompt. Errors: 1028 "LogDisk: Requested drive not online" Example: logdisk("c:") See Also: DirChange 95 CPML FUNCTION REFERENCE Max Returns largest number in a list of numbers. Syntax: Max (integer [, integer]...) Parameters: "integer" = number. Returns: (integer) largest parameter. Use this function to determine the largest of a set of numbers. Example: a=Max(5, -37, 125, 34, 2345, -32767) Message("Largest number is",a) See Also: Abs, Average, Min 96 CPML FUNCTION REFERENCE MenuChange Checks, unchecks, enables, or disables a menu item. Syntax: MenuChange (menuname, flags) Parameters: "menuname" =menu item whose status you wish to change. "flags" = @CHECK, @UNCHECK, @ENABLE, or @DISABLE. Returns: (integer) always @TRUE. There are currently two ways you can modify a menu item: You can check and uncheck the item to imply that it corresponds to an option that can be turned on or off. You can temporarily disable the item (it shows up as gray) and later re-enable it. The two sets of flags (@Check/@UnCheck and @Enable/@Disable) can be combined in one function call by using the | (or) operator. Example: MenuChange (FilePrint, @Disable) MenuChange (WPWrite, @Enable|@Check) See Also: IsMenuChecked, IsMenuEnabled 97 CPML FUNCTION REFERENCE Message Displays a message to the user. Syntax: Message (title, text) Parameters: "title" = title of the message box. "text" = text to display in the message box. Returns: (integer) always @TRUE. Use this command to display a message to the user. The user must respond by selecting the OK button before processing will continue. Example: Message("GUESSIT","Pick a number between one and 100") Message("GUESSIT","Multiply your number by 2") Message("GUESSIT","Add 34") Message("GUESSIT","Divide by 2") Message("GUESSIT","Subtract your original number") Message("GUESSIT","Your answer is 17") produces: See Also: Display, Pause, Terminate 98 CPML FUNCTION REFERENCE Min Returns lowest number in a list of numbers. Syntax: Min (integer [, integer]...) Parameters: "integer" = any integer number. Returns: (integer) lowest parameter. Use this function to determine the lowest of a set of integers. Example: a=Min( 5, -37, 125, 34, 2345, -32767) Message("Smallest number is",a) See Also: Abs, Average, Max 99 CPML FUNCTION REFERENCE #NextFile Syntax: #NextFile filename The #NextFile directive tells the CPML interpreter to append another.CPM file to the current one before building the menus. In this manner you can build a common menu for a group of users, for example, and include a #NextFile directive to allow each user to customize part of their menus to suit their individual needs. The default menu file CMDPOST.CPM calls the default user menu CMDUSER.CPM in just this way. #NextFile should appear only once in a menu file, as CPML only acts upon the first one it sees. Also, you can only link one user menu in this manner. Example: ;(beginning of CMDPOST.CPM file) ;changed this directive to point to my own menu file ;instead of the default "cmduser.cpm": #NextFile MyOwn.cpm . . . 100 CPML FUNCTION REFERENCE Num2Char Converts a number to its character equivalent. Syntax: Num2Char (integer) Parameters: "number" = any number from 0 to 255. Returns: (string) one-byte string containing the character the number represents. Use this command to convert a number to its ASCII equivalent. Example: ; Build a variable containing a CRLF combo crlf=strcat(num2char(13),num2char(10)) message("NUM2CHAR",strcat("line1",crlf,"line2")) See Also: Char2Num 101 CPML FUNCTION REFERENCE OtherDir Finds the directory where the other copy of Command Post is running, if any. Syntax: OtherDir ( ) Parameters: "string" = pathname to "other" directory. Returns: (string) the directory of the second-most recently used Command Post window. The current window is considered the most recently used directory. Use this command to determine directory of the other Command Post window. Useful in setting up copy and move operations between two Command Post copies. Example: a=DirGet() b=OtherDir() Message("Directory of this CmdPost window is",a) Message("Directory of the other CmdPost window is",b) See Also: DirGet, DirHome, OtherUpdate 102 CPML FUNCTION REFERENCE OtherUpdate Updates another Command Post directory display. Syntax: OtherUpdate ( ) Returns: (integer) @TRUE if another copy of Command Post was found to update; @FALSE if this is the only copy running. This command updates the File Manager display of the next-most recently invoked copy of Command Post. This is useful if your menu item changes a directory; i.e. if a file or directory is created, moved, renamed, or deleted. OtherUpdate helps ensure the other Command Post display immediately reflects the change the user caused from this copy. Example: FileCopy ("MyFile.txt", OtherDir(), @FALSE) OtherUpdate () See Also: OtherDir, SetDisplay 103 CPML FUNCTION REFERENCE Pause Provides a message to user. User may cancel processing. Syntax: Pause (title, text) Parameters: "title" = title of pause box. "text" = text of the message to be displayed. Returns: (integer) always @TRUE. This command displays a message to the user with an exclamation point icon. The user may respond by selecting the OK button, or they may cancel the processing by selecting CANCEL. The Pause command is similar to the Message command except for the addition of the CANCEL button and icon. Example: Pause("Change Disks","Insert new disk into Drive A:") produces: See Also: Display, Message, Terminate 104 CPML FUNCTION REFERENCE Random Computes a pseudo-random number. Syntax: Random (max) Parameters: "max" = largest desired number. Returns: (integer) unpredictable positive number. This function will return a random integer between 0 and "max". Example: a = Random(79) Message("Random number between 0 and 79",a) 105 CPML FUNCTION REFERENCE Run Runs a program as a normal window. Syntax: Run (program-name, parameters) Parameters: "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT file, or a data file. "parameters" = optional parameters as required by the applica- tion. Returns: (integer) @TRUE if the program was found; @FALSE if it wasn't. Use this command to run an application. If the drive and path are not part of the program name, the current directory will be examined first and then the DOS path will be searched to find the desired executable file. If the "program-name" doesn't have an extension of .EXE, .COM, .PIF, or .BAT, it will be run in accordance with whatever is in the [extensions] section of the WIN.INI file. When this happens, any "parameters" you specified are ignored. Examples: Run("Notepad.exe","abc.txt") Run("clock.exe","") Run("paint.exe","pict.msp") See Also: RunHide, RunIcon, RunZoom, WinClose, WinWaitClose 106 CPML FUNCTION REFERENCE RunHide Runs a program as a hidden window. Syntax: RunHide (program-name, parameters) Parameters: "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT file, or a data file. "parameters" = optional parameters as required by the application. Returns: (integer) @TRUE if the program was found; @FALSE if it wasn't. Use this command to run an application as a hidden window. If the drive and path are not part of the program name, the current directory will be examined first and then the DOS path will be searched to find the desired executable file. If the "program-name" doesn't have an extension of .EXE, .COM, .PIF, or .BAT, it will be run in accordance with whatever is in the [extensions] section of the WIN.INI file. When this happens, any "parameters" you specified are ignored. Note: When this command launches an application it informs it that you want it to run as a hidden window. Whether or not the application honors your wish is beyond RunHide's control. Examples: RunHide("Notepad.exe","abc.txt") RunHide("clock.exe","") RunHide("paint.exe","pict.msp") See Also: Run, RunIcon, RunZoom, WinHide, WinClose, WinWaitClose 107 CPML FUNCTION REFERENCE RunIcon Runs a program as an iconic (minimized) window. Syntax: RunIcon (program-name, parameters) Parameters: "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT file, or a data file. "parameters" = optional parameters as required by the application. Returns: (integer) @TRUE if the program was found; @FALSE if it wasn't. Use this command to run an application as an icon. If the drive and path are not part of the program name, the current directory will be examined first and then the DOS path will be searched to find the desired executable file. If the "program-name" doesn't have an extension of .EXE, .COM, .PIF, or .BAT, it will be run in accordance with whatever is in the [extensions] section of the WIN.INI file. When this happens, any "parameters" you specified are ignored. Note: When this command launches an application it merely informs it that you want it to begin as an icon. Whether or not the application honors your wish is beyond RunIcon's control. Examples: RunIcon("Notepad.exe","abc.txt") RunIcon("clock.exe","") RunIcon("paint.exe","pict.msp") See Also: Run, RunHide, RunZoom, WinIconize, WinClose, WinWaitClose 108 CPML FUNCTION REFERENCE RunZoom Runs a program as a full-screen (maximized) window. Syntax: RunZoom (program-name, parameters) Parameters: "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT file, or a data file. "parameters" = optional parameters as required by the application. Returns: (integer) @TRUE if the program was found; @FALSE if it wasn't. Use this command to run an application as a full-screen window. If the drive and path are not part of the program name, the current directory will be examined first and then the DOS path will be searched to find the desired executable file. If the "program-name" doesn't have an extension of .EXE, .COM, .PIF, or .BAT, it will be run in accordance with whatever is in the [extensions] section of the WIN.INI file. When this happens, any "parameters" you specified are ignored. Note: When this command launches an application it merely informs it that you want it to be maximized to full-screen. Whether or not the application honors your wish is beyond RunZoom's control. Examples: RunZoom("Notepad.exe","abc.txt") RunZoom("clock.exe","") RunZoom("paint.exe","pict.msp") See Also: Run, RunHide, RunIcon, WinZoom, WinClose, WinWaitClose 109 CPML FUNCTION REFERENCE SetDisplay Controls the display of files in the Command Post File Manager window. Syntax: SetDisplay (detail, sort-by, masks) Parameters: "detail" = level of detail. Use "SHORT" or "LONG". "sort-by" = how to sort the filenames. Use "NAME", "KIND", "SIZE", "DATE" or "UNSORTED". "masks" = list of masks for file display. Returns: (integer) @TRUE if valid options were specified; @FALSE if invalid. Use this command to change and/or update the file display. Any of the fields may be null. If a field is null the previous setting is used. This command will alter the file display Parameters:, and then re-read all the files and update the display. A special form of this command, SETDISPLAY ("","",""), will update the file display without changing any of the previously set Parameters. Errors: 2105 "SetDisplay: Display type not SHORT or LONG" 2106 "SetDisplay: Sort Type not NAME, DATE, SIZE, KIND, or UNSORTED" Example: Windows &SDK &Show SDK Development Files SetDisplay ("","","*.ICO *.CUR *.BMP *.DLG *.H") 110 CPML FUNCTION REFERENCE StrCat Concatenates two or more strings. Syntax: StrCat (string1, string2[, stringN]...) Parameters: "string1", etc = at least two strings you want to "string" together (so to speak). Returns: (string) concatenation of the entire list of input strings. Use this command to stick character strings together, or to format display messages. Errors: 2058 "StrCat function syntax error" Example: User=AskLine("Login", "Your Name:", "") Message("Login",strcat("Hi, ",User)) ;note that this will do the same: Message("Login","Hi, %User%") See Also: StrFill, StrFix, StrTrim 111 CPML FUNCTION REFERENCE StrCmp Compares two strings. Syntax: StrCmp (string1, string2) Parameters: "string1", "string2" = strings to compare. Returns: (integer) -1, 0, or 1; depending on whether string1 is less than, equal to, or greater than string2, respectively. Use this command to determine whether two strings are equal, or which precedes the other in an ASCII sorting sequence. Note: This command has been included for semantic completeness. The relational operators >, >=, ==, !=, <=, and < provide the same capability. Example: a=AskLine("STRCMP","Enter a test line","") b=AskLine("STRCMP","Enter another test line","") c=strcmp(a,b) c=c+1 d=strsub("less than equal to greater than",c*12,12) ;Note that above string is grouped into 12-character chunks. ;Desired chunk is removed with the strsub statement. message("STRCMP","%a% is %d% %b%") See Also: StrICmp, StrIndex, StrLen, StrScan, StrSub 112 CPML FUNCTION REFERENCE StrFill Creates a string filled with a series of characters. Syntax: StrFill (filler, length) Parameters: "filler" = a string to be repeated to create the return string. If the filler string is null, spaces will be used instead. "length" = the length of the desired string. Returns: (string) character string. Use this function to create a string consisting of multiple copies of the filler string concatenated together. Example: Message("My Stars",strfill("*",30)) See Also: StrCat, StrFix, StrLen, StrTrim 113 CPML FUNCTION REFERENCE StrFix Pads or truncates a string to a fixed length. Syntax: StrFix (base-string, pad-string, length) Parameters: "base-string" = string to be adjusted to a fixed length. "pad-string" = appended to "base-string" if needed to fill out the desired length. If "pad-string" is null, spaces are used instead. "length" = length of the desired string. Returns: (string) fixed size string. This function "fixes" the length of a string, either by truncating it on the right, or by appending enough copies of pad-string to achieve the desired length. Example: a=StrFix("Henry"," ",15) b=StrFix("Betty"," ",15) c=StrFix("George"," ",15) Message("Spaced Names",strcat(a,b,c)) See Also: StrFill, StrLen, StrTrim 114 CPML FUNCTION REFERENCE StriCmp Compares two strings without regard to case. Syntax: StrICmp (string1, string2) Parameters: "string1", "string2" =strings to compare. Returns: (integer) -1, 0, or 1; depending on whether string1 is less than, equal to, or greater than string2, respectively. Use this command to determine whether two strings are equal, or which precedes the other in an ACSII sorting sequence, when case is ignored. Example: a=AskLine("STRICMP","Enter a test line","") b=AskLine("STRICMP","Enter another test line","") c=stricmp(a,b) c=c+1 d=strsub("less than equal to greater than",c*12,12) ;Note that above string is grouped into 12-character chunks. ;Desired chunk is removed with the strsub statement. message("STRICMP","%a% is %d% %b%") See Also: StrCmp, StrIndex, StrLen, StrScan, StrSub 115 CPML FUNCTION REFERENCE StrIndex Searches a string for a substring. Syntax: StrIndex (string, sub-string, start, direction) Parameters: "string" = the string to be searched for a substring. "substring" = the string to look for within the main string. "start" = the position in the main string to begin the search. The first character of a string is position 1. "direction" = the search direction. @FWDSCAN searches forward, while @BACKSCAN searches backwards. Returns: (integer) position of "sub-string" within "string"; 0 if not found. This function searches for a substring within a "target" string. Starting at the "start" position, it goes forward or backward depending on the value of the "direction" parameter. It stops when it finds the "substring" within the "target" string, and returns its position. A start position of 0 has special meaning depending on which direction you are scanning. For forward searches zero indicates the search should start at the beginning of the string. For reverse searches zero causes it to start at the end of the string. Errors: 3100 "StrIndex/StrScan 3rd parameter out of bounds" Example: Instr = AskLine ("STRINDEX", "Type a sentence:", "") start=1 end=strindex(InStr," ",start,@FWDSCAN) terminate(end==0,"Sorry...","No spaces found") message("STRINDEX",strcat("The first word is: ", strsub(InStr,start,end-1)) exit See Also: StrLen, StrScan, StrSub 116 CPML FUNCTION REFERENCE StrLen Provides the length of a string. Syntax: StrLen (string) Parameters: "string" = any text string. Returns: (integer) length of string. Use this command to determine the length of a string variable or expression. Example: MyFile=AskLine("Filename","File to process:","") FilenameLen=strlen(MyFile) Terminate(FilenameLen>13, "", "Filename too long!") See Also: StrFill, StrFix, StrIndex, StrScan, StrTrim 117 CPML FUNCTION REFERENCE StrLower Converts a string to lowercase. Syntax: StrLower (string) Parameters: "string" = any text string. Returns: (string) lowercase string. Use this command to convert a text string to lower case. Example: a=AskLine("STRLOWER","Enter text","") b=strlower(a) message(a,b) See Also: StrICmp, StrUpper 118 CPML FUNCTION REFERENCE StrScan Searches string for occurrence of delimiters. Syntax: StrScan (string, delimiters, start, direction) Parameters: "string" = the string that is to be searched. "delimiters" = a string of delimiters to search for within "string". "start" = the position in the main string to begin the search. The first character of a string is position 1. "direction" = the search direction. @FWDSCAN searches forward, while @BACKSCAN searches backwards. Returns: (integer) position of delimiter in string, or 0 if not found. This function searches for delimiters within a target "string". Starting at the "start" position, it goes forward or backward depending on the value of the "direction" parameter. It stops when it finds any one of the characters in the "delimiters" string within the target "string". Errors: 3100 "StrIndex/StrScan 3rd parameter out of bounds" Example: TheStr="123,456.789:abc" start=1 end=strscan(TheStr,",.:",start,@FWDSCAN) terminate(end==0,"Sorry...","No delimiters found") message("The first parameter",strsub( TheStr,start,end-start+1)) exit See Also: StrLen, StrSub 119 CPML FUNCTION REFERENCE StrSub Extracts a substring out of an existing string. Syntax: StrSub (string, start, length) Parameters: "string" = the string from which the substring is to be extracted. "start" = character position within "string" where the sub-string starts. (The first character of the string is at position 1). "length" = length of desired substring. If you specify a length of zero it will return a null string. Returns: (string) substring of parameter string. This function extracts a substring from within a "target" string. Starting at the "start" position, it copies up to "length" characters into the substring. Errors: 3059 "Illegal Bounds for STRSUB function" Example: a="My dog has fleas" animal=strsub(a,4,3) Message("STRSUB","My animal is a %animal%") See Also: StrLen, StrScan 120 CPML FUNCTION REFERENCE StrTrim Removes leading and trailing spaces from a character string. Syntax: StrTrim (string) Parameters: "string" = a string with unwanted spaces at the beginning and/or the end. Returns: (string) string devoid of leading and trailing spaces. Use this function to remove unwanted spaces from the beginning and end of text data. Example: TheFile = AskLine("STRTRIM","Filename ('exit' cancels)","") TstExit = strtrim(strlower(TheFile)) Terminate(TstExit=="exit","Cancelled","...by user request") ;processing of TheFile continues... See Also: StrFill, StrFix, StrLen 121 CPML FUNCTION REFERENCE StrUpper Converts a string to uppercase. Syntax: StrUpper (string) Parameters: "string" = any text string. Returns: (string) uppercase string. Use this function to convert a text string to upper case. Example: a=AskLine("STRUPPER","Enter text","") b=strupper(a) message(a,b) See Also: StrICmp, StrLower 122 CPML FUNCTION REFERENCE Terminate Conditionally ends the menuitem. Syntax: Terminate (expression, title, message) Parameters: "expression" = any logical expression. "title" = the title of a message box to be displayed before termination. "message" = the message in the message box. Returns: (integer) always @TRUE. This command ends processing for the menu item if "expression" is nonzero. Note that many functions return @TRUE (1) or @FALSE (0), which you can use to decide whether to cancel a menu item. If either "title" or "message" contains a string, a message box with a title and a message is displayed before exiting. Examples: ;Unconditional Termination w/o message box. ;Same as "Exit": Terminate(@TRUE,"","") ;Basically a no-op: Terminate(@FALSE,"","This will never terminate") ;Exits with message if a is less than zero: Terminate(a<0,"Error","Cannot use negative numbers") ;Exits w/o message if answer isn't "YES": Terminate(answer!="YES","","") See Also: Display, Pause, Message 123 CPML FUNCTION REFERENCE TextBox Displays a file in a listbox on the screen and returns selected line, if any. Syntax: TextBox (title, filename) Parameters: "title" = listbox title. "filename" =file containing contents of listbox. Returns: (string) = highlighted string, if any. The TextBox command loads a file into a Windows listbox and displays the listbox to the user. The command has two primary uses: First off, it can be used to display multi-line messages to the user. In addition, because of its ability to return a selected line, it may be used as a multiple choice question box. The line highlighted by the user (if any) will be returned to the program. If disk drive and path not are part of the filename, the current directory will be examined first, and then the DOS path will be searched to find the desired file. Example: ;Display config.sys: a=TextBox("Choose a line","C:\CONFIG.SYS") display(3,"Chosen line",a) See Also: ItemSelect 124 CPML FUNCTION REFERENCE Version Returns the version number of the currently-running Command Post language processor. Syntax: Version ( ) Returns: (string) = Command Post version number. Use this function to determine the version of Command Post that is running. It is useful to verify that a menu generated with the latest version of the language will operate properly on what may be a different machine with a different version of Command Post installed. Example: a=Version() See Also: Environment, WinVersion 125 CPML FUNCTION REFERENCE WinActivate Activates a previously running window. Syntax: WinActivate (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be activated. Returns: (integer) @TRUE if a window was found to activate; @FALSE if no windows were found. Use this command to activate windows for user input. Errors: 1045 "WinActivate: Window not found" Example: Run("notepad.exe","") Run("clock.exe","") WinActivate("Notepad") See Also: WinCloseNot, WinGetActive, WinShow 126 CPML FUNCTION REFERENCE WinArrange Arranges, tiles, and/or stacks application windows. Syntax: WinArrange (style) Parameters: style = one of the following: @STACK, @TILE (or @ARRANGE), @ROWS, or @COLUMNS. Returns: (integer) always @TRUE. Use this command to rearrange the open windows on the screen. (Any iconized programs are unaffected.) @STACKED @TILED @ROWS @COLUMNS When you specify @ROWS and you have more than four open windows, or if you specify @COLUMNS and you have more than three open windows, Command Post will revert to @TILE. See Also: WinItemize, WinHide, WinIconize, WinPlace, WinShow, WinZoom 127 CPML FUNCTION REFERENCE WinClose Closes an open window. Syntax: WinClose (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be closed. Returns: (integer) @TRUE if a window was found to close; @FALSE if no windows were found. Use this command to close windows. This command will not close the current Command Post window. You can, however, call EndSession to end the current Windows session. Errors: 1039 "WinClose: Window not found" Example: Run ("notepad.exe","") WinClose("Notepad") See Also: WinCloseNot, WinHide, WinIconize, WinWaitClose 128 CPML FUNCTION REFERENCE WinCloseNot Closes all windows, except those provided as parameters:. Syntax: WinCloseNot (partial-windowname [, partial-windowname]...) Parameters: partial-windowname = either an initial portion of, or an entire window name. Any windows whose titles match the partial names will stay open. Returns: (integer) always @TRUE. Use this command to close all windows except those specifically listed in the parameter strings. At least one partial windowname must be given. A null-string parameter would match all windows, or in other words close nothing. Errors: 2038 "WinCloseNot Function Syntax error" Example: ;The statement below will close all windows except: ;1) MS-DOS Executive (starts with 'MS-D') ;2) Clock (starts with 'Clo' ) WinCloseNot("MS-D","Clo") See Also: WinItemize, WinClose, WinHide, WinIconize, WinWaitClose 129 CPML FUNCTION REFERENCE WinGetActive Gets the title of the active window. Syntax: WinGetActive ( ) Returns: (string) title of active window. Use this command to determine which window is currently active. Example: CurrentWin=WinGetActive() See Also: WinItemize, WinActivate 130 CPML FUNCTION REFERENCE WinHide Hides a window. Syntax: WinHide (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be hidden. Returns: (integer) @TRUE if a window was found to hide; @FALSE if no windows were found. Use this command to hide windows. The programs are still running when they are hidden. A partial-windowname of "" hides the current Command Post window. Errors: 1040 "WinHide: Window not found" Example: Run("notepad.exe","") WinHide("Notepad") WinShow("Notepad") See Also: WinClose, WinIconize, WinPlace 131 CPML FUNCTION REFERENCE WinIconize Iconizes a window. Syntax: WinIconize (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be iconized. Returns: (integer) @TRUE if a window was found to iconize; @FALSE if no windows were found. Use this command to turn a window into an icon at the bottom of the screen. A partial-windowname of "" iconizes the current Command Post window. Errors: 1041 "WinIconize: Window not found" Example: Run("clock.exe","") WinIconize("Clo") ; partial window name used here See Also: WinClose, WinHide, WinPlace, WinShow, WinZoom 132 CPML FUNCTION REFERENCE WinItemize Returns a tab-delimited list of all open windows. Syntax: WinItemize ( ) Returns: (string) list of all open windows' titles. This function compiles a list of all the open application windows' titles and separates the titles by tabs. This is especially useful in conjunction with the ItemSelect function, which enables the user to choose an item from such a tab-delimited list. Note this behaves somewhat differently than FileItemize and DirItemize, which create space-delimited lists. This is because window titles regularly contain embedded spaces. Example: &Windows &Find a window AllWins = WinItemize() HTab = Num2Char(9) MyWind = ItemSelect("Windows",AllWins, HTab) WinActivate(MyWind) See Also: DirItemize, FileItemize, ItemSelect 133 CPML FUNCTION REFERENCE WinPlace Places a window anywhere on the screen. Syntax: WinPlace (x-ulc, y-ulc, x-brc, y-brc, partial-windowname) Parameters: x-ulc = how far from the left of the screen to place the upper- left corner (0-1000). y-ulc = how far from the top of the screen to place the upper- left corner (0-1000). x-brc = how far from the left of the screen to place the bottom-right corner (10-1000) or @NORESIZE. y-brc = how far from the top of the screen to place the bottom- right corner (10-1000) or @NORESIZE or @ABOVEICONS. "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be moved to the new position. Returns: (integer) @TRUE if a window was found to move; @FALSE if no windows were found. Use this command to move windows on the screen. (You cannot, however, move icons or windows that have been maximized to full screen.) A partial-windowname of "" moves the current Command Post window. The "x-ulc", "y-ulc", "x-brc", and "y-brc" parameters are based on a logical screen that is 1000 points wide by 1000 points high. You can move the window without changing the width and/or height by specifying @NORESIZE for the "x-brc" and/or "y-brc" parameters, respectively. You can fix the bottom of the window to sit just above the line of icons along the bottom of the screen by specifying a "y-brc" of @ABOVEICONS. Some sample parameters: Upper left quarter of the screen: 0, 0, 500, 500 Upper right quarter: 500, 0, 500, 1000 Center quarter: 250, 250, 750, 750 Lower left eighth: 0, 750, 500, 1000 134 CPML FUNCTION REFERENCE A handy utility program is included with Command Post, called WinInfo.exe. This program lets you take an open window that is sized and positioned the way you like it, and automatically create the proper WinPlace statement for you. It puts the text into the Clipboard, from which you can paste it into your menu code: You'll need a mouse to use WinInfo. While WinInfo is the active window, place the mouse over the window you wish to create the WinPlace statement for, and press the spacebar. The new statement will be placed into the Clipboard. Then press the Esc key to close WinInfo. Errors: 1044 "WinPlace: Window not found" Example: WinPlace(0,0,200,200,"Clock") See Also: WinArrange, WinHide, WinIconize, WinShow, WinZoom 135 CPML FUNCTION REFERENCE WinShow Shows a window in its "normal" state. Syntax: WinShow (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be shown. Returns: (integer) @TRUE if a window was found to show; @FALSE if no windows were found. Use this command to restore a window to its "normal" size and position. A partial-windowname of "" restores the current Command Post window. Errors: 1043 "WinShow: Window not found" Example: RunZoom("notepad.exe","") ;other processing... WinShow("Notepad") See Also: WinArrange, WinHide, WinIconize, WinZoom 136 CPML FUNCTION REFERENCE WinTitle Changes the title of a window. Syntax: WinTitle (partial-windowname, new-name) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be shown. "new-name" =the new name of the window. Returns: (integer) @TRUE if a window was found to rename; @FALSE if no windows were found. Use this command to change a window's title. A partial-windowname of "" refers to the current Command Post window. Note: Some applications may rely upon their window's title staying the same! It should be used with caution and adequate testing. Example: &Windows (special) Make &Uppercase HTab = Num2Char(9) AllWinds = WinItemize() MyWin=ItemSelect("Uppercase Windows", AllWinds, HTab) WinTitle(MyWin, StrUpper(MyWin)) Drop (HTab, AllWinds, MyWin) See Also: WinItemize 137 CPML FUNCTION REFERENCE WinVersion Provides the version number of the current Windows system. Syntax: WinVersion (level) Parameters: "level" = either @MAJOR or @MINOR. Returns: (integer) either major or minor part of the Windows version number. Use this command to determine which version of Windows is currently running. @MAJOR returns the integer part of the Windows version number; i.e. 1.0, 2.11, 3.0, etc. @MINOR returns the decimal part of the Windows version number; i.e. 1.0, 2.11, 3.0, etc. Example: &Info Windows &Version MinorVer=WinVersion(@MINOR) MajorVer=WinVersion(@MAJOR) Message("Windows Version",strcat(MajorVer,".",MinorVer)) See Also: Version 138 CPML FUNCTION REFERENCE WinWaitClose Suspends the menu execution until a specified window has been closed. Syntax: WinWaitClose (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. WinWaitClose suspends execution until all matching windows have been closed. Returns: (integer) @TRUE if at least one window was found to wait for; @FALSE if no windows were found. Use this command to suspend the menu item's execution until the user has finished using a given window and has manually closed it. Example: ;WinWaitClose command example run("clock.exe","") Display(4,"Note","Close Clock to continue") WinWaitClose("Clock") Message("Continuing...","Clock closed") See Also: Delay, Yield 139 CPML FUNCTION REFERENCE WinZoom Maximizes a window to full-screen. Syntax: WinZoom (partial-windowname) Parameters: "partial-windowname" = either an initial portion of, or an entire window name. The most-recently used window whose title matches the name will be shown. Returns: (integer) @TRUE if a window was found to zoom; @FALSE if no windows were found. Use this command to "zoom" windows to full screen size. A partial-windowname of "" zooms the current Command Post window. Errors: 1042 "WinZoom: Window not found" Example: Run("notepad.exe","") WinZoom("Notepad") WinShow("Notepad") See Also: WinHide, WinIconize, WinPlace, WinShow 140 CPML FUNCTION REFERENCE Yield Provides time for other windows to do processing. Syntax: Yield Returns: nothing. Use this command to give other running windows time to process. This command will allow each open window to process 20 or more messages. Example: ;run PageMaker and give it some time to start up... PMFile = AskLine ("PageMaker", "File to run:", "") run("PM.EXE", PMFile) yield yield yield See Also: Delay 141 APPENDIX A Browser APPENDIX A Browser The Command Post Browser program lets you view a file's contents in a variety of ways. The default is to show the file in Windows' "ANSI text" mode: Initial Browser View - ANSI Text As you can see, Browser gives you five main menus to choose from: File These menu items let you open a new file to view, re-read the current file, and perform other housekeeping functions including exiting the program. Hide & Seek Browser gives you the ability to filter which lines you view with its Hide & Seek commands. You can hide or show specific lines by entering a word to look for. For instance, the menu item Hide & Seek/Show if... displays this dialog box: ...and (in this example) shows only the lines containing the word "modem": 142 APPENDIX A Browser Print *** Not currently available---We're working on it*** These selections allow you to print all or part of the file. Clip Copy Lets you copy portions of the file into the Windows Clipboard. Clip Append Lets you add portions of the file onto the end of the Windows Clipboard. Options These menu items let you change how you view the file; changing for example between ASCII text mode (which interprets some special characters differently than ANSI text) and hex-dump formats: Options/ASCII text Options/Hex dump 143 APPENDIX B Command Post and Windows 3.0 APPENDIX B Command Post and Windows 3.0 Command Post as Your Shell Normally, Command Post is automatically launched along with the Program Manager, since it is included on the "Run=" line of the WIN.INI file. With Windows 3.0 you can also install Command Post as your primary shell. Perhaps you want to save memory, or avoid having to deal with Windows' Program Manager. It's easy: Using the Notepad editor, edit the SYSTEM.INI file found in your Windows directory. A few lines down from the top you will find a line that reads (as shipped by Microsoft) shell=progman.exe Change this line to: shell=cmdpost.exe Save the file and restart Windows. Command Post will now appear in place of Program Manager. 145 APPENDIX B Command Post and Windows 3.0 The Windows 3.0 Task Manager Windows 3.0 uses a special program called the Task Manager (TASKMAN.EXE). The Task Manager is invoked whenever you do any of the following: 1) Press CTRL-ESC 2) Select Switch To... from the system menu of any application 3) Doubleclick on the screen background with the mouse. The Task Manager supplied with Windows brings up a dialog box which lets you choose which window to go to. Command Post gives you most of Task Manager's functionality. For this reason, we have supplied a replacement TASKMAN.EXE with which you can replace Microsoft's version. Our Task Manager will simply bring up Command Post. To replace Microsoft's TASKMAN.EXE with ours: 1) Rename Microsoft's TASKMAN.EXE to something different, such as TASKMANG.EXE. 2) Copy the TASKMAN.EXE from the Command Post installation directory to your Windows directory. This procedure is done automatically in the Command Post installation program if you choose the appropriate options. Windows' Task Manager has one feature that Command Post lacks: In some instances it lets you shut down otherwise recalcitrant programs with the End Task button. You might want to keep Windows' Task Manager as a Command Post menu item: &Utilities &Task Manager Run ("Taskmang.exe", "") 146 APPENDIX C CPML Programming Tricks APPENDIX C CPML Programming Tricks Fun With Filenames Sometimes you need to take a pathname and extract the drive letter, directory path, or filename from it. The CPML string functions help you do this. Getting the drive letter is relatively easy. Just make sure there's a colon in the pathname in at least the second character position. If there is, take the character just before it: FullPath = AskLine ("", "Enter a full pathname", "") ColonIsAt= StrIndex(FullPath, ":",1, @FWDSCAN) ;if no colon or is first char, return "" drive letter: LetterLen = Min (Max (ColonIsAt-1, 1), 0) DriveLetter = StrSub(FullPath, ColonIsAt-1, 1) Drop (ColonIsAt, LetterLen) The colon could come later than position #2 if the pathname includes a network address before the drive letter. Getting the directory path is accomplished by finding the last backslash character and taking everything before that point. Note when using StrIndex to search backwards from the end of a string, we use a start position of 0: Slash= StrIndex (FullPath, "\", 0, @BACKSCAN) DirPath = StrSub (FullPath, 1, Slash-1) Drop (Slash) The filename is extracted in a similar manner: Slash = StrIndex (FullPath, "\", 0, @BACKSCAN) FName = StrSub (FullPath, Slash+1, StrLen(FullPath) -Slash) Drop (Slash) Once you have a filename you can extract its root. First find the dot. If there isn't any, proceed as if it was at the end. In either case take the portion of the filename before the dot: DotIsAt = StrIndex (FileName,".",0,@FWDSCAN) DotIsAt = DotIsAt*(DotIsAt!=0) + (StrLen(FileName)+1)*(DotIsAt==0) RootFileName=StrSub (FileName,1,DotIsAt-1) Drop (DotIsAt) 147 APPENDIX C CPML Programming Tricks Getting the extension is easier: DotIsAt = StrIndex (FileName,".",0,@FWDSCAN) Terminate (DotIsAt==0,"","File has no extension") Ext= StrSub (FileName, DotIsAt+1, StrLen(FileName)-DotIsAt) Drop (DotIsAt) Making a Free-Floating Menu The Command Post directory window, coupled with the default menu in CMDPOST.CPM, provides you with a more-useful file manager than is provided by Windows version 2.x. However there are times when all you'd rather see is your custom menu bar without the directory listing, perhaps nestled down at the lower-right hand corner of the screen. This can be done rather easily in the initialization section of your custom menu file with the WinPlace command: ThisWin = WinGetActive() WinTitle (ThisWin, "Jenny's Favorites") ;get these dimensions from WININFO.EXE: WinPlace (710,872,1000,966,"Jenny's Favorites") When a Program is Already Running When you launch a program from a menu and it's already running, some times you'd rather just activate the window that's running instead of invoking another instance of the same program: &Desktop &Clock ErrorMode (@OFF) ; Turn Errors Off Terminate (WinActivate("Clock"),"","") ; Already running ErrorMode (@CANCEL) ; Re-enable default error mode Run ("Clock.exe","") Working With Lists When selecting a menu item to run an application program, you can choose a file for the program to open from among all the appropri- ate files in the current directory. For example, assume we want to choose from among the .WRI files, and then run Windows Write with the one we highlighted. If the user presses OK without selecting a file, we'll still run Write, but we won't open a file: HTab = Num2Char (09) WRIFiles = FileItemize("*.WRI") TheFile = ItemSelect(".WRI file, or just OK for new file",WRIFiles, HTab) RunZoom ("Write.exe", TheFile) Drop (WRIFiles, TheFile, HTab) 148 APPENDIX C CPML Programming Tricks We don't have to restrict ourselves to a single wildcard when we itemize files. And if we've set up an association between the file extensions we're itemizing on and the programs that create them, we don't have to restrict ourselves to a single program, either. For example, let's show a list of all our compressed files in the current directory, allow the user to choose one, and run the appropriate decompression program against it. (This assumes we've set up associations between these extensions and their respective compression programs in WIN.INI's [Extensions] section): &Utilities &Compress a file Files = FileItemize ("*.ZIP *.LZH *.ARC *.PAK *.PKA") TheFile = ItemSelect ("Choose a File", FileList, " ") Run (TheFile,"") Drop(FileList, TheFile) Of course, we don't have to itemize just by extension, either. Any kind of wildcard will do. We can even itemize full pathnames. Conditional Branching CPML does not have any branching statements. The closest it comes to having an "if" statement is the Terminate function, which will end the menu item if a specified condition is true. However you can accomplish more useful conditional branching by using string manipulation and the powerful %substitution% feature of the language. Here's the basic technique: Test your condition, negate it, and use the result (@TRUE = 1 or @FALSE = 0) as the "length" parameter in a StrSub function to assign either a ";" or the zero-length null string "" to a variable. Then, substitute this variable's contents into the beginning of each statement you want to execute when the condition is true. When the condition you tested is true, the statements are executed normally. But when the condition is false, a ";" is inserted at the beginning of the lines, making them com- ments and causing those statements to be ignored! Example: You prefer Notepad for simple text editing. But it can't handle files longer than approximately 50,000 bytes in Windows 3.0 (17,000 in Windows 2.x). So let's call Word for Windows if our file is too long: 149 APPENDIX C CPML Programming Tricks &Word Processing &Simple Editing ;assuming MyFile contains the filename we want... TooBig = !(FileSize(MyFile) > 49000) IfTooBig = strsub(";",1, TooBig) IfNotTooBig = strsub(";",1,!TooBig) execute %IfNotTooBig% RunZoom ("Notepad", MyFile) execute %IfTooBig% RunZoom ("D:\winword\WinWord",MyFile) Be sure to use the Execute command in front of the substituted variable, or else you will encounter an error. If these capabilities aren't powerful enough for your needs, you may want to consider having the menu item call a PubTech BatchWorks batch program. The BatchWorks language is upwardly-compatible with CPML (and in fact was also written by us). BatchWorks creates free-standing batch files within which you can have conditionals, loops, subroutines, and extensive dialog boxes defined in addition to the standard CPML functions and commands described here. A BatchWorks file can also be invoked directly from the Windows v3.0 Program Manager. The Command Post Clock The Command Post package includes a screen blanker/clock application. The executable is called CP_BLNK.EXE, and is used in the default CMDPOST.CPM menu. CP_BLNK.EXE takes one parameter, which is the minutes to delay before blanking the screen. The parameter may be a positive, zero, or negative number: Screen Clock Clock Off Blanking Displayed Positive Negative ON number number Zero Don't run OFF CP_BLNK.EXE Examples: Run("cp_blnk.exe",5) ; Display clock. Blank in 5 minutes. Run("cp_blnk.exe",0) ; Display clock. Never Blank. Run("cp_blnk.exe",-5) ; No clock. Blank in 5 minutes. If you start the blanker with a zero or positive number, a clock will appear in the lower right of the screen. Initially the clock will merely display the Command Post version number. See pg. 23 for how to use the Clock once it's onscreen. 150 APPENDIX D Predefined Constants APPENDIX D Predefined Constants CPML provides you with a number of predefined integer constants to help make your menus more mnemonic: Logical Conditions String Handling @FALSE @FWDSCAN @NO @BACKSCAN @OFF @TRUE Menu Handling @YES @ENABLE @ON @DISABLE @UNCHECK Window Arranging @CHECK @NORESIZE System Control @ABOVEICONS @MAJOR @STACK @MINOR @ARRANGE @TITLE Error Handling @ROWS @CANCEL @COLUMNS @NOTIFY @OFF 151 APPENDIX E Errors APPENDIX E Errors If the current error mode is @CANCEL (the default), any CPML errors encountered while processing a menu item cause the item to be cancelled with an error message. Minor Errors Minor errors are ignored if the current error mode has been set to @OFF. If the error mode is @NOTIFY the user has the option of continuing with the menu item or cancelling it. 1006 File Copy/Move: No matching files found 1017 File Delete: No matching files found 1018 File Delete: Delete Failed 1024 File Rename: No matching files found 1025 File Rename: Rename failed 1028 LogDisk: Requested drive not online 1029 DirMake: Dir not created 1030 DirRemove: Dir not removed 1031 DirChange: Dir not found/changed 1039 WinClose: Window not found 1040 WinHide: Window not found 1041 WinIconize: Window not found 1042 WinZoom: Window not found 1043 WinShow: Window not found 1044 WinPlace: Window not found 1045 WinActivate: Window not found Moderate Errors If the error mode is @NOTIFY or @OFF, the user has the option of continuing with the menu item or cancelling it. 2002 File Copy/Move: 'From' file illegal 2003 File Copy/Move: 'To' file illegal 2004 File Copy/Move: Cannot copy/move wildcards into fixed root 2005 File Copy/Move: Cannot copy/move wildcards into fixed extension 2007 File Move: Unable to rename source file 2015 File Move: Unable to remove source file 2016 File Delete: File name illegal 2019 File Rename: 'From' file illegal 2020 File Rename: 'To' file illegal 2021 File Rename: Attempt to rename across drive boundary. - Use MOVE instead. 2022 File Rename: Cannot rename wildcards into a fixed filename root 153 APPENDIX E Errors 2023 File Rename: Cannot rename wildcards into a fixed filename extension 2038 WinCloseNot Function Syntax error 2058 StrCat function syntax error 2060 Average function syntax error 2105 SetDisplay: Display type not SHORT or LONG 2106 SetDisplay: Sort Type not NAME, DATE, SIZE, KIND, or UNSORTED Fatal Errors Fatal errors cause the current menu item to be cancelled with an error message, regardless of the error mode in effect. (We show the error codes here for consistency, but in practice you will never be able to call LastError after a fatal error.) 3008 File Copy/Move: 'From' file open error 3011 File Copy/Move: 'From' file length error 3012 File Copy/Move: No room left on disk. Out of space?? 3013 File Copy/Move: 'To' file open error 3014 File Copy/Move: I/O Error 3026 LogDisk: Illegal disk drive 3027 LogDisk: DOS reports no disks!! ??? 3034 Clipboard owned by another app. Cannot open. 3035 Clipboard does not contain text for ClipAppend. 3036 Clipboard cannot hold that much text (>64000 bytes) 3037 Unable to allocate memory for clipboard. Close some applications 3046 Internal Error 3046. Function not defined 3047 Variable name over 30 chars. Too Long 3048 Substitution %Variable% not followed by a % (Use %% for %) 3049 No variables exist??!! 3050 Undefined variable 3051 Undefined variable or function 3052 Uninitialized variable or undefined function 3053 Character string too long (>256 chars??) 3054 Unrecognizable item found on line 3055 Variable name is over 30 chars. Too Long 3056 Variable could not be converted to string 3057 Variable could not be converted to integer 3059 Illegal Bounds for StrSub function 3061 Illegal Syntax 3062 Attempt to divide by zero 3063 Internal Error 3063. Binary op not found 3064 Internal Error 3064. Unary op not found 3065 Unbalanced Parenthesis 3066 Wrong Number of Arguments in Function 3067 Function Syntax. Opening parenthesis missing. 3068 Function Syntax. Illegal delimiter found. 3069 Illegal assignment statement. (Use == for equality testing) 3070 Internal error 3070. Too many arguments defined. 3071 Missing or incomplete statement 3074 Expression continues past expected end. 154 APPENDIX E Errors 3081 FileRead: Invalid file handle 3082 FileRead: File not currently open 3084 FileWrite: Invalid file handle 3085 FileWrite: File not currently open 3087 FileRead: File not open for reading 3088 FileRead: Attempt to read past end of file 3089 FileWrite: File not open for writing 3095 Compare could not be resolved into a integer or string compare 3096 Memory allocation failure. Out of memory for string storage 3097 Memory allocation failure. Out of memory for variable storage 3098 Internal error, NULL pointer passed to xstrxxx subroutines 3100 StrIndex/StrScan 3rd parameter out of bounds 3101 Substituted line too long. (> 256 characters) 3102 Drop: Can only drop variables 3103 IsDefined: Attempting to test non-variables item 3107 Run: Filetype is not COM, EXE, PIF or BAT 3108 FileItemize: Unable to lock file info segment 3109 FileItemize: Unable to unlock file info segment 3110 FileItemize: Unable to lock file index segment 3111 FileItemize: Unable to unlock file index segment 3112 FileSize: File Not Found 3113 FileSize: Filelength I/O Error 3114 FileSize: Buffer Overrun Error 3115 FileDelete: Buffer Overrun Error 3116 FileRename: Buffer Overrun Error 3117 FileCopyMove: Buffer Overrun Error 3118 FileCopyMove: Destination file same as source 155 Index Index Display 42,73-74 # Drop 46,74-75 #NextFile 103-104 E A EndSession 46,75-76 Abs 45,52 Environment 46,76-77 AskLine 29,42,52-54 ErrorMode 46,77-78 AskYesNo 29,42,54-55 Errors 41-42,157-160 Average 45,55-56 fatal 158-160 minor 157 B moderate 157-158 Beep 42,56-57 see also Debug, ErrorMode, LastError C Execute 46,78-79 Char2Num 45,57-58 Exit 46,79-80 ClipAppend 46,58-59 ClipGet 46,59-60 F ClipPut 46,60-61 File Management Clock, Command Post default "File" menu 6-12 default action 23 in CPML 42-43 in CPML 154 FileCopy 42,80-81 cmdpost.cpm 3,25 FileDelete 43,81-82 and #NextFile 104 FileExist 43,82-83 cmduser.cpm 3,25 FileItemize 43,83-84 and #NextFile 104 FileLocate 43,84-85 Comments 39 FileMove 43,85-86 Conditional Branching 153 FileRename 43,86-87 see also Terminate FileSize 43,87-88 Constants 36-37 predefined 37 H CurrentFile 31,42,61-62 Housekeeping "Main" menu 16-21 D DateTime 46,62-63 I Debug 46,63-65 Identifiers 37 Delay 46,65-66 IniRead 46,88-89 DirChange 31,43,66-67 IniWrite 46,89-90 Directives 41 IsDefined 46,90-91 see also #NextFile IsMenuChecked 44,91-92 Directory Management IsMenuEnabled 44,92-93 default "Dir" menu 12-14 IsNumber 45,93-94 in CPML 43 IsRunning 46,94-95 DirGet 43,67-68 ItemSelect 29,42,95-97 DirHome 43,68-69 DirItemize 43,69-70 J DirMake 43,70-71 JELL-O 54 DirRemove 43,71-72 DiskFree 43,72-73 K 156 IndexIndexIndex Keywords 38 as an icon 6 in CPML 44-45 L RunZoom 28,44,112-113 LastError 47,97-98 LogDisk 43,98-99 S Selecting files 4-6 M SetDisplay 47,113-114 Max 45,99-100 Statements 39-40 menu files 25-31 reference 47-146 CPML language components 36-41 StrCat 45,114-115 error handling 41-42 StrCmp 45,115-116 menu structure 35 StrFill 45,116-117 menuitems 35-36 StrFix 45,117-118 reloading changes 21-22 StrICmp 45,118-119 second file 103-104 StrIndex 45,119-120 statement summary 42-47 StrLen 45,120-121 statements 47-146 StrLower 45,121-122 MenuChange 44,100-101 StrScan 45,122-123 Message 30,42,101-102 StrSub 45,123-124 Microsoft Windows StrTrim 45,124-125 date & time formatting 63 StrUpper 45,125-126 determining the version Substitution 40-41 47,141-142 and StrCat 114-115 ending the session 11 System Menu 21-22 version 2.x ending the session 76 T MS-DOS Executive 3 Terminate 30,42,47,126-128 version 3.0 TextBox 42,128-129 ending the session 76 Min 46,102-103 V Variables 37-38 N Version 47,129 Num2Char 45,102-105 Views default "View" menu 14-16 O see also SetDisplay Operators 38-39 Precedence 39 W OtherDir 47,105-106 WinActivate 43,129-130 OtherUpdate 47,106-107 WinArrange 43,130-132 WinClose 44,132 P WinCloseNot 44,132-133 Pause 30,42,107-108 Window Management in CPML 43-44 R WinGetActive 44,133-134 Random 46,108-109 WinHide 44,134-135 Registration 21,163 WinIconize 44,135-136 Run 28,44,109-110 WinItemize 44,136-137 RunHide 44,110-111 WinPlace 44,137-139 RunIcon 28,44,111-112 WinShow 44,139-140 Running programs WinTitle 44,140-141 as a normal window 6 WinVersion 47,141-142 157 WinWaitClose 44,142-143 Yield 47,144-145 WinZoom 44,143-144 Y 158