Command Post 7.0 User's Manual For IBM R PC/XT R, PC/AT R, PS/2 R 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 c 1988-1990 by Morrie Wilson. All rights reserved. Software License 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. The registered software may be copied for backup purposes only. The shareware version may be distributed for evaluation purposes only. It is against the law to copy the software on any medium except as specifically allowed in the license agreement. Limited Warranty Wilson WindowWare guarantees your satisfaction with this product for a period of 30 days from the date of the original purchase. If you are unsatisfied with Command Post within that time period, return the package in saleable condition to the place of original purchase for a full refund. Wilson WindowWare warrants the original disks and documentation are free from defects in material and workmanship, assuming normal use, for a period of 90 days from the date of purchase. EXCEPT AS SPECIFICALLY PROVIDED ABOVE, WILSON WINDOWWARE MAKES NO OTHER WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS SOFTWARE, THE DISKS OR DOCUMENTATION, INCLUDING ITS QUALITY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL WILSON WINDOWWARE BE HELD LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING FROM FAILURE OR DEFICIENCY OF THIS MANUAL OR THE SOFTWARE DESCRIBED HEREIN, EVEN IF WILSON WINDOWWARE HAS BEEN ADVISED OF ANY POSSIBILITY OR LIKELIHOOD OF SUCH DAMAGES. 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 ii 25-Apr-90 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. 25-Apr-90 iii CONTENTS CONTENTS CONTENTS iv INTRODUCTION viii System Requirements viii About This Manual viii Notational Conventions viii Acknowledgements ix GETTING STARTED 10 TEN-MINUTE TOUR 11 File Management 14 Directory Management 19 Changing the View 21 Housekeeping Functions 22 System Menu Box 26 The Command Post Clock 27 YOUR OWN MENUS 29 What is a Menu File? 29 How to Create a Simple Menu 29 Enhancing Our Menu 30 An Enhancement for Safety 31 The Major Functions 32 Running a Program 32 Getting Information from the User 33 Displaying Information 34 Other Useful Functions 35 COMMAND POST MENU LANGUAGE 37 Menu Structure 37 Menu Items 37 Language Components 38 Constants 38 Identifiers 39 Variables 39 Keywords Are Reserved 39 Operators 40 Precedence and evaluation order40 Comments 41 Statements 41 Substitution 42 Language Directives 42 Function Parameters 42 Error Handling 43 The Functions & Statements 43 Inputting Information 43 Displaying Information 44 File Management 44 iv 25-Apr-90 CONTENTS Directory Management 44 Disk Drive Management 45 Window Management 45 Menu Management 46 Program Management 46 String Handling 46 Arithmetic Functions 47 Clipboard Handling 47 System Control 47 CPML FUNCTION REFERENCE 49 Introduction 49 Abs 50 AskLine 50 AskYesNo 51 Average 52 Beep 52 Char2Num 53 ClipAppend 53 ClipGet 54 ClipPut 54 CurrentFile 55 DateTime 55 Debug 56 Delay 58 DirChange 58 DirGet 59 DirHome 59 DirItemize 60 DirMake 60 DirRemove 61 DiskFree 61 Display 62 Drop 63 EndSession 63 Environment 63 ErrorMode 64 Execute 65 Exit 65 FileCopy 66 FileDelete 67 FileExist 67 FileItemize 68 FileLocate 69 FileMove 69 FileRename 70 FileSize 71 IniRead 71 IniWrite 72 IsDefined 73 IsMenuChecked 73 IsMenuEnabled 74 IsNumber 74 IsRunning 75 25-Apr-90 v CONTENTS ItemSelect 75 LastError 76 LogDisk 77 Max 77 MenuChange 78 Message 78 Min 79 #NextFile 80 Num2Char 80 OtherDir 80 OtherUpdate 81 Pause 81 Random 82 Run 83 RunHide 83 RunIcon 84 RunZoom 85 SetDisplay 85 StrCat 86 StrCmp 87 StrFill 87 StrFix 88 StriCmp 89 StrIndex 89 StrLen 90 StrLower 90 StrScan 91 StrSub 92 StrTrim 92 StrUpper 93 Terminate 93 TextBox 94 Version 95 WinActivate 96 WinArrange 96 WinClose 97 WinCloseNot 98 WinGetActive 99 WinHide 99 WinIconize 100 WinItemize 100 WinPlace 101 WinShow 102 WinTitle 103 WinVersion 104 WinWaitClose 104 WinZoom 105 Yield 105 APPENDIX A Browser 107 APPENDIX B Command Post and Windows109 The Command Post Clock 109 vi 25-Apr-90 CONTENTS APPENDIX C CPML Programming Tricks110 Fun With Filenames 110 Making a Free-Floating Menu 111 When a Program is Already Running111 Working With Lists 111 Conditional Branching 112 APPENDIX D Predefined Constants 114 APPENDIX E Errors 115 Minor Errors 115 Moderate Errors 115 Fatal Errors 116 Index 119 25-Apr-90 vii 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.0 or higher. About This Manual This manual is divided into five sections: First is Getting Started (pg. ix), where we tell you how to install the program. Then we offer a Ten-Minute Tour of the default File Manager window (pg. 10). Next is an introduction to creating Your Own Menus (pg. 28), 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. 37), and a comprehensive CPML Function Reference (pg. 48) 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. viii 25-Apr-90 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. 25-Apr-90 ix GETTING STARTED GETTING STARTED Command Post is quite easy to install. You will find two diskettes in your Command Post package: One 5 1/4" and one 3 1/2". Take whichever one is appropriate for your computer and insert it into your floppy drive. Make sure you are completely out of Windows and are at the DOS prompt. (If you must insist on calling a DOS session from within Windows in order to install Command Post, AT LEAST MAKE SURE COMMAND POST ISN'T RUNNING before you try to install the new version on top of it!) Now that you are at the DOS prompt, type A: or B:, depending on which floppy drive you used. Type the command install. You'll be prompted for a directory path to copy the files into. You can have install copy the files to your Windows directory, or to some other directory in your DOS PATH. Install will then extract the necessary files and place them into this directory. When the installation program is finished you should take a few minutes to view the CP_READ.ME file. This file contains any late- breaking information about your copy of Command Post. 10 25-Apr-90 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. Selecting files and navigating through your directories is similar to using the MS-DOS Executive: 25-Apr-90 37 TEN-MINUTE TOUR Action Mouse Keyboard Click on type Ctrl + Select a directory icon desired drive Drive with the left letter. button. Select a Click on Use arrow keys File desired to place filename with selection box left button. over desired file, then press Enter. OR: Press first letter of filename to move selection box to next file with that letter. Select Click on Press the Shift Additiona additional key while l Files filenames with moving the left button selection box while pressing over a range of the Shift key. filenames. OR: Click on additional filenames with the right button. OR: Drag mouse 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 12 25-Apr-90 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. Go to a Doubleclick on Place selection Subdirec- desired subdir- box over tory ectory name desired with the left directory and button. press Enter. Go to a Click on Press the Parent desired Backspace key. Directory directory in the current path string (next to the drive icons) with the left button. 25-Apr-90 13 TEN-MINUTE TOUR Let's look at the default menu items: File Management Run... Load... These selections launch a program. 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 highlighted 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: 14 25-Apr-90 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": 25-Apr-90 15 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. 106 ). 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. 16 25-Apr-90 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 the printer attached to the LPT1: device. This command is meant to be used with text files only; it doesn't attempt to format the file or otherwise interpret it. Size of selected files This menu item displays a message box showing you how much space is taken up by the selected files: 25-Apr-90 17 TEN-MINUTE TOUR Space left 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. Associate... 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 popup 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/Associate 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 18 25-Apr-90 TEN-MINUTE TOUR version 2.11. 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: 25-Apr-90 19 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... . 20 25-Apr-90 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 25-Apr-90 21 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- 1 Stack 2 Arrange 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 3 Arrange in Rows 4 Arrange menu contains the window in Columns arranging functions. There are four ways Command Post can Selections 5 through 8 are the arrange application windows on same as 1 through 4 except the the screen for you: Command Post window is minimized. Housekeeping Functions 22 25-Apr-90 TEN-MINUTE TOUR Clipboard This menu item runs the Windows Clipboard viewer: 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/Re- name/Move..., the destination pathname defaults to the "other" Command Post's directory. Control Panel This selection runs the Windows Control Panel: Windows 2.11 Control Panel 25-Apr-90 23 TEN-MINUTE TOUR DOS C:> 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. Edit Command Post Menus This menu item displays a listbox containing all the .CPM files in the current directory: It then starts the Windows Notepad with the .CPM file you chose: 24 25-Apr-90 TEN-MINUTE TOUR In order to actually use the updated menu file you must select Reload Menu from Command Post's system-box menu. Edit INI Files This menu item lets you edit a Windows initialization file. It starts the Windows Notepad with the .INI file: 25-Apr-90 25 TEN-MINUTE TOUR System Information This selection shows a message box containing numerous pieces of information about your Windows installation. 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, and About Command Post.... In addition we've added: 26 25-Apr-90 TEN-MINUTE TOUR 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 annoying 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. Exit Windows This is the same as selecting Exit Windows from the File menu. (the second column) The right-hand column of entries contain the names of all the open application windows. You can switch to one of these programs by doubleclicking on their title in the menu. 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. 25-Apr-90 27 TEN-MINUTE TOUR Action Mouse Keyboard Change Click with the Select display right mouse "CmdPost 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. Close (not Select available) "CmdPost Clock" from the Command Post system menu's right- hand column. Type ALT-F4. Move Drag with left (not mouse button. available) Doubleclick (not Show with the right available) system mouse button. info Jump to Doubleclick (not Command with the left available) Post button. 28 25-Apr-90 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 CommandPost menu bar, and menu items in the dropdown menus. For each menu item you'll have one or more lines of commands which CommandPost 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 Because it begins in column 1, this entry defines a menu name. The 25-Apr-90 29 YOUR OWN MENUS "&" 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 3.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(CMPL), but it takes only a few to get started. Well, what did we do to start PageMaker before we had CommandPost? 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 3.0 DirChange("d:\pm\docs") Run("pm.exe","") DirChange("d:\pm\docs") tells CommandPost to change to the D: drive and find the \PM\DOCS subdirectory. Run("pm.exe", "") tells CommandPost 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.PM3, CHPTR2.PM3, 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 3.0 item we created above. Since this is a submenu item, it starts in column 2: 30 25-Apr-90 YOUR OWN MENUS PM-&Waldorf DirChange ("d:\pm\waldorf") RunZoom ("pm.exe", "chptr1.pm3") RunIcon ("clipbrd.exe","") Our menu item now does a lot of work for us. The RunZoom command has a new parameter, "chptr1.pm3", which tells PageMaker which file to load when it starts up. The command RunIcon launches the program CLIPBRD.EXE 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 Afterspending 45 hours on CHPTR1.PM3, 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.pm3","a:chptr1.pm3",@FALSE) RunZoom ("pm.exe", "chptr1.pm3") 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.PM3 to the destination A:CHPTR1.PM3. 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! 25-Apr-90 31 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. 84) 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. 83) Example: &Word Processing Edit &MyFile Run ("Notepad", "myfile.txt") RunZoom (program-name, parameters) Starts a program as a full-screen window. (See pg. 85) Example: &Accounting The &BIG spreadsheet RunZoom ("Excel", "bigsheet.xcl") 32 25-Apr-90 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. 51) Example: &Utilities Delete MyFile... Cont = AskYesNo ("My Menu", "You REALLY want to do this?") Terminate (Cont==@NO, "", "") FileDelete (MyFile) 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. 50) 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. 75) Example: &DTP Apps PM-&Waldorf Project DirChange ("d:\pm\waldorf") WFiles = FileItemize ("chptr*.pm3") TheFile = ItemSelect ("Select A Chapter", WFiles, " ") RunZoom ("pm.exe", TheFile) 25-Apr-90 33 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. 78) 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. 80) 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. 93) 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.xcl") 34 25-Apr-90 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. 55) Example: &Editing Run &Notepad with selected file Run ("Notepad", CurrentFile()) DirChange (pathname) Changes the directory to the pathname specified. (See pg. 58) Example: &Miscellany &Run some program not in path DirChange ("c:\some\dir\not\in\path") Run ("Obscure.exe","") 25-Apr-90 35 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, makes a new column starting with this item. _ 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. 46) that can alter the characteristics of the menu titles themselves. For instance you can put a checkmark next to a menu, or disable & 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. 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. 25-Apr-90 37 COMMAND POST MENU LANGUAGE 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, "", "You have FULL access") MenuChange("SystemUtilitiesCleanupDir", @DISABLE) MenuChange("SystemUtilitiesEditBatFiles",@DISABLE) MenuChange("SystemUtilitiesEditWinIni", @DISABLE) Terminate (@TRUE, "", "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 of 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 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. 38 25-Apr-90 COMMAND POST MENU LANGUAGE 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 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. 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 25-Apr-90 39 COMMAND POST MENU LANGUAGE 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 < 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 40 25-Apr-90 COMMAND POST MENU LANGUAGE 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. 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 25-Apr-90 41 COMMAND POST MENU LANGUAGE 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. 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. 42 25-Apr-90 COMMAND POST MENU LANGUAGE 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. @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. 25-Apr-90 43 COMMAND POST MENU LANGUAGE 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. 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. 44 25-Apr-90 COMMAND POST MENU LANGUAGE 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. 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. 25-Apr-90 45 COMMAND POST MENU LANGUAGE 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. 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. 46 25-Apr-90 COMMAND POST MENU LANGUAGE StrScan (main-str, delims, start, direction) Finds an occurance 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. 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. 25-Apr-90 47 COMMAND POST MENU LANGUAGE 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. 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. 48 25-Apr-90 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. 25-Apr-90 49 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 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) 50 25-Apr-90 CPML FUNCTION REFERENCE produces: ...and then, if Jenny types "Strawberry Sundae" and presses OK: See Also: AskYesNo, Display, ItemSelect, Message, Pause, TextBox 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('','Please press "YES"') 25-Apr-90 51 CPML FUNCTION REFERENCE 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 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 Beep Beeps once. 52 25-Apr-90 CPML FUNCTION REFERENCE Syntax: Beep Use this command to produce a short beep, generally to alert the user to an error situation. Example: q=AskYesNo('YES!!!', 'Please press "YES"') terminate(q==@NO, "", "") Beep Display(3,'ERROR',"I said press 'YES'") 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 ClipAppend Appends a string to the Clipboard. Syntax: ClipAppend (string) Parameters: "string" = text string to add to Clipboard. 25-Apr-90 53 CPML FUNCTION REFERENCE 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 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 ClipPut Copies a string to the clipboard. 54 25-Apr-90 CPML FUNCTION REFERENCE 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 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 DateTime Provides the current Date and time. 25-Apr-90 55 CPML FUNCTION REFERENCE 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/Nite code (e.g. AM or PM) 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("The Date and Time is",DateTime()) would produce: 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 56 25-Apr-90 CPML FUNCTION REFERENCE @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("Is the Pope Catholic") debug(@off) b = a + 4 produces: ...then, if the user presses Next: ...and if the user presses Yes: 25-Apr-90 57 CPML FUNCTION REFERENCE ...etc. (If the user had pressed No it would have said "VALUE=>0".) See Also: ErrorMode, LastError Delay Pauses execution a specifed 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 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. 58 25-Apr-90 CPML FUNCTION REFERENCE 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("config.sys") See Also: DirGet, DirHome, LogDisk 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") DirChange(OrigDir) See Also: DirHome, OtherDir DirHome Returns directory containing the Command Post EXE file. Syntax: DirHome ( ) Returns: (string) pathname of the home directory. Use this command to determine location of .exe and menu files. 25-Apr-90 59 CPML FUNCTION REFERENCE Example: a=DirHome() Message("Command Post was started from",a) See Also: DirGet, OtherDir 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 DirMake Creates a new directory. Syntax: DirMake ([d:]path) Parameters: "[d:]" = the desired disk drive. "path" = the path to create. 60 25-Apr-90 CPML FUNCTION REFERENCE 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 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 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. 25-Apr-90 61 CPML FUNCTION REFERENCE 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 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("Favorite dessert?","Jello") display(3,"%name%'s Dessert",dsrt) ...the display statement produces: 62 25-Apr-90 CPML FUNCTION REFERENCE See Also: Pause, Message, Terminate 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 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. 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 Environment Gets a DOS environment variable. 25-Apr-90 63 CPML FUNCTION REFERENCE 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 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 occured. @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 supress errors you expect will occur and then re-enable ErrorMode (@CANCEL). 64 25-Apr-90 CPML FUNCTION REFERENCE 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 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% 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. 25-Apr-90 65 CPML FUNCTION REFERENCE Example: a = 100 message("The value of a is",a) exit See Also: Pause 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 66 25-Apr-90 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: See Also: FileExist, FileLocate, FileMove, FileRename 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. 25-Apr-90 67 CPML FUNCTION REFERENCE 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(strcat(DirGet(),"myfile.txt")) Tex=substr("NOT ",1,strlen("NOT ")*Fex) Message("MyFile.Txt"," Is %Tex%in the DOS path") See Also: FileLocate 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 when there are many): IFiles=FileItemize("c:\win\*.ini") IFile=ItemSelect(".INI Files",IFiles) RunZoom ("Notepad", IFile) Drop (IFiles, IFile) See Also: DirItemize, WinItemize, ItemSelect 68 25-Apr-90 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 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. 25-Apr-90 69 CPML FUNCTION REFERENCE 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 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. 70 25-Apr-90 CPML FUNCTION REFERENCE 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 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 IniRead Reads data from the WIN.INI file. 25-Apr-90 71 CPML FUNCTION REFERENCE 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 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. 72 25-Apr-90 CPML FUNCTION REFERENCE 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 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 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 to indicate an option has been enabled. This function lets you determine if the menu 25-Apr-90 73 CPML FUNCTION REFERENCE item has already been checked. Example: See Also: IsMenuEnabled, MenuChange 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 if you want to prevent the user from choosing it. It shows up on the screen as a grayed item. This function lets you determine if the menu item has been disabled or not. Example: See Also: IsMenuChecked, MenuChange 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. 74 25-Apr-90 CPML FUNCTION REFERENCE Example: a = AskLine("ISNUMBER","Enter a number","0") Terminate(!IsNumber(a),"", "You didn't enter a number") See Also: Abs, Char2Num 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: See Also: OtherDir, OtherUpdate 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. 25-Apr-90 75 CPML FUNCTION REFERENCE 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("pcpaint", TheFile) would produce (depending on what's in the current directory): See Also: AskYesNo, Display, DirItemize, FileItemize, WinItemize, Message, Pause, TextBox 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). 76 25-Apr-90 CPML FUNCTION REFERENCE 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 999-9999.") See Also: Debug, ErrorMode 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 Max Returns largest number in a list of numbers. Syntax: Max (integer [, integer]...) Parameters: "integer" = number. 25-Apr-90 77 CPML FUNCTION REFERENCE 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 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 & 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 Message Displays a message to the user. Syntax: Message (title, text) 78 25-Apr-90 CPML FUNCTION REFERENCE 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 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 25-Apr-90 79 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 . . . 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 OtherDir Finds the directory where the other copy of Command Post is running, if any. 80 25-Apr-90 CPML FUNCTION REFERENCE 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 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: See Also: OtherDir, SetDisplay Pause Provides a message to user. User may cancel processing. 25-Apr-90 81 CPML FUNCTION REFERENCE 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 Random Computes a psuedo-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) 82 25-Apr-90 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 not are 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 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 not are part of the program name, the current 25-Apr-90 83 CPML FUNCTION REFERENCE 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 RunIcon Runs a program as an iconized (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 not are 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. 84 25-Apr-90 CPML FUNCTION REFERENCE Examples: RunIcon("Notepad.exe","abc.txt") RunIcon("clock.exe","") RunIcon("paint.exe","pict.msp") See Also: Run, RunHide, RunZoom, WinIconize, WinClose, WinWaitClose 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 not are 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 SetDisplay Controls the display of files in the Command Post File Manager window. 25-Apr-90 85 CPML FUNCTION REFERENCE 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") 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. 86 25-Apr-90 CPML FUNCTION REFERENCE 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 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 a=strsub("less than equal to greater than",c*12,12) ;Note that above string is grouped into 12-charater chunks. ;Desired chunk is removed with the strsub statement. message("STRCMP","%a% is %d% %b%") See Also: StrICmp, StrIndex, StrLen, StrScan, StrSub StrFill Creates a string filled with a series of characters. 25-Apr-90 87 CPML FUNCTION REFERENCE 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 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 88 25-Apr-90 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. Note: This command has been included for semantic completeness. The relational operators >, >=, ==, !=, <=, and < provide the same capability. Example: a=AskLine("STRICMP","Enter a test line","") b=AskLine("STRICMP","Enter another test line","") c=stricmp(a,b) c=c+1 a=strsub("less than equal to greater than",c*12,12) ;Note that above string is grouped into 12-charater chunks. ;Desired chunk is removed with the strsub statement. message("STRICMP","%a% is %d% %b%") See Also: StrCmp, StrIndex, StrLen, StrScan, StrSub 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. 25-Apr-90 89 CPML FUNCTION REFERENCE 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: AskLine ("STRINDEX", "Type a sentence:", InStr) 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 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 StrLower Converts a string to lowercase. 90 25-Apr-90 CPML FUNCTION REFERENCE 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 StrScan Searches string for occurence 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". 25-Apr-90 91 CPML FUNCTION REFERENCE 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 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 StrTrim Removes leading and trailing spaces from a character string. 92 25-Apr-90 CPML FUNCTION REFERENCE 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 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 Terminate Conditionally ends the menuitem. Syntax: Terminate (expression, title, message) 25-Apr-90 93 CPML FUNCTION REFERENCE 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 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. 94 25-Apr-90 CPML FUNCTION REFERENCE 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 multiline 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 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 25-Apr-90 95 CPML FUNCTION REFERENCE 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 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 WinArrange Arranges, tiles, and/or stacks application windows. Syntax: WinArrange (style) Parameters: style = one of the following: @STACK, @TILE (or @ARRANGE), @ROWS, or @COLUMNS. 96 25-Apr-90 CPML FUNCTION REFERENCE 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. Example: &Reveal all windows WinArrange (@TILE) See Also: WinItemize, WinHide, WinIconize, WinPlace, WinShow, WinZoom 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. 25-Apr-90 97 CPML FUNCTION REFERENCE 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 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 98 25-Apr-90 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 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 25-Apr-90 99 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 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. 100 25-Apr-90 CPML FUNCTION REFERENCE Example: &Windows &Find a window AllWins = WinItemize() HTab = Num2Char(9) MyWind = ItemSelect("Windows",AllWins, HTab) WinActivate(MyWind) See Also: DirItemize, FileItemize, ItemSelect 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 25-Apr-90 101 CPML FUNCTION REFERENCE Center quarter: 250, 250, 750, 750 Lower left eighth: 0, 750, 500, 1000 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 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. 102 25-Apr-90 CPML FUNCTION REFERENCE 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 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 25-Apr-90 103 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.-, 2.-, etc. @MINOR returns the decimal part of the Windows version number; i.e. -.0, -.11, -.0, etc. Example: &Info Windows &Version MinorVer=WinVersion(@MINOR) MajorVer=WinVersion(@MAJOR) Message("Windows Version",strcat(MajorVer,".",MinorVer)) See Also: Version 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. 104 25-Apr-90 CPML FUNCTION REFERENCE Example: ;WinWaitClose command example run("clock.exe","") Display(4,"Note","Close Clock to continue") WinWaitClose("Clock") Message("Continuing...","Clock closed") See Also: Delay, Yield 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 Yield Provides time for other windows to do processing. Syntax: Yield Returns: nothing. Use this command to give other running windows time to process. 25-Apr-90 105 CPML FUNCTION REFERENCE This command will allow each open window to process 20 or more messages. Example: ;run PageMaker and give it sime time to start up... PMFile = AskLine ("PageMaker", "File to run:", "") run("PM.EXE", PMFile) yield yield yield See Also: Delay 106 25-Apr-90 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": 25-Apr-90 107 APPENDIX A Browser Print 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 108 25-Apr-90 APPENDIX B Command Post and Windows APPENDIX B Command Post and Windows 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 postive, zero, or negative number: Screen Clock Clock Off Blanking Displayed ON Positive Negative 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. 25-Apr-90 109 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) Getting the extension is easier: 110 25-Apr-90 APPENDIX C CPML Programming Tricks 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) ; Reenable 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: WRIFiles = FileItemize("*.WRI") TheFile = ItemSelect(".WRI file, or just OK for new file",WRIFiles) RunZoom ("Write.exe", TheFile) Drop (WRIFiles, TheFile) 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 25-Apr-90 111 APPENDIX C CPML Programming Tricks 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 32767 bytes. So let's call Word for Windows if our file is too long: &Word Processing &Simple Editing ;assuming MyFile contains the filename we want... TooBig = !(FileSize(MyFile) > 32767) 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. 112 25-Apr-90 APPENDIX C CPML Programming Tricks 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. 25-Apr-90 113 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 Menu Handling @TRUE @ENABLE @YES @DISABLE @ON @UNCHECK Window Arranging @CHECK @NORESIZE @ABOVEICONS System Control @STACK @MAJOR @ARRANGE @MINOR @TITLE Error Handling @ROWS @CANCEL @COLUMNS @NOTIFY @OFF 114 25-Apr-90 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 2023 File Rename: Cannot rename wildcards into a fixed filename extension 25-Apr-90 115 APPENDIX E Errors 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 Substition %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. 3081 FileRead: Invalid file handle 3082 FileRead: File not currently open 3084 FileWrite: Invalid file handle 116 25-Apr-90 APPENDIX E Errors 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 25-Apr-90 117 Index Index moderate, 115-116; see also, # Debug,ErrorMode,LastError #NextFile, 79-80 Execute, 48,65 Exit, 48,65-66 A Abs, 47,49-50 F AskLine, 33,43,50-51 FileCopy, 44,66-67 AskYesNo, 33,43,51-52 FileDelete, 44,67 Average, 47,52 FileExist, 44,67-68 FileItemize, 44,68-69 B FileLocate, 44,68-69 Beep, 44,52-53 FileMove, 44,69-70 FileRename, 44,70-71 C FileSize, 44,71 Char2Num, 46,52-53 ClipAppend, 47,53-54 I ClipGet, 47,54 Identifiers, 39 ClipPut, 47,54-55 IniRead, 48,71-72 cmdpost.cpm, 11,29; and IniWrite, 48,72-73 #NextFile, 80 IsDefined, 48,81 cmduser.cpm, 11,29; and IsMenuChecked, 46,73-74 #NextFile, 80 IsMenuEnabled, 46,74 Comments, 39-40 IsNumber, 46,74-75 Conditional Branching, 112; see IsRunning, 48,75 also, Terminate ItemSelect, 33,43,75-76 Constants, 38-39; predefined, 39 CurrentFile, 35,44,55 K Keywords, 39-40 D DateTime, 47,55-56 L Debug, 47,56-58 LastError, 48,76-77 Delay, 47,58 LogDisk, 45,76-77 DirChange, 35,44,58-59 Directives, 42; see also, M #NextFile Max, 47,77-78 DirGet, 44,59 MenuChange, 46,78 DirHome, 44,59-60 Message, 34,44,78-79 DirItemize, 45,60 Microsoft Windows: determining DirMake, 45,60-61 the version, 48,104; ending the DirRemove, 45,61 session, 19; version 2.x, 23; DiskFree, 45,61-62 MS-DOS Executive, 11; version Display, 44,61-63 3.0; ending the session, 63 Drop, 47,63 Min, 47,79-80 E N EndSession, 47,63 Num2Char, 46,79-80 Environment, 48,63-64 ErrorMode, 48,64-65 O Errors, Error_handling,115-119; Operators, 40; Precedence, 40 fatal, 116-119; minor, 115; OtherDir, 48,80-81 25-Apr-90 119 OtherUpdate, 48,81 Substitution, 42; and StrCat, 86-87 P Pause, 34,44,80-82 T Terminate, 34,44,48,93-94 R TextBox, 44,94-95 Random, 47,82-83 Run, 32,46,83 V RunHide, 46,83-84 Variables, 39 RunIcon, 32,46,84-85 Version, 48,95-96 Running programs: as a normal window, 14; as an icon, 14 W RunZoom, 32,46,85 WinActivate, 45,96 WinArrange, 45,96-97 S WinClose, 45,97-98 SetDisplay, 48,85-86 WinCloseNot, 45,98-99 Statements, 41-42; reference, WinGetActive, 45,99 48-106 WinHide, 45,99-100 StrCat, 46,86-87 WinIconize, 45,100 StrCmp, 46,86-87 WinItemize, 45,100-101 StrFill, 46,87-88 WinPlace, 45,100-102 StrFix, 46,88-89 WinShow, 45,102-103 StrICmp, 46,89 WinTitle, 45,103-104 StrIndex, 46,89-90 WinVersion, 48,104 StrLen, 46,90 WinWaitClose, 45,104-105 StrLower, 46,90-91 WinZoom, 45,105 StrScan, 47,91-92 StrSub, 47,92 Y StrTrim, 47,92-93 Yield, 48,105-106 StrUpper, 47,93 120 25-Apr-90 I want my OWN copy of Command Post! Please send it to: Company: Name: Address: City: St: Zip: Phone: ( ) - Command Post(s) @$49.95 ea. . Total: . Please enclose a check payable to Wilson WindowWare; or you may use Visa, MasterCharge, or EuroCard. For charge cards, please enter the information below: Card number: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ Expiration date: ___/___ Signature: Send to: Wilson WindowWare 2701 California Ave SW #212 Seattle, WA 98116 USA or call: (800) 761-8383 (206) 935-7129 (fax) (Please allow 2 to 4 weeks for delivery)