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