home *** CD-ROM | disk | FTP | other *** search
/ Shareware 1 2 the Maxx / sw_1.zip / sw_1 / WINDOWS / UTILS / FC_10N.ZIP / FILECMDR.MA$ < prev    next >
Text File  |  1992-03-19  |  160KB  |  6,731 lines
  1.  
  2.  
  3.  
  4.  
  5.                                                          File Commander 0.0
  6.                                                               User's Manual
  7.  
  8.  
  9.  
  10.                                                                   22-Feb-92
  11.  
  12.  
  13.  
  14.                                This manual is incomplete and partially in
  15.                                error.  Below is the Command Post manual,
  16.                                roughly whacked into a VERY preliminary
  17.                                File Commander Manual
  18.  
  19.  
  20.  
  21.                                 For IBM, PC/XT, PC/AT, PS/2 and compatibles
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.                                                           Wilson WindowWare
  36.                                             2701 California Ave SW  ste 212
  37.                                                           Seattle, WA 98116
  38.  
  39.  
  40.                                                       Orders:(800) 762-8383
  41.                                                    Support:  (206) 937-9335
  42.                                                       Fax:   (206) 935-7129
  43.  
  44.  
  45.  
  46.  
  47.                          Copyright 1988-1992 by Morrie Wilson.
  48.                                   All rights reserved.
  49.  
  50.  
  51.  
  52.           No part of this manual may be reproduced or transmitted in any
  53.           form or by any means, electronic or mechanical, including
  54.           photocopying and recording, for any purpose without the express
  55.           written permission of Wilson WindowWare.  Information in this
  56.           document is subject to change without notice and does not
  57.           represent a commitment by Wilson WindowWare.
  58.  
  59.  
  60.           The software described herein is furnished under a license
  61.           agreement.  It is against the law to copy this software under any
  62.           circumstances except as provided by the license agreement.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.           U.S. Government Restricted Rights
  73.           Use, duplication, or disclosure by the Government is subject to
  74.           restrictions as set forth in subdivision (b)(3)(ii) of the Rights
  75.           in Technical Data and Computer Software clause at 252.227-7013.
  76.           Contractor/manufacturer is Wilson WindowWare/2701 California Ave SW
  77.           /ste 212/Seattle, WA 98116
  78.  
  79.  
  80.  
  81.           Trademarks
  82.           IBM, PC/XT, PC/AT, and PS/2 are registered trademarks of
  83.           International Business Machines Corporation.
  84.           Microsoft and MS-DOS are registered trademarks of Microsoft
  85.           Corporation.
  86.           Windows is a trademark of Microsoft Corporation.
  87.           PageMaker is a trademark of Aldus Corporation.
  88.           PubTech and BatchWorks are registered trademarks of Publishing
  89.           Technologies, Inc.
  90.  
  91.           JELL-O is  a registered trademark of General Foods Corporation.
  92.  
  93.           Command Post is a trademark of Wilson WindowWare, Inc.
  94.           File Commander is a trademark of Wilson WindowWare, Inc.
  95.  
  96.  
  97.  
  98.                                                                             ii
  99.  
  100.                                                                       CONTENTS
  101.  
  102.  
  103.                                         CONTENTS
  104.  
  105.  
  106.           CONTENTS                           iii
  107.  
  108.           INTRODUCTION                         v
  109.              System Requirements               v
  110.              About This Manual                 v
  111.              Notational Conventions            v
  112.              Acknowledgements                 vi
  113.  
  114.           GETTING STARTED                      1
  115.  
  116.  
  117.            <<< Deleted Text >>>
  118.  
  119.           YOUR OWN MENUS                      25
  120.              What is a Menu File?             25
  121.              How to Create a Simple Menu      25
  122.              Enhancing Our Menu               26
  123.              An Enhancement for Safety        27
  124.              The Major Functions              28
  125.                Running a Program              28
  126.                Getting Info from the User     29
  127.                Displaying Information         30
  128.                Other Useful Functions         31
  129.  
  130.           COMMAND POST MENU LANGUAGE          35
  131.              Menu Structure                   35
  132.              Menu Items                       35
  133.              Language Components              36
  134.                Constants                      36
  135.                Identifiers                    37
  136.                Variables                      37
  137.                Keywords Are Reserved          38
  138.                Operators                      38
  139.            Precedence and eval order      39
  140.                Comments                       39
  141.                Statements                     39
  142.                Substitution                   40
  143.                Language Directives            41
  144.              Function Parameters              41
  145.              Error Handling                   41
  146.  
  147.                                                                            iii
  148.  
  149.                                                                       CONTENTS
  150.  
  151.              The Functions & Statements       42
  152.                Inputting Information          42
  153.                Displaying Information         42
  154.                File Management                42
  155.                Directory Management           43
  156.                Disk Drive Management          43
  157.                Window Management              43
  158.                Menu Management                44
  159.                Program Management             44
  160.                String Handling                45
  161.                Arithmetic Functions           45
  162.                Clipboard Handling             46
  163.                System Control                 46
  164.  
  165.           CPML FUNCTION REFERENCE             51
  166.              Introduction                     51
  167.              Abs                              52
  168.              TextBox                         128
  169.              Version                         129
  170.              WinClose                        132
  171.  
  172.           APPENDIX A  Browser                146
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                                                             iv
  184.  
  185.                                                                   INTRODUCTION
  186.  
  187.  
  188.                                       INTRODUCTION
  189.  
  190.           Command Post 7.0 helps you end some of the drudgery of day-to-day
  191.           tasks when working in Microsoft Windows.
  192.  
  193.           How many times have we tired of changing drives, moving through two
  194.           subdirectories, finding an executable file from among 43 other
  195.           filenames, double clicking on it, selecting File/Open, then
  196.           searching for another directory in the listbox because our document
  197.           happens to be in a different directory than the program!  With
  198.           Command Post you can automate that knowledge of where to move
  199.           around the disk, which directories to go to, which files you want
  200.           to work on, what size you prefer your window to be, and so on.
  201.  
  202.  
  203.           System Requirements
  204.           Command Post 7.0 requires an IBM PC or compatible with a minimum of
  205.           640k memory running Microsoft Windows version 2.03 or higher.
  206.  
  207.  
  208.  
  209.           About This Manual
  210.           This manual is divided into five sections:  First is Getting
  211.           Started (pg. 1), where we tell you how to install the program.
  212.           Then we offer a Ten-Minute Tour of the default File Manager window
  213.           (pg. 3).  Next is an introduction to creating Your Own Menus (pg.
  214.           25), after which you can start making your own individual routine
  215.           easier.
  216.           Then we go into a full description of the Command Post Menu
  217.           Language (CPML) (pg. 33), and a comprehensive CPML Function
  218.           Reference (pg. 47) to assist you in making more complex and
  219.           intelligent menus.
  220.  
  221.  
  222.  
  223.           Notational Conventions
  224.           Throughout this manual, we use the following conventions to
  225.           distinguish elements of text:
  226.           ALL-CAPS
  227.              Used for filenames.
  228.  
  229.           Boldface
  230.              Used for important points, programs, function names, and parts of
  231.              syntax that must appear as shown.
  232.           System
  233.              Used for menu names as they appear to the user.
  234.  
  235.           Small fixed-width
  236.              Used for menu program sample code.
  237.  
  238.  
  239.                                                                              v
  240.  
  241.                                                                   INTRODUCTION
  242.  
  243.           Our thanks to the many beta-testers for their invaluable comments &
  244.           suggestions.
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.                                                                             vi
  290.  
  291.                                                               GETTING  STARTED
  292.  
  293.  
  294.  
  295.                                                                 YOUR OWN MENUS
  296.  
  297.  
  298.                                      YOUR OWN MENUS
  299.  
  300.  
  301.           Custom menus are your chance to put Command Post to work in just
  302.           the way you want.  They allow you to change directories and launch
  303.           applications with just the parameters you need - all from a simple
  304.           menu choice. You can offer options to the user and save yourself
  305.           (and others) the task of memorizing your disk layout. There are
  306.           many possibilities, but we'll start with the simplest and probably
  307.           most useful task, starting programs, after examining the menu file.
  308.  
  309.  
  310.           What is a Menu File?
  311.           Menus are defined in ASCII text files (the kind created by Notepad)
  312.           with the extension .CPM.
  313.  
  314.           If you don't specify a .CPM filename when you run Command Post, it
  315.           uses the default menu file CMDPOST.CPM.  You can also bring up
  316.           another copy of Command Post using a different menu file by double-
  317.           clicking on any .CPM filename from within Command Post.
  318.           Every menu file contains menu names which show up on the Command
  319.           Post menu bar, and menu items in the dropdown menus. For each menu
  320.           item you'll have one or more lines of commands which Command Post
  321.           will execute when you choose that item. Your menu will "feel" just
  322.           like a regular Windows menu, but it will manage things in a way
  323.           tailored to suit your needs.
  324.  
  325.  
  326.  
  327.           How to Create a Simple Menu
  328.           Let's assume you want to keep the default menus Command Post gives
  329.           you and add your own onto the end of the menu bar.
  330.           CMDPOST.CPM contains the definitions for the File, Dir, View, and
  331.           Main menus.  It calls another menu file, CMDUSER.CPM, for the
  332.           custom menus.  CMDPOST.CPM contains some very complex programming
  333.           and is worth taking a look at sometime.  For now however let's just
  334.           stick to modifying CMDUSER.CPM.
  335.  
  336.           Using Windows Notepad, open the CMDUSER.CPM file.  You can do this
  337.           by selecting Edit CPM Files from the Main menu.  Scroll down to the
  338.           end of the file.  We're going to add a new menu specifically for
  339.           desktop publishing applications.
  340.           First off, let's name our new menu. Starting in the first column
  341.           (at the far left), type:
  342.  
  343.           &DTP Apps
  344.  
  345.  
  346.                                                                             25
  347.  
  348.                                                                 YOUR OWN MENUS
  349.  
  350.           Because it begins in column 1, this entry defines a menu name.  The
  351.           "&" is optional--it defines an Alt-key combination for the entry;
  352.           Alt-D in this example.  It will appear on the Command Post menu bar
  353.           as "DTP Apps"..
  354.           Since we intend to use PageMaker for our projects, we'll define a
  355.           menu item which lets us launch it. On the next line, beginning in
  356.           the second column (one space in), type:
  357.  
  358.            &PageMaker 4.0
  359.  
  360.           Since it begins in column 2, Command Post knows it defines a
  361.           dropdown menu item. Below this menu item we will enter the commands
  362.           which let you launch PageMaker.  These begin in column 5 or more
  363.           (or you can tab once).  There are almost a hundred functions and
  364.           commands in the Command Post Menu Language(CPML), but it takes only
  365.           a few to get started.
  366.  
  367.           Well, what did we do to start PageMaker before we had Command Post?
  368.           We had to make sure we're in the proper drive, find the PageMaker
  369.           executable file, and doubleclick or run it.  We can put those steps
  370.           in our PageMaker menu with the DirChange and Run functions:
  371.           &DTP Apps
  372.            &PageMaker 4.0
  373.               DirChange("d:\pm\docs")
  374.               Run("pm.exe","")
  375.  
  376.  
  377.           DirChange("d:\pm\docs") tells Command Post to change to the D:
  378.           drive and find the \PM\DOCS subdirectory. Run("pm.exe", "") tells
  379.           Command Post to launch the PM.EXE application, with no parameters
  380.           passed to it.
  381.           Our simple menu is complete.  Now save the file and exit Notepad.
  382.           Then choose Reload Menu from Command Post's system menu box so our
  383.           new menu will take effect.
  384.  
  385.  
  386.  
  387.           Enhancing Our Menu
  388.           Let's imagine that we have a special publishing project ("The
  389.           Waldorf Salad Cookbook" - should sell millions) that we've been
  390.           working on over a series of months. It has its own subdirectory,
  391.           D:\PM\WALDORF, and several PageMaker files - CHPTR1.PM4,
  392.           CHPTR2.PM4, etc.  We would like to have a separate menu item for
  393.           each chapter so we can start PageMaker with the chapter already
  394.           loaded. We always use PageMaker at full-screen, so we'd rather not
  395.           have to press the Maximize box whenever the program starts.  Also,
  396.           we would like to launch the CLIPBRD.EXE utility as an icon, since
  397.           we check the clipboard often.  Let's create the first menu item ,
  398.           which will follow the generic PageMaker 4.0 item we created above.
  399.           Since this is a submenu item, it starts in column 2:
  400.  
  401.  
  402.                                                                             26
  403.  
  404.                                                                 YOUR OWN MENUS
  405.  
  406.            PM-&Waldorf
  407.               DirChange ("d:\pm\waldorf")
  408.               RunZoom ("pm.exe", "chptr1.pm4")
  409.               RunIcon ("clipbrd.exe","")
  410.  
  411.           Our menu item now does a lot of  work for us.  The RunZoom command
  412.           has a new parameter, "chptr1.pm4", which tells PageMaker which file
  413.           to load when it starts up.  The command RunIcon launches the
  414.           Clipboard viewer as an icon.
  415.  
  416.           We could define more menu items for the other chapters, and find
  417.           ourselves getting to work faster and easier than before.  Not to
  418.           mention helping other people work on the project without getting
  419.           lost in our particular directory structure.
  420.  
  421.  
  422.           An Enhancement for Safety
  423.           After spending 45 hours on CHPTR1.PM4, we start to worry a bit
  424.           about losing our work.  We decide to make a diskette backup of our
  425.           chapter at the beginning of each session.  We'll make it a part of
  426.           the menu!  It now looks like this:
  427.  
  428.            PM-Waldorf Ch &1
  429.               DirChange ("d:\pm\waldorf")
  430.               ;Backup the current file first...
  431.               Pause ("Backup Chapter 1","Put Backup disk in Drive A:")
  432.               FileCopy ("Chptr1.pm4","a:chptr1.pm4",@FALSE)
  433.               RunZoom ("pm.exe", "chptr1.pm4")
  434.               RunIcon ("clipbrd.exe","")
  435.  
  436.           Our menu changes to the proper directory, and now displays a dialog
  437.           box with the title "Backup Chapter 1", prompting the user to "Put
  438.           Backup disk in Drive A:".  The Pause function also creates OK and
  439.           Cancel buttons which let the user get out of the menu item (where
  440.           did I put that disk???) or continue.  If OK is clicked, FileCopy
  441.           copies the source file CHPTR1.PM4 to the destination A:CHPTR1.PM4.
  442.           The @FALSE is a CPML constant which specifies that we do not want
  443.           to prompt the user if the file already exists in the target
  444.           directory.
  445.  
  446.           It's a good idea to put comments in the file when you're trying to
  447.           accomplish something complex.  Comments start with a semicolon; the
  448.           rest of the line is ignored.
  449.           This menu item is getting a bit complicated, but look at what we've
  450.           accomplished. You've automated the backup process, and made it hard
  451.           to forget. You don't have to memorize all those manual steps, and
  452.           you don't have to teach them to others. Menus make your life
  453.           easier, and in this case let you sleep easier too!
  454.  
  455.  
  456.  
  457.  
  458.                                                                             27
  459.  
  460.                                                                 YOUR OWN MENUS
  461.  
  462.           The Major Functions
  463.           There are almost a hundred functions and commands that make up
  464.           CPML.  But you can create powerful custom menus right away with
  465.           these eleven:
  466.  
  467.  
  468.           Running a Program
  469.           You can launch applications in a number of ways:
  470.  
  471.           RunIcon (program-name, parameters)
  472.           Starts a program as an icon at the bottom of the screen.  (See pg.
  473.           107)
  474.  
  475.           Example:
  476.           &Utilities
  477.            &Clock
  478.              RunIcon ("Clock", "")
  479.  
  480.  
  481.           Run (program-name, parameters)
  482.           Starts a program in a "normal" window.  Windows decides where to
  483.           place the application's  window on the screen.  (See pg. 105)
  484.           Example:
  485.           &Word Processing
  486.            Edit &MyFile
  487.              Run ("Notepad", "myfile.txt")
  488.  
  489.  
  490.           RunZoom (program-name, parameters)
  491.           Starts a program as a full-screen window.  (See pg. 108)
  492.  
  493.           Example:
  494.           &Accounting
  495.            The &BIG spreadsheet
  496.              RunZoom ("Excel", "bigsheet.xls")
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.                                                                             28
  515.  
  516.                                                                 YOUR OWN MENUS
  517.  
  518.  
  519.  
  520.           Getting Information from the User
  521.           Often you need to have the user enter extra information before you
  522.           can process a menu request.  Here are the simplest ways to do that:
  523.  
  524.           AskYesNo (title, question)
  525.           Displays a dialog box with a given title, posing a question to the
  526.           user, who may click a Yes, No, or Cancel button.  (See pg. 50)
  527.  
  528.           Example:
  529.           &Utilities
  530.            Delete MyFile...
  531.              Cont = AskYesNo ("My Menu", "You REALLY want to do this?")
  532.              Terminate (Cont==@NO, "", "")
  533.              FileDelete ("MyFile.txt")
  534.  
  535.  
  536.           AskLine (title, prompt, default)
  537.           Displays a dialog box with a given title, which prompts the user
  538.           for a line of input.  Returns the default if the user just presses
  539.           the OK button.  (See pg. 48)
  540.           Example:
  541.           &Word Processing
  542.            &Edit a file...
  543.              TheFile = AskLine ("Edit File", "Filename:", CurrentFile())
  544.              Run ("Notepad", TheFile)
  545.  
  546.  
  547.           ItemSelect (title, list, delimiter)
  548.           Displays a listbox filled with items from a list you specify in a
  549.           string.  The items are separated in your string by a delimiter
  550.           character.  Very useful in conjunction with FileItemize,
  551.           DirItemize, and WinItemize.  (See pg. 91)
  552.  
  553.           Example:
  554.           &DTP Apps
  555.            PM-&Waldorf Project
  556.              DirChange ("d:\pm\waldorf")
  557.              WFiles = FileItemize ("chptr*.pm4")
  558.              TheFile = ItemSelect ("Select A Chapter", WFiles, " ")
  559.              RunZoom ("pm.exe", TheFile)
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.                                                                             29
  571.  
  572.                                                                 YOUR OWN MENUS
  573.  
  574.  
  575.  
  576.           Displaying Information
  577.           It's easy to display information to the user:
  578.  
  579.           Message (title, text)
  580.           This command displays a message box with a title and text you
  581.           specify, until the user presses the OK button.  (See pg. 97)
  582.  
  583.           Example:
  584.           &Miscellany
  585.            Show &Date && Time
  586.              DT = DateTime ()
  587.              Message ("Current Date & Time", "It is now %DT%")
  588.  
  589.  
  590.           Pause (title, text)
  591.           This command is similar to Message except an exclamation-point icon
  592.           appears in the message box, and the user can press OK or Cancel.
  593.           If they press Cancel, the menu item exits.  (See pg. 103)
  594.           Example:
  595.           &Daily Utilities
  596.            &Delete .BAK files
  597.              Pause ("Delete Backups", "Last chance to stop!")
  598.              ;if it gets this far, they pressed OK...
  599.              FileDelete ("*.bak")
  600.  
  601.  
  602.           Terminate (expression, title, message)
  603.           This command stops processing the menu item if the expression is
  604.           true.  If either the title or the message are not null strings
  605.           (""), then a message box is displayed to alert the user to what has
  606.           happened.  (See pg. 122)
  607.  
  608.           Example:
  609.           &Restricted Operations
  610.            &Payroll History
  611.              UsersPW = AskLine ("*RESTRICTED*","Enter your password:","")
  612.              ;assuming executive's password already saved in WIN.INI:
  613.              RealPW = IniRead ("MyCompany", "Executive PW", "")
  614.              Terminate (UsersPW!=RealPW, "ERROR", "Wrong Password!")
  615.  
  616.              ;if they got this far, they gave correct password:
  617.              RunZoom ("Excel.exe", "Personel.xls")
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.                                                                             30
  627.  
  628.                                                                 YOUR OWN MENUS
  629.  
  630.  
  631.  
  632.           Other Useful Functions
  633.  
  634.           CurrentFile ( )
  635.           Returns the name of the selected file (the one with the dotted
  636.           rectangle around it) from the Command Post window.  (See pg. 57)
  637.           Example:
  638.           &Editing
  639.            Run &Notepad with selected file
  640.              Run ("Notepad", CurrentFile())
  641.  
  642.  
  643.           DirChange (pathname)
  644.           Changes the directory to the pathname specified.  (See pg. 62)
  645.  
  646.           Example:
  647.           &Miscellany
  648.            &Run some program not in path
  649.              DirChange ("c:\some\dir\not\in\path")
  650.              Run ("Obscure.exe","")
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.                                                                             31
  683.  
  684.                                                     COMMAND POST MENU LANGUAGE
  685.  
  686.  
  687.                                COMMAND POST MENU LANGUAGE
  688.  
  689.  
  690.  
  691.           Menu Structure
  692.           Menus are defined in a menu file.  Each menu file consists of one
  693.           or more lines of menu statements.  Each line is terminated with a
  694.           carriage return / line feed (CRLF) combination and can be up to 256
  695.           characters long.
  696.  
  697.           There are two main parts of a menu file:
  698.           The first section, which is optional, is the initialization code.
  699.           This section is executed once when the menu is first loaded and
  700.           run.  It's located before the first menu item declaration.
  701.  
  702.           The remainder of the menu file consists of menu item titles and
  703.           their associated statements.  The code under each menu title is
  704.           executed when the corresponding menu item is selected.  Execution
  705.           begins at the first statement under a menu item and continues up to
  706.           the definition of the next item.
  707.  
  708.  
  709.           Menu Items
  710.           Menu titles can consist of letters, digits, spaces, punctuation
  711.           marks; in fact any displayable ANSI characters your text editor can
  712.           create.
  713.  
  714.           There are special characters you can use to modify the appearance
  715.           of items in the menus.
  716.           &  Causes the following character to be underlined in the menu item.
  717.           The user can select the item by pressing the ALT key with the
  718.           character instead of using the mouse.
  719.  
  720.           |  In a main menu, puts this item on a new line.
  721.           |  In a dropdown menu, this item starts a new column.
  722.           _  Used to create a horizontal bar (in dropdown menus only).
  723.           Most CPML commands carry out functions based on your menu
  724.           selections.  However there are a few functions (summarized on pg.
  725.           42) that can alter the characteristics of the menu titles
  726.           themselves.  For instance you can put a checkmark next to a menu,
  727.           or disable and gray it.
  728.  
  729.           In order to identify a menu item within a CPML statement, each menu
  730.           item you define has an associated menu name.  The menu name is
  731.           built using only the letters and digits that make up the menu
  732.           title.  Menu names are case-insensitive; you don't have to worry
  733.           about how the actual menu title is capitalized in order to identify
  734.           it.
  735.  
  736.  
  737.  
  738.                                                                             33
  739.  
  740.                                                     COMMAND POST MENU LANGUAGE
  741.  
  742.           For menu items in a popup menu, the menu name consists of its
  743.           parent menu's name, plus the popup menu item's name concatenated at
  744.           the end.
  745.           These menu names are valid as soon as the menu file is loaded, so
  746.           you can use the menu management functions in the initialization
  747.           code before the menus even appear.
  748.  
  749.           Example:
  750.              PW=AskLine ("","Enter your password:", "")
  751.              ;assuming the resident guru's pw is already in WIN.INI:
  752.              RealPW = IniRead ("Our Company", "Tech Guru PW", "")
  753.              Terminate (PW==RealPW, "Access", "You have FULL access")
  754.  
  755.              MenuChange("SystemUtilitiesCleanupDir",  @DISABLE)
  756.              MenuChange("SystemUtilitiesEditBatFiles",@DISABLE)
  757.              MenuChange("SystemUtilitiesEditWinIni",  @DISABLE)
  758.              Message ("Access", "You have LIMITED access")
  759.  
  760.           &System Utilities  ;name = "SystemUtilities"
  761.            &Cleanup Dir      ;name = "SystemUtilitiesCleanupDir"
  762.              ...
  763.            &Edit BAT Files...;name = "SystemUtilitiesEditBatFiles"
  764.              ...
  765.            &Edit WIN.INI     ;name = "SystemUtilitiesEditWinIni"
  766.              ...
  767.  
  768.  
  769.           Language Components
  770.           The statements you write to execute the menu items are constructed
  771.           from constants, variables, operators, functions, commands, and
  772.           comments.
  773.  
  774.  
  775.           Constants
  776.           The programming language supports both integer and string
  777.           constants.
  778.  
  779.  
  780.           Integer Constants
  781.           Integer constants are built from the digits 0 through 9.  They can
  782.           range in magnitude from negative to positive 231 -1  (approximately
  783.           two billion).  Constants larger than these permissible magnitudes
  784.           will produce unpredictable results.
  785.           Examples of integer constants:
  786.                       1
  787.                     -45
  788.                  377849
  789.             -1999999999
  790.  
  791.  
  792.  
  793.  
  794.                                                                             34
  795.  
  796.                                                     COMMAND POST MENU LANGUAGE
  797.  
  798.           String Constants
  799.           String constants are comprised of displayable characters bounded by
  800.           quote marks.  You can use double quotes ("), single quotes ('), or
  801.           back quotes (`) to enclose a string constant, as long as the same
  802.           type of quote is used to both start and end it.  If you need to
  803.           imbed the delimiting quote mark inside the string constant, use the
  804.           delimiting quote mark twice.
  805.           Examples of string constants:
  806.              "a"
  807.              `Betty Boop`
  808.              "This constant has an imbedded "" mark"
  809.              'This constant also has an imbedded " mark'
  810.  
  811.           Predefined Constants
  812.           The programming language has a number of built-in integer constants
  813.           that can be used for various purposes.  These start with the @-
  814.           sign, and are case-insensitive (although we prefer to use ALL
  815.           CAPS).
  816.  
  817.           Some predefined constants:
  818.              @FALSE                             @TILE
  819.              @NO                                @TRUE
  820.              @STACK                             @YES
  821.  
  822.           A list of all the predefined constants can be found in Appendix D:
  823.           Predefined Constants.
  824.  
  825.  
  826.  
  827.           Identifiers
  828.           Identifiers are the names supplied for variables, functions, and
  829.           commands in your program.
  830.           An identifier is a sequence of one or more letters or digits that
  831.           begins with a letter.  Identifiers may have up to 30 characters.
  832.  
  833.           All identifiers are case insensitive.  Upper- and lowercase charac-
  834.           ters may be mixed at will inside variable names, commands or
  835.           functions.
  836.           For example these statements all mean the same thing:
  837.              AskLine (MyTitle, Prompt, Default)
  838.              ASKLINE (MYTITLE, PROMPT, DEFAULT)
  839.              aSkLiNe (MyTiTlE, pRoMpT, dEfAuLt)
  840.  
  841.  
  842.           Variables
  843.           A variable may contain an integer, a string, or a string
  844.           representing an integer.  Automatic conversions between integers
  845.           and strings are performed as a matter of course during execution.
  846.  
  847.  
  848.  
  849.  
  850.                                                                             35
  851.  
  852.                                                     COMMAND POST MENU LANGUAGE
  853.  
  854.           If a function requires a string argument and an integer argument is
  855.           supplied, the variable will be automatically modified to include
  856.           the representative string.
  857.           If a function requires an integer argument and a string argument is
  858.           supplied, an attempt will be made to convert the string to an inte-
  859.           ger.  If it does not convert successfully, an error will result.
  860.  
  861.  
  862.  
  863.           Keywords Are Reserved
  864.           "Keywords" are the predefined identifiers that have special meaning
  865.           to the programming language.  These cannot be used as variable
  866.           names.
  867.           CPML keywords consist of the functions, commands, and predefined
  868.           constants.
  869.  
  870.           Some examples of reserved keywords:
  871.              beep
  872.              dirchange
  873.              @Yes
  874.              filecopy
  875.  
  876.  
  877.           Operators
  878.           The programming language operators take one operand ("unary
  879.           operators") or two operands ("binary operators").
  880.           Unary operators (integers only):
  881.              -    Arithmetic Negation (Two's complement)
  882.              +    Identity (Unary plus)
  883.              ~    Bitwise Not.  Changes each 0 bit to 1, and vice-versa.
  884.              !    Logical Not.  Produces 0 (@FALSE) if the operand is
  885.                   nonzero, else 1 (@TRUE) if the operand is zero.
  886.  
  887.  
  888.           Binary arithmetic operators (integers only):
  889.              *    Multiplication
  890.              /    Division
  891.              mod  Modulo
  892.              +    Addition
  893.              -    Subtraction
  894.              <<   Left Shift
  895.              >>   Right Shift
  896.              &    Bitwise And
  897.              |    Bitwise Or
  898.              ^    Bitwise Exclusive Or  (XOR)
  899.              &&   Logical And
  900.              | |  Logical Or
  901.  
  902.           Binary relational operators (integers and strings):
  903.              >      Greater-than
  904.              >=     Greater-than or equal
  905.  
  906.                                                                             36
  907.  
  908.                                                     COMMAND POST MENU LANGUAGE
  909.  
  910.              <      Less-than
  911.              <=     Less-than or equal
  912.              ==     Equality
  913.              != or <>Inequality
  914.           Assignment operator (integers and strings):
  915.              =      Assigns evaluated result of an expression to a variable
  916.  
  917.  
  918.  
  919.           Precedence and evaluation order
  920.           The precedence of the operators affect the evaluation of operands
  921.           in expressions.  Operands associated with higher-precedence
  922.           operators are evaluated before the lower-precedence operators.
  923.           The table below shows the precedence of the operators.  Where
  924.           operators have the same precedence, they are evaluated from left to
  925.           right.
  926.  
  927.           Operator            Description
  928.              ( )              Parenthetical grouping
  929.              ~ ! - +          Unary operators
  930.              * / mod          Multiplication & Division
  931.              + -              Addition & Subtraction
  932.              <<  >>           Shift operators
  933.              < <= == >= > != <>   Relational operators
  934.              & ^ |            Bit manipulation operators
  935.              && | |           Logical operators
  936.  
  937.  
  938.           Comments
  939.           A comment is a sequence of characters that are ignored when
  940.           processing a menu item.  A semicolon (not otherwise part of a
  941.           string constant) indicates the beginning of a comment.
  942.           All characters to the right of the semicolon are considered
  943.           comments and are ignored.
  944.  
  945.           Blank lines are also ignored.
  946.           Examples of comments:
  947.              ;This is a comment
  948.              abc=5  ;This is also a comment
  949.  
  950.  
  951.           Statements
  952.           The statements of a menu specify what to do when the menu item is
  953.           selected.
  954.  
  955.  
  956.           Assignment Statements
  957.           Assignment statements are used to set variables to specific or
  958.           computed values.  Variables may be set to integers or strings.
  959.  
  960.  
  961.  
  962.                                                                             37
  963.  
  964.                                                     COMMAND POST MENU LANGUAGE
  965.  
  966.           Examples:
  967.              a=5
  968.              value=Average(a,10,15)
  969.              location="Northern Hemisphere"
  970.              World = strcat(location," ","Southern Hemisphere")
  971.  
  972.           Control Statements
  973.           Control statements are generally used to execute system management
  974.           functions and consist of a call to a command without assigning any
  975.           return values.
  976.           Examples:
  977.              run("clock.exe","")
  978.              delay(5)
  979.              winclose("Clock")
  980.              Exit
  981.  
  982.  
  983.           Substitution
  984.           The menu language has a powerful substitution feature which inserts
  985.           the contents of a string variable into a statement before the line
  986.           is parsed.
  987.  
  988.           To substitute the contents of a variable in the statement, simply
  989.           put a percent-sign (%) on both sides of the variable name.
  990.           Examples:
  991.              MyCmd="DirChange('C:\')"   ;set MyCmd to a command
  992.              %MyCmd%               ;execute the command
  993.  
  994.           ...or consider this one:
  995.  
  996.              IniWrite ("PC", "Owner", "Jenny")
  997.              ...
  998.              Owner = IniRead ("PC", "Owner", "somebody")
  999.              message ("", "This is %Owner%'s PC")
  1000.  
  1001.           will produce this message box:
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.           To put a single percent-sign (%) on a source line, specify a double
  1010.           percent sign(%%).  This is required even inside quoted strings.
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.                                                                             38
  1019.  
  1020.                                                     COMMAND POST MENU LANGUAGE
  1021.  
  1022.  
  1023.           Language Directives
  1024.           A "language directive" is a command to the CPML interpreter, as
  1025.           opposed to a menu statement.  These begin with a pound-sign ("#")
  1026.           in column 1.
  1027.           Currently there is only one directive recognized by Command Post:
  1028.           #NextFile. This directive tells the CPML interpreter to append
  1029.           another .CPM file to the current one before building the menus.
  1030.           You can append only one extra menu file in this way.
  1031.  
  1032.  
  1033.  
  1034.           Function Parameters
  1035.           Most of the functions and commands in the language require
  1036.           parameters.  These come in three types:
  1037.              Integer
  1038.              String
  1039.              Variable name
  1040.  
  1041.           CPML performs automatic conversions between strings and integers,
  1042.           so in general you can use them interchangeably.
  1043.  
  1044.           Integer parameters may be any of the following:
  1045.              An integer (i.e. 23)
  1046.              A string representing an integer (i.e. "23")
  1047.              A variable containing an integer
  1048.              A variable containing a string representing an integer
  1049.  
  1050.           String parameters may be any of the following:
  1051.              A string
  1052.              An integer
  1053.              A variable containing a string
  1054.              A variable containing an integer
  1055.  
  1056.  
  1057.  
  1058.           Error Handling
  1059.           There are three types of errors that can occur while processing a
  1060.           menu item:  Minor, Moderate, and Fatal.  What happens when an error
  1061.           occurs depends on the current error mode, which is set with the
  1062.           ErrorMode function.
  1063.           There are three possible modes you can specify:
  1064.  
  1065.           @CANCEL
  1066.              User is notified when any error occurs, and then the menu item is
  1067.              cancelled.  This is the default.
  1068.           @NOTIFY
  1069.              User is notified when any error occurs, and has option to
  1070.              continue unless the error is fatal.
  1071.  
  1072.  
  1073.  
  1074.                                                                             39
  1075.  
  1076.                                                     COMMAND POST MENU LANGUAGE
  1077.  
  1078.           @OFF
  1079.              User is only notified if the error is moderate or fatal.  User
  1080.              has option to continue unless the error is fatal.
  1081.           The function LastError returns the code of the most-recent error
  1082.           encountered during the current menu item.
  1083.  
  1084.           Minor errors are numbered from 1000 to 1999.
  1085.           Moderate errors are numbered from 2000 to 2999.
  1086.           Fatal errors are numbered from 3000 to 3999.
  1087.           Error handling is reset to @CANCEL at the start of each menu item.
  1088.  
  1089.  
  1090.  
  1091.           The Functions & Statements
  1092.  
  1093.  
  1094.           Inputting Information
  1095.           AskLine (title, prompt, default)
  1096.              Lets user enter a line of information.
  1097.           AskYesNo (title, question)
  1098.              Lets user choose from Yes, No, or Cancel.
  1099.  
  1100.           ItemSelect (title, list, delimiter)
  1101.              Chooses an item from a listbox.
  1102.           TextBox (title, filename)
  1103.              Fills a listbox from text strings in a file.
  1104.  
  1105.  
  1106.  
  1107.           Displaying Information
  1108.           Beep
  1109.              Beeps at the user.
  1110.           Display (seconds, title, text)
  1111.              Momentarily displays a string.
  1112.  
  1113.           Message (title, text)
  1114.              Displays text in a message box.
  1115.           Pause (title, text)
  1116.              Displays text in a message box.
  1117.  
  1118.           Terminate (expression, title, message)
  1119.              Conditionally ends a menu operation, with a notice if desired.
  1120.  
  1121.  
  1122.           File Management
  1123.           CurrentFile ( )
  1124.              Returns the selected file or subdirectory name.
  1125.  
  1126.           FileCopy (from-list, to-file, warning)
  1127.              Copies files.
  1128.  
  1129.  
  1130.                                                                             40
  1131.  
  1132.                                                     COMMAND POST MENU LANGUAGE
  1133.  
  1134.           FileDelete (file-list)
  1135.              Deletes files.
  1136.           FileExist (filename)
  1137.              Determines if a file exists.
  1138.  
  1139.           FileItemize (file-list)
  1140.              Builds a list of files.
  1141.           FileLocate (filename)
  1142.              Finds a file within the current DOS path.
  1143.  
  1144.           FileMove (from-list, to-file, warning)
  1145.              Moves files to another set of pathnames.
  1146.           FileRename (from-list, to-file)
  1147.              Renames files to another set of names.
  1148.  
  1149.           FileSize (file-list)
  1150.              Adds up the total size of a set of files.
  1151.  
  1152.  
  1153.           Directory Management
  1154.           DirChange ([d:]path)
  1155.              Changes the current directory.
  1156.  
  1157.           DirGet ( )
  1158.              Returns the current directory path.
  1159.           DirHome ( )
  1160.              Returns the initial directory path.
  1161.  
  1162.           DirItemize (dir-list)
  1163.              Builds a list of directories.
  1164.           DirMake ([d:]path)
  1165.              Creates a new directory.
  1166.  
  1167.           DirRemove ([d:]path)
  1168.              Removes an existing directory.
  1169.  
  1170.  
  1171.           Disk Drive Management
  1172.           DiskFree (drive-list)
  1173.              Returns the amount of free space on a set of drives.
  1174.  
  1175.           LogDisk (drive)
  1176.              Changes the logged disk drive.
  1177.  
  1178.  
  1179.           Window Management
  1180.           WinActivate (partial-windowname)
  1181.              Makes an application window the active window.
  1182.  
  1183.           WinArrange (style)
  1184.              Arranges all running application windows on the screen.
  1185.  
  1186.                                                                             41
  1187.  
  1188.                                                     COMMAND POST MENU LANGUAGE
  1189.  
  1190.           WinClose (partial-windowname)
  1191.              Closes an application window.
  1192.           WinCloseNot (partial-windowname [, partial-windowname]...)
  1193.              Closes all application windows except those specified.
  1194.  
  1195.           WinGetActive ( )
  1196.              Gets the title of the active window.
  1197.           WinHide (partial-windowname)
  1198.              Hides an application window.
  1199.  
  1200.           WinIconize (partial-windowname)
  1201.              Turns an application window into an icon.
  1202.           WinItemize ( )
  1203.              Lists all the main windows currently running.
  1204.  
  1205.           WinPlace (x-ul, y-ul, x-br, y-br, partial-windowname)
  1206.              Changes the size and position of an application window on the
  1207.              screen.
  1208.           WinShow (partial-windowname)
  1209.              Shows a currently-hidden application window.
  1210.  
  1211.           WinTitle (partial-windowname, new-windowname)
  1212.              Changes the title of an application window.
  1213.           WinWaitClose (partial-windowname)
  1214.              Waits until an application window is closed.
  1215.  
  1216.           WinZoom (partial-windowname)
  1217.              Maximizes an application window to full-screen.
  1218.  
  1219.  
  1220.           Menu Management
  1221.           IsMenuChecked (menuitem-name)
  1222.              Determines if a menuitem is checked.
  1223.  
  1224.           IsMenuEnabled (menuitem-name)
  1225.              Determines if a menuitem is enabled.
  1226.           MenuChange (menuitem-name, flags)
  1227.              Modifies displayed characteristics of a menuitem.
  1228.  
  1229.  
  1230.  
  1231.           Program Management
  1232.           Run (program-name, parameters)
  1233.              Runs a program as a normal window.
  1234.           RunHide (program-name, parameters)
  1235.              Runs a program in a hidden window.
  1236.  
  1237.           RunIcon (program-name, parameters)
  1238.              Runs a program as an icon.
  1239.           RunZoom (program-name, parameters)
  1240.              Runs a program in a maximized window.
  1241.  
  1242.                                                                             42
  1243.  
  1244.                                                     COMMAND POST MENU LANGUAGE
  1245.  
  1246.  
  1247.           String Handling
  1248.           Char2Num (string)
  1249.              Returns the ANSI code of a string's first character.
  1250.           IsNumber (string)
  1251.              Determines if a string represents a valid number.
  1252.  
  1253.           Num2Char (number)
  1254.              Converts a number to the ANSI character it represents.
  1255.           StrCat (string[, string]...)
  1256.              Concatenates strings together.
  1257.  
  1258.           StrCmp (string1, string2)
  1259.              Compares two strings.
  1260.           StrFill (string, string-length)
  1261.              Builds a string from a repeated smaller string.
  1262.  
  1263.           StrFix (base-string, padding-string, length)
  1264.              Pads or truncates a string to a fixed length.
  1265.           StrICmp (string1, string2)
  1266.              Compares two strings, ignoring their case.
  1267.  
  1268.           StrIndex (main-str, sub-str, start, direction)
  1269.              Locates a string within a larger string.
  1270.           StrLen (string)
  1271.              Returns the length of a string
  1272.  
  1273.           StrLower (string)
  1274.              Converts a string to all lower-case characters.
  1275.           StrScan (main-str, delims, start, direction)
  1276.              Finds an occurrence of one or more delimiter characters in a
  1277.              string.
  1278.  
  1279.           StrSub (string, start, length)
  1280.              Returns a substring from within a string.
  1281.           StrTrim (string)
  1282.              Trims leading and trailing blanks from a string.
  1283.  
  1284.           StrUpper (string)
  1285.              Converts a string to all upper-case characters.
  1286.  
  1287.  
  1288.           Arithmetic Functions
  1289.           Abs (number)
  1290.              Returns the absolute value of a number.
  1291.  
  1292.           Average (num [, num]...)
  1293.              Returns the average of a list of integers.
  1294.           Max (num [, num]...)
  1295.              Determines the highest number in a list.
  1296.  
  1297.  
  1298.                                                                             43
  1299.  
  1300.                                                     COMMAND POST MENU LANGUAGE
  1301.  
  1302.           Min (num [, num]...)
  1303.              Determines the lowest number in a list.
  1304.           Random (max)
  1305.              Generates a positive random number.
  1306.  
  1307.  
  1308.  
  1309.           Clipboard Handling
  1310.           ClipAppend (string)
  1311.              Appends a string to the end of the Clipboard.
  1312.           ClipGet ( )
  1313.              Returns the Clipboard contents into a string.
  1314.  
  1315.           ClipPut (string)
  1316.              Replaces the Clipboard contents with a string.
  1317.  
  1318.  
  1319.           System Control
  1320.           DateTime ( )
  1321.              Returns the current date and time.
  1322.  
  1323.           Debug (@ON | @OFF)
  1324.              Turns Debug mode on or off.
  1325.           Delay (seconds)
  1326.              Pauses menu execution.
  1327.  
  1328.           Drop (var [, var]...)
  1329.              Deletes variables to recover their memory.
  1330.           EndSession ( )
  1331.              Ends the current Windows session.
  1332.  
  1333.           Environment (env-variable)
  1334.              Returns the value of a DOS environment variable.
  1335.           ErrorMode (mode)
  1336.              Sets what happens in the event of an error.
  1337.  
  1338.           Execute statement
  1339.              Directly executes a Command Post statement.
  1340.           Exit
  1341.              Exits the current menuitem's operation.
  1342.  
  1343.           IniRead (section, keyname, default)
  1344.              Reads a string from the win.ini file.
  1345.           IniWrite (section, keyname, string)
  1346.              Writes a string to the win.ini file.
  1347.  
  1348.           IsDefined (variable)
  1349.              Determines if a variable is currently defined.
  1350.           IsRunning ( )
  1351.              Determines if another copy of Command Post is running.
  1352.  
  1353.  
  1354.                                                                             44
  1355.  
  1356.                                                     COMMAND POST MENU LANGUAGE
  1357.  
  1358.           LastError ( )
  1359.              Returns the last error encountered.
  1360.           #NextFile  filename
  1361.              Links a second Command Post menu file onto the one invoked.
  1362.  
  1363.           OtherDir ( )
  1364.              Finds the directory of the "other" running Command Post.
  1365.           OtherUpdate ( )
  1366.              Updates other running Command Post's display.
  1367.  
  1368.           SetDisplay (detail-level, sort-by, masks)
  1369.              Changes how the Command Post File Manager lists files.
  1370.           Terminate (expression, title, message)
  1371.              Conditionally ends a menu operation, with a notice if desired.
  1372.  
  1373.           Version ( )
  1374.              Returns the version of Command Post currently running.
  1375.           WinVersion (which-level)
  1376.              Gets the version of Windows that is currently running.
  1377.  
  1378.           Yield
  1379.              Pauses menu processing so other applications can process some
  1380.              messages.
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.                                                                             45
  1411.  
  1412.                                                      CPML  FUNCTION  REFERENCE
  1413.  
  1414.  
  1415.                                           CPML
  1416.                                         FUNCTION
  1417.                                        REFERENCE
  1418.  
  1419.  
  1420.  
  1421.           Introduction
  1422.           CPML gives you almost a hundred functions and control statements,
  1423.           which we describe in detail in this section.
  1424.  
  1425.           We use a shorthand notation to indicate the syntax of the
  1426.           functions.
  1427.           Function names and other actual characters you type are in
  1428.           boldface.  Optional parameters are enclosed in square brackets "[
  1429.           ]".  When a function takes a variable number of parameters, the
  1430.           variable parts will be followed by ellipses ("...").
  1431.  
  1432.           Take for example string concatenation:
  1433.           StrCat (string[, string]...)
  1434.  
  1435.           This says that the StrCat function takes at least one string
  1436.           parameter.  Optionally you can specify more strings to concatenate.
  1437.           If you do, you must separate the strings with commas.
  1438.           For each function and control statement, we show you the Syntax,
  1439.           describe the Parameters (if any), the value it Returns (if any), a
  1440.           description of the function, any nonfatal Errors specific to the
  1441.           function, Example code (shown in courier type), and related
  1442.           functions you may want to See Also.
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.                                                                             47
  1467.  
  1468.                                                      CPML  FUNCTION  REFERENCE
  1469.  
  1470.  
  1471.  
  1472.           Abs
  1473.           Returns the magnitude of the argument.
  1474.  
  1475.           Syntax:
  1476.              Abs (integer)
  1477.  
  1478.           Parameters:
  1479.              "integer" = integer whose absolute value is desired.
  1480.  
  1481.           Returns:
  1482.              (integer) absolute value of argument.
  1483.  
  1484.  
  1485.           Example:
  1486.              DY=abs(y1-y2)
  1487.              Message("Years","There are %DY% years 'twixt %y1% and %y2%")
  1488.  
  1489.  
  1490.           See Also:
  1491.              Average, Max, Min
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.                                                                             48
  1523.  
  1524.                                                      CPML  FUNCTION  REFERENCE
  1525.  
  1526.  
  1527.  
  1528.           AskLine
  1529.           Prompts the user for one line of input.
  1530.  
  1531.           Syntax:
  1532.              AskLine (title, prompt, default)
  1533.  
  1534.           Parameters:
  1535.              "title" = title of the dialog box.
  1536.              "prompt" =  question to be put to the user.
  1537.              "default" = default answer.
  1538.  
  1539.           Returns:
  1540.              (string)  user response.
  1541.  
  1542.           Use this command to query the user for a line of data.  The entire
  1543.           user response will be returned if the user presses the OK button or
  1544.           the Enter key.  If they press Cancel, the menu item processing is
  1545.           cancelled.
  1546.  
  1547.  
  1548.           Example:
  1549.              Name=AskLine("Dessert","Please enter your name","")
  1550.              Dsrt=AskLine("Dessert","Favorite dessert?","Ice Cream")
  1551.              message(strcat(Name,"'s dessert is "),Dsrt)
  1552.  
  1553.           produces:
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.                                                                             49
  1579.  
  1580.                                                      CPML  FUNCTION  REFERENCE
  1581.  
  1582.           ...and then, if Jenny types "JELL-O" and presses OK:
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.           See Also:
  1593.              AskYesNo, Display, ItemSelect, Message, Pause, TextBox
  1594.  
  1595.  
  1596.  
  1597.  
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.                                                                             50
  1635.  
  1636.                                                      CPML  FUNCTION  REFERENCE
  1637.  
  1638.  
  1639.  
  1640.           AskYesNo
  1641.           Prompts the user for a YES or NO answer.
  1642.  
  1643.           Syntax:
  1644.              AskYesNo (title, question)
  1645.  
  1646.           Parameters
  1647.              "title" = title of the question box.
  1648.              "question" =question to be put to the user.
  1649.  
  1650.           Returns:
  1651.              (integer) @YES or @NO, depending on the button pressed.
  1652.  
  1653.           This command displays a message box with three pushbuttons - Yes,
  1654.           No, and Cancel.  If the user presses Cancel, the current menu item
  1655.           is ended so there is no return value.
  1656.  
  1657.  
  1658.           Example:
  1659.              q=AskYesNo('Testing','Please press "YES"')
  1660.              Terminate(q==@YES,"","")
  1661.              Display(3,'ERROR',"I said press 'YES'")
  1662.  
  1663.           produces:
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.           ...and if the user presses No:
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.           See Also:
  1680.              AskLine, Display, ItemSelect, Message, Pause, TextBox
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.                                                                             51
  1691.  
  1692.                                                      CPML  FUNCTION  REFERENCE
  1693.  
  1694.  
  1695.  
  1696.           Average
  1697.           Provides the integer average of the arguments.
  1698.           Syntax:
  1699.              Average (integer [, integer]...)
  1700.  
  1701.           Parameters:
  1702.              "integer" = integers to get the average of.
  1703.  
  1704.           Returns:
  1705.              (integer) average of the arguments.
  1706.  
  1707.           Use this command to compute the average of a series of numbers.
  1708.           This function returns an integer value, so there can be some
  1709.           rounding error involved.
  1710.  
  1711.  
  1712.           Errors:
  1713.              2060 "Average function syntax error"
  1714.  
  1715.           Example:
  1716.              Ave=Average(1,2,3,4,5,6,7,8,9,10,11,12,13)
  1717.              Message("The average is",Ave)
  1718.  
  1719.  
  1720.           See Also:
  1721.              Abs, Max, Min
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.                                                                             52
  1747.  
  1748.                                                      CPML  FUNCTION  REFERENCE
  1749.  
  1750.  
  1751.  
  1752.           Beep
  1753.           Beeps once.
  1754.  
  1755.           Syntax:
  1756.              Beep
  1757.  
  1758.  
  1759.           Use this command to produce a short beep, generally to alert the
  1760.           user to an error situation.
  1761.  
  1762.           Example:
  1763.              Beep
  1764.              Pause ("WARNING!!!", "You are about to destroy data!")
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.                                                                             53
  1803.  
  1804.                                                      CPML  FUNCTION  REFERENCE
  1805.  
  1806.  
  1807.  
  1808.           Char2Num
  1809.           Converts the first character of a string to its numeric equivalent.
  1810.  
  1811.           Syntax:
  1812.              Char2Num (string)
  1813.  
  1814.           Parameters:
  1815.              "string" =  any text string.  Only the first character will be
  1816.                        converted.
  1817.  
  1818.           Returns:
  1819.              (integer) ANSI character code.
  1820.  
  1821.           This function returns the 8-bit ANSI code corresponding to the
  1822.           first character of the string parameter.
  1823.  
  1824.           Note:  For the commonly-used characters (with codes below 128),
  1825.           ANSI and ASCII characters are identical.
  1826.  
  1827.           Example:
  1828.           ; Show the hex equivalent of entered character
  1829.           &Programming
  1830.            &ANSI Codes
  1831.              InpChar = AskLine("ANSI Equivalents", "Char:", "")
  1832.              Ansi = strsub(InpChar,1,1)
  1833.              AnsiEquiv = Char2Num(InpChar)
  1834.              Message("ANSI Codes","%Ansi% => %AnsiEquiv%")
  1835.  
  1836.  
  1837.           See Also:
  1838.              Num2Char
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.                                                                             54
  1859.  
  1860.                                                      CPML  FUNCTION  REFERENCE
  1861.  
  1862.  
  1863.  
  1864.           ClipAppend
  1865.           Appends a string to the Clipboard.
  1866.  
  1867.           Syntax:
  1868.              ClipAppend (string)
  1869.  
  1870.           Parameters:
  1871.              "string" =  text string to add to Clipboard.
  1872.  
  1873.           Returns:
  1874.              (integer) @TRUE if string was appended;
  1875.                        @FALSE if Clipboard ran out of memory.
  1876.  
  1877.           Use this command to append a string to the Windows Clipboard.  The
  1878.           Clipboard must either contain text data or be empty for this
  1879.           command to succeed.
  1880.  
  1881.  
  1882.           Example:
  1883.           ; The code below will append 2 copies of the Clipboard con-
  1884.           ; tents back to the Clipboard, resulting in 3 copies of the
  1885.           ; original contents with a CR/LF between each copy.
  1886.              a=clipget()
  1887.              crlf=strcat(num2char(13),num2char(10))
  1888.              clipappend(crlf)
  1889.              clipappend(a)
  1890.              clipappend(crlf)
  1891.              clipappend(a)
  1892.  
  1893.  
  1894.           See Also:
  1895.              ClipGet, ClipPut
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.                                                                             55
  1915.  
  1916.                                                      CPML  FUNCTION  REFERENCE
  1917.  
  1918.  
  1919.  
  1920.           ClipGet
  1921.           Returns the contents of the Clipboard.
  1922.  
  1923.           Syntax:
  1924.              ClipGet ( )
  1925.  
  1926.           Returns:
  1927.              (string)  clipboard contents.
  1928.  
  1929.           Use this command to copy text from the Windows Clipboard into a
  1930.           string variable.
  1931.  
  1932.           Note:  If the Clipboard contains an excessively large string a
  1933.           (fatal) out of memory error may occur.
  1934.  
  1935.           Example:
  1936.           ; The code below will convert Clipboard contents to uppercase:
  1937.              clipput(strupper(clipget()))
  1938.              a=clipget()
  1939.              message("UPPERCASE Clipboard Contents",a)
  1940.  
  1941.  
  1942.           See Also:
  1943.              ClipAppend, ClipPut
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.                                                                             56
  1971.  
  1972.                                                      CPML  FUNCTION  REFERENCE
  1973.  
  1974.  
  1975.  
  1976.           ClipPut
  1977.           Copies a string to the clipboard.
  1978.  
  1979.           Syntax:
  1980.              ClipPut (string)
  1981.  
  1982.           Parameters:
  1983.              "string" =  any text string.
  1984.  
  1985.           Returns:
  1986.              (integer) @TRUE if string was copied;
  1987.                        @FALSE if clipboard ran out of memory.
  1988.  
  1989.           Use this command to copy a string to the Windows Clipboard.  The
  1990.           previous Clipboard contents will be lost.
  1991.  
  1992.  
  1993.           Example:
  1994.           ; The code below will convert Clipboard contents to lowercase:
  1995.              clipput(strlower(clipget()))
  1996.              a = clipget ()
  1997.              message("lowercase Clipboard Contents",a)
  1998.  
  1999.  
  2000.           See Also:
  2001.              ClipAppend, ClipGet
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.                                                                             57
  2027.  
  2028.                                                      CPML  FUNCTION  REFERENCE
  2029.  
  2030.  
  2031.  
  2032.           CurrentFile
  2033.           Returns the selected filename.
  2034.  
  2035.           Syntax:
  2036.              CurrentFile ( )
  2037.  
  2038.           Returns:
  2039.              (string)  currently-selected file's name.
  2040.  
  2041.           When Command Post displays the files in the current directory, one
  2042.           of them is always selected.  It's the one with the dotted-line box
  2043.           around it.
  2044.  
  2045.           This is different than a "highlighted" file.  When a file is
  2046.           highlighted, it shows up in inverse video (usually white-on-black).
  2047.           To find the filenames that are highlighted, see FileItemize.
  2048.  
  2049.           Example:
  2050.           ; Ask which program to run (default = current file):
  2051.              TheFile = AskLine ("Run It", "Program:", CurrentFile())
  2052.              Run (TheFile, "")
  2053.  
  2054.  
  2055.           See Also:
  2056.              FileItemize, DirGet, DirItemize
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.                                                                             58
  2083.  
  2084.                                                      CPML  FUNCTION  REFERENCE
  2085.  
  2086.  
  2087.  
  2088.           DateTime
  2089.           Provides the current Date and time.
  2090.  
  2091.           Syntax:
  2092.              DateTime ( )
  2093.  
  2094.           Returns:
  2095.              (string)  Today's Date and time
  2096.  
  2097.           This function will return the current date and time in a pre-
  2098.           formatted string.  The format it is returned in depends on how it
  2099.           is set up in the international section of the WIN.INI file:
  2100.  
  2101.           ddd mm:dd:yy hh:mm:ss XX
  2102.           ddd dd:mm:yy hh:mm:ss XX
  2103.           ddd yy:mm:dd hh:mm:ss XX
  2104.           Where
  2105.              ddd is day of the week (e.g. Mon)
  2106.              mm  is the month (e.g. 10)
  2107.              dd  is the day of the month (e.g. 23)
  2108.              yy  is the year (e.g. 90)
  2109.              hh  is the hours
  2110.              mm  is the minutes
  2111.              ss  is the seconds
  2112.              XX  is the Day/Night code (e.g. AM or PM)
  2113.  
  2114.           Note:  Windows 3.0 provides even more formatting options than this.
  2115.           The WIN.INI file will be examined to determine which format to use.
  2116.           You can adjust the WIN.INI file via the International section of
  2117.           the Control Panel if the format isn't what you prefer.
  2118.  
  2119.  
  2120.           Example:
  2121.           ; assuming the current standard is U.S.
  2122.           ; (i.e. day  dd/mm/yy hh:mm:ss AM):
  2123.              Message("Current Date & Time",DateTime())
  2124.  
  2125.           would produce:
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.                                                                             59
  2139.  
  2140.                                                      CPML  FUNCTION  REFERENCE
  2141.  
  2142.  
  2143.  
  2144.           Debug
  2145.           Controls the debug mode.
  2146.  
  2147.           Syntax:
  2148.              Debug (mode)
  2149.  
  2150.           Parameters:
  2151.              "mode" =  @ON | @OFF
  2152.  
  2153.           Returns:
  2154.              (integer) Previous Debug mode
  2155.  
  2156.           Use this command to turn the debug mode on or off.  The default is
  2157.           @OFF.
  2158.  
  2159.           When Debug mode is on, Command Post will display the command just
  2160.           executed, its result (if any), any error conditions, and the next
  2161.           command to execute.
  2162.           The commands are displayed in a special dialog box.  As you can see
  2163.           in the Example section following, the dialog box gives the user
  2164.           four options:  Next, Run, Cancel and Show Var.
  2165.  
  2166.           Next executes the next statement and remains in debug mode.
  2167.           Run exits debug mode and runs the rest of the program normally.
  2168.  
  2169.           Cancel terminates the current menu item.
  2170.           Show Var displays the contents of a variable whose name the user
  2171.           entered in the edit box.
  2172.  
  2173.  
  2174.           Example:
  2175.           ; Debug example
  2176.              debug(@on)
  2177.              a = 6
  2178.              q = askyesno("Testing Debug Mode", "Is the Pope Catholic")
  2179.              debug(@off)
  2180.              b = a + 4
  2181.  
  2182.           produces:
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.  
  2193.  
  2194.                                                                             60
  2195.  
  2196.                                                      CPML  FUNCTION  REFERENCE
  2197.  
  2198.           ...then, if the user presses Next:
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.           ...and if the user presses Yes:
  2208.  
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.           ...etc.  (If the user had pressed No it would have said
  2221.           "VALUE=>0".)
  2222.  
  2223.  
  2224.           See Also:
  2225.              ErrorMode, LastError
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.                                                                             61
  2251.  
  2252.                                                      CPML  FUNCTION  REFERENCE
  2253.  
  2254.  
  2255.  
  2256.           Delay
  2257.           Pauses execution a specified amount of time.
  2258.  
  2259.           Syntax:
  2260.              Delay (seconds)
  2261.  
  2262.           Parameters:
  2263.              "seconds" = number of seconds to delay (2 - 15)
  2264.  
  2265.           Returns:
  2266.              (integer) always @TRUE
  2267.  
  2268.           Seconds must be between 2 and 15. Smaller or larger numbers will be
  2269.           adjusted accordingly.
  2270.  
  2271.  
  2272.           Example:
  2273.              Message("Wait","About 15 seconds")
  2274.              Delay(15)
  2275.              Message("Hi","I'm Baaaaaaack")
  2276.  
  2277.  
  2278.           See Also:
  2279.              Yield
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.                                                                             62
  2307.  
  2308.                                                      CPML  FUNCTION  REFERENCE
  2309.  
  2310.  
  2311.  
  2312.           DirChange
  2313.           Changes the current directory.  Can also log a new drive.
  2314.  
  2315.           Syntax:
  2316.              DirChange ([d:]path)
  2317.  
  2318.           Parameters:
  2319.              "[d:]" =  an optional disk drive to log onto.
  2320.              "path" =  the desired path.
  2321.  
  2322.           Returns:
  2323.              (integer) @TRUE if directory was changed;
  2324.                        @FALSE if the path could not be found.
  2325.  
  2326.           Use this command to change the current working directory to another
  2327.           directory, either on the same or a different disk drive.
  2328.  
  2329.  
  2330.           Errors:
  2331.              1031 "DirChange: Dir not found/changed"
  2332.  
  2333.           Example:
  2334.              DirChange("c:\")
  2335.              textbox("This is your CONFIG.SYS file", "config.sys")
  2336.  
  2337.  
  2338.           See Also:
  2339.              DirGet, DirHome, LogDisk
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.                                                                             63
  2363.  
  2364.                                                      CPML  FUNCTION  REFERENCE
  2365.  
  2366.  
  2367.  
  2368.           DirGet
  2369.           Gets the Current Working Directory.
  2370.  
  2371.           Syntax:
  2372.              DirGet ( )
  2373.  
  2374.           Returns:
  2375.              (string) =  Current Working Directory.
  2376.  
  2377.           Use this command to determine which directory we are currently in.
  2378.           It's especially useful when changing drives or directories
  2379.           temporarily.
  2380.  
  2381.  
  2382.           Example:
  2383.           ; Get, then restore current working directory
  2384.              OrigDir=DirGet()
  2385.              DirChange("c:\")
  2386.              FileCopy("config.sys","%OrigDir%xxxtemp.xyz", @FALSE)
  2387.              DirChange(OrigDir)
  2388.  
  2389.  
  2390.           See Also:
  2391.              DirHome, OtherDir
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.                                                                             64
  2419.  
  2420.                                                      CPML  FUNCTION  REFERENCE
  2421.  
  2422.  
  2423.  
  2424.           DirHome
  2425.           Returns directory containing the Command Post EXE file.
  2426.  
  2427.           Syntax:
  2428.              DirHome ( )
  2429.  
  2430.           Returns:
  2431.              (string)  pathname of the home directory.
  2432.  
  2433.           Use this command to determine the location of CMDPOST.EXE.
  2434.  
  2435.  
  2436.           Example:
  2437.              a=DirHome()
  2438.              Message("Command Post Executable is in ",a)
  2439.  
  2440.  
  2441.           See Also:
  2442.              DirGet, OtherDir
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474.                                                                             65
  2475.  
  2476.                                                      CPML  FUNCTION  REFERENCE
  2477.  
  2478.  
  2479.  
  2480.           DirItemize
  2481.           Returns a space-delimited list of the highlighted directories.
  2482.  
  2483.           Syntax:
  2484.              DirItemize (dir-list)
  2485.  
  2486.           Parameters:
  2487.              "dir-list" =a string containing zero or more subdirectory names,
  2488.                        which may be wildcarded.
  2489.  
  2490.           Returns:
  2491.              (string)  list of directories.
  2492.  
  2493.           This function compiles a list of subdirectories and separates the
  2494.           names with spaces.
  2495.  
  2496.           Which directory names are itemized depends on the "dir-list"
  2497.           parameter:  If it is an empty string, all subdirectories
  2498.           highlighted in the Command Post file manager display are included.
  2499.           If there are any directory names or wildcards in the string, all
  2500.           subdirectories matching the pathnames are included regardless of
  2501.           which ones are highlighted.
  2502.           This is especially useful in conjunction with the ItemSelect
  2503.           function, which enables the user to choose an item from such a
  2504.           space-delimited list.
  2505.  
  2506.  
  2507.           Example:
  2508.              ;Verify directory selection:
  2509.              a=DirItemize("")
  2510.              ItemSelect("Directories", a, " ")
  2511.  
  2512.  
  2513.           See Also:
  2514.              FileItemize, WinItemize, ItemSelect
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524.  
  2525.  
  2526.  
  2527.  
  2528.  
  2529.  
  2530.                                                                             66
  2531.  
  2532.                                                      CPML  FUNCTION  REFERENCE
  2533.  
  2534.  
  2535.  
  2536.           DirMake
  2537.           Creates a new directory.
  2538.  
  2539.           Syntax:
  2540.              DirMake ([d:]path)
  2541.  
  2542.           Parameters:
  2543.              "[d:]" =  the desired disk drive.
  2544.              "path" =  the path to create.
  2545.  
  2546.           Returns:
  2547.              (integer) @TRUE if the directory was successfully created;
  2548.                        @FALSE if it wasn't.
  2549.  
  2550.           Use this command to create a new directory.
  2551.  
  2552.  
  2553.           Errors:
  2554.              1029 "DirMake: Dir not created"
  2555.  
  2556.           Example:
  2557.              DirMake("c:\XXXSTUFF")
  2558.  
  2559.  
  2560.           See Also:
  2561.              DirRemove
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.  
  2585.  
  2586.                                                                             67
  2587.  
  2588.                                                      CPML  FUNCTION  REFERENCE
  2589.  
  2590.  
  2591.  
  2592.           DirRemove
  2593.           Removes a directory.
  2594.  
  2595.           Syntax:
  2596.              DirRemove (dir-list)
  2597.  
  2598.           Parameters:
  2599.              "dir-list" =a space-delimited list of directory pathnames.
  2600.  
  2601.           Returns:
  2602.              (integer) @TRUE if the directory was successfully removed;
  2603.                        @FALSE if it wasn't.
  2604.  
  2605.           Use this command to delete directories.  You can delete one or more
  2606.           at a time by separating directory names with spaces.  You cannot,
  2607.           however, use wildcards.
  2608.  
  2609.  
  2610.           Errors:
  2611.              1030 "DirRemove: Dir not removed"
  2612.  
  2613.           Example:
  2614.              DirRemove("c:\XXXSTUFF")
  2615.              DirRemove("tempdir1 tempdir2 tempdir3")
  2616.  
  2617.  
  2618.           See Also:
  2619.              DirMake
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.                                                                             68
  2643.  
  2644.                                                      CPML  FUNCTION  REFERENCE
  2645.  
  2646.  
  2647.  
  2648.           DiskFree
  2649.           Finds the total space available on a group of drives.
  2650.  
  2651.           Syntax:
  2652.              DiskFree (drive-list)
  2653.  
  2654.           Parameters:
  2655.              "drive-list" = at least one drive letter, separated by spaces.
  2656.  
  2657.           Returns:
  2658.              (integer) the number of bytes available on all the specified
  2659.                        drives.
  2660.  
  2661.           This function takes a string consisting of drive letters, separated
  2662.           by spaces.  Only the first character of each non-blank group of
  2663.           characters is used to determine the drives, so you can use just the
  2664.           drive letters, or add a colon (":"), or add a backslash ("\"), or
  2665.           even a whole pathname and still get a perfectly valid result.
  2666.  
  2667.  
  2668.           Example:
  2669.              Size = DiskFree ("c d")
  2670.              Message ("Space Available on C: & D:", Size)
  2671.  
  2672.  
  2673.           See Also:
  2674.              FileSize
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.                                                                             69
  2699.  
  2700.                                                      CPML  FUNCTION  REFERENCE
  2701.  
  2702.  
  2703.  
  2704.           Display
  2705.           Displays a message to the user for a specified time.
  2706.  
  2707.           Syntax:
  2708.              Display (seconds, title, text)
  2709.  
  2710.           Parameters:
  2711.              "seconds" = integer seconds to display the message (1-15).
  2712.              "title" = Title of the window to be displayed.
  2713.              "text" =  Text of the window to be displayed.
  2714.  
  2715.           Returns:
  2716.              (integer) always @TRUE.
  2717.  
  2718.           Use this command to display a message for a few seconds, and then
  2719.           continue with processing without user input.
  2720.  
  2721.           The display box may be prematurely canceled by the user by clicking
  2722.           it with a mouse, or hitting any character.
  2723.  
  2724.           Example:
  2725.              name=askline("Desserts", "Please enter your name", "")
  2726.              dsrt=askline("Desserts", "Favorite dessert?", "Ice Cream")
  2727.              display(3,"%name%'s Dessert", dsrt)
  2728.  
  2729.           ...If Jennifer likes pudding, the display statement produces:
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.           See Also:
  2737.              Pause, Message, Terminate
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.                                                                             70
  2755.  
  2756.                                                      CPML  FUNCTION  REFERENCE
  2757.  
  2758.  
  2759.  
  2760.           Drop
  2761.           Removes variables from memory.
  2762.  
  2763.           Syntax:
  2764.              Drop (var, [var]...)
  2765.  
  2766.           Parameters:
  2767.              var =     variable names to remove.
  2768.  
  2769.           Returns:
  2770.              (integer) @TRUE.
  2771.  
  2772.           This function removes variables from the language processor's
  2773.           variable list, and recovers the memory associated with the variable
  2774.           (and possibly related string storage).
  2775.  
  2776.  
  2777.           Example:
  2778.              A="A variable"
  2779.              B="Another one"
  2780.  
  2781.              Drop(A,B)   ; This removes A and B from memory
  2782.  
  2783.  
  2784.  
  2785.  
  2786.  
  2787.  
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.                                                                             71
  2811.  
  2812.                                                      CPML  FUNCTION  REFERENCE
  2813.  
  2814.  
  2815.  
  2816.           EndSession
  2817.           Ends the Windows session.
  2818.  
  2819.           Syntax:
  2820.              EndSession ( )
  2821.  
  2822.           Use this command to end the Windows session.  This command is
  2823.           equivalent to closing the MS-DOS Executive window in Windows v2.x,
  2824.           or the Program Manager window in Windows v3.0.
  2825.  
  2826.  
  2827.           Example:
  2828.           &Utilities
  2829.            E&xit Windows
  2830.              Sure = AskYesNo ("End Session", "You SURE you want to
  2831.                                            exit Windows?")
  2832.              Terminate (Sure==@No, "", "Exit Windows cancelled")
  2833.              EndSession ()
  2834.  
  2835.  
  2836.           See Also:
  2837.              Exit, Terminate, WinClose, WinCloseNot
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.  
  2849.  
  2850.  
  2851.  
  2852.  
  2853.  
  2854.  
  2855.  
  2856.  
  2857.  
  2858.  
  2859.  
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.                                                                             72
  2867.  
  2868.                                                      CPML  FUNCTION  REFERENCE
  2869.  
  2870.  
  2871.  
  2872.           Environment
  2873.           Gets a DOS environment variable.
  2874.  
  2875.           Syntax:
  2876.              Environment (env-variable)
  2877.  
  2878.           Parameters:
  2879.              "env-variable" = any defined environment variable.
  2880.  
  2881.           Returns:
  2882.              (string)  environment variable contents.
  2883.  
  2884.           Use this command to query the DOS environment.
  2885.  
  2886.  
  2887.           Example:
  2888.           &MsDos Utilities
  2889.            Display &Path
  2890.              ;Display the PATH for this DOS session...
  2891.              CurrPath=Environment("PATH")
  2892.              Message ("Current DOS Path", CurrPath)
  2893.  
  2894.  
  2895.           See Also:
  2896.              IniRead, Version, WinVersion
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.  
  2917.  
  2918.  
  2919.  
  2920.  
  2921.  
  2922.                                                                             73
  2923.  
  2924.                                                      CPML  FUNCTION  REFERENCE
  2925.  
  2926.  
  2927.  
  2928.           ErrorMode
  2929.           Specifies how to handle errors.
  2930.  
  2931.           Syntax:
  2932.              ErrorMode (mode)
  2933.  
  2934.           Parameters:
  2935.              "mode" =  @CANCEL, @NOTIFY, or @OFF.
  2936.  
  2937.           Returns:
  2938.              (integer) previous error setting.
  2939.  
  2940.           Use this command to control the effects of runtime errors.  The
  2941.           default is @CANCEL, meaning the execution of the menu item will be
  2942.           cancelled for any error.
  2943.  
  2944.           @CANCEL:  All runtime errors will cause execution to be cancelled.
  2945.           The user will be notified which error occurred.
  2946.           @NOTIFY:  All runtime errors will be reported to the user, and they
  2947.           can choose to continue if it isn't fatal.
  2948.  
  2949.           @OFF:  Minor runtime errors will be suppressed. Moderate and fatal
  2950.           errors will be reported to the user.  User has the option of
  2951.           continuing if the error is not fatal.
  2952.           In general we suggest the normal state of the program should be
  2953.           ErrorMode(@CANCEL), especially if you are writing a menu for others
  2954.           to use.  You can always suppress errors you expect will occur and
  2955.           then re-enable ErrorMode (@CANCEL).
  2956.  
  2957.  
  2958.           Example:
  2959.           ; Delete xxxtest.xyz.
  2960.           ; If file doesn't exist, continue execution; don't stop:
  2961.              PrevErrMode=ErrorMode(@off)
  2962.              FileDelete("c:\xxxtest.xyz")
  2963.              ErrorMode(PrevErrMode)
  2964.  
  2965.  
  2966.           See Also:
  2967.              Debug, LastError
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.                                                                             74
  2979.  
  2980.                                                      CPML  FUNCTION  REFERENCE
  2981.  
  2982.  
  2983.  
  2984.           Execute
  2985.           Executes a statement in a protected environment.  Any errors
  2986.           encountered are recoverable.
  2987.  
  2988.           Syntax:
  2989.              Execute statement
  2990.  
  2991.           Parameters:
  2992.              "statement" =  is (hopefully) an executable statement.
  2993.  
  2994.           Use this command to execute computed or user-entered statements.
  2995.           Due to the built-in error recovery associated with the Execute
  2996.           statement, it is ideal for interactive execution of user-entered
  2997.           commands.
  2998.  
  2999.           Note the Execute statement doesn't operate on a string per se, but
  3000.           rather on a direct statement.  If you want to put a code segment
  3001.           into a string variable you must use the substitution feature of the
  3002.           language, as in the example below.
  3003.  
  3004.           Example:
  3005.              CPMLCmd="" ;in autoexec section in beginning
  3006.              . . .
  3007.           &System
  3008.            CP Menu Language Interactive
  3009.              CPMLCmd=AskLine("CPML Interactive","Command:",CPMLCmd)
  3010.              execute %CPMLCmd%
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.                                                                             75
  3035.  
  3036.                                                      CPML  FUNCTION  REFERENCE
  3037.  
  3038.  
  3039.  
  3040.           Exit
  3041.           Terminates the menu item being interpreted.
  3042.  
  3043.           Syntax:
  3044.              Exit
  3045.  
  3046.           Use this command to prematurely exit a menu process.  An exit is
  3047.           implied at the end of each menu item.
  3048.  
  3049.  
  3050.           Example:
  3051.              a = 100
  3052.              message("The value of a is",a)
  3053.              exit
  3054.  
  3055.  
  3056.           See Also:
  3057.              Pause
  3058.  
  3059.  
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.                                                                             76
  3091.  
  3092.                                                      CPML  FUNCTION  REFERENCE
  3093.  
  3094.  
  3095.  
  3096.           FileCopy
  3097.           Copies files.
  3098.  
  3099.           Syntax:
  3100.              FileCopy (source-list, destination, warning)
  3101.  
  3102.           Parameters:
  3103.              "source-list" =  a string containing one or more filenames,
  3104.                        which may be wildcarded.
  3105.              "destination" =  target file name.
  3106.  
  3107.              "warning" = @TRUE if you want a warning before
  3108.                        overwriting existing files;
  3109.                        @FALSE if no warning desired.
  3110.  
  3111.           Returns:
  3112.              (integer)   @TRUE if all files were copied successfully;
  3113.                        @FALSE if at least one file wasn't copied.
  3114.  
  3115.           Use this command to copy an individual file, a group of files using
  3116.           wildcards, or several groups of files by separating the names with
  3117.           spaces.
  3118.  
  3119.           You can also copy files to any COM or LPT device.
  3120.           "Source-list" may contain * and ? wildcards.  "Destination" may
  3121.           contain the * wildcard only.
  3122.  
  3123.  
  3124.           Errors:
  3125.              1006 "File Copy/Move: No matching files found"
  3126.              2002 "File Copy/Move: 'From' file illegal"
  3127.              2003 "File Copy/Move: 'To'   file illegal"
  3128.              2004 "File Copy/Move: Cannot copy/move wildcards into fixed root"
  3129.              2005 "File Copy/Move: Cannot copy/move wildcards into fixed
  3130.                   extension"
  3131.              3118 "FileCopyMove: Destination file same as source"
  3132.  
  3133.           Examples:
  3134.              FileCopy("c:\config.sys","d:", @FALSE)
  3135.              FileCopy("c:\*.sys","d:devices\*.sys", @TRUE)
  3136.              FileCopy("c:\config.sys","LPT1:", @FALSE)
  3137.  
  3138.  
  3139.           See Also:
  3140.              FileDelete, FileExist, FileLocate, FileMove, FileRename
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.                                                                             77
  3147.  
  3148.                                                      CPML  FUNCTION  REFERENCE
  3149.  
  3150.  
  3151.  
  3152.           FileDelete
  3153.           Deletes files.
  3154.  
  3155.           Syntax:
  3156.              FileDelete (file-list)
  3157.  
  3158.           Parameters:
  3159.              "file-list" =  a string containing one or more filenames, which
  3160.                        may be wildcarded.
  3161.  
  3162.           Returns:
  3163.              (integer) @TRUE if all the files were deleted;
  3164.                        @FALSE if a file didn't exist or is marked with the
  3165.                        READ-ONLY attribute.
  3166.  
  3167.           Use this command to delete an individual file, a group of files
  3168.           using wildcards, or several groups of files by separating the names
  3169.           with spaces.
  3170.  
  3171.  
  3172.           Errors:
  3173.              1017 "File Delete: No matching files found"
  3174.              1018 "File Delete: Delete Failed"
  3175.              2016 "File Delete: File name illegal"
  3176.  
  3177.           Example:
  3178.              WasDeleted = FileDelete ("BadFile")
  3179.  
  3180.  
  3181.           See Also:
  3182.              FileExist, FileLocate, FileMove, FileRename
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.                                                                             78
  3203.  
  3204.                                                      CPML  FUNCTION  REFERENCE
  3205.  
  3206.  
  3207.  
  3208.           FileExist
  3209.           Tests for the existence of files.
  3210.  
  3211.           Syntax:
  3212.              FileExist (filename)
  3213.  
  3214.           Parameters:
  3215.              "filename" =either a fully qualified filename with drive and
  3216.                        path, or just a filename and extension.
  3217.  
  3218.           Returns:
  3219.              (integer) @YES if the file exists;
  3220.                        @NO if it doesn't or if the pathname is invalid.
  3221.  
  3222.           This statement is used to test whether or not a specified file
  3223.           exists.
  3224.  
  3225.           If a fully qualified file name is used only the specified drive and
  3226.           directory will be checked for the desired file.  If only the root
  3227.           and extension are specified, then all the directories in the DOS
  3228.           PATH statement will be searched for the desired file.
  3229.  
  3230.           Example:
  3231.              ; check for file in current directory
  3232.              Fex=FileExist(strcat(DirGet(),"myfile.txt"))
  3233.              Tex=substr("NOT",1,strlen("NOT")*Fex)
  3234.              Message("MyFile.Txt"," Is %Tex%in the current directory")
  3235.  
  3236.              ; check for file in someplace along path
  3237.              Fex=FileExist("myfile.txt")
  3238.              Tex=substr("NOT",1,strlen("NOT")*Fex)
  3239.  
  3240.              Message("MyFile.Txt"," Is %Tex% in the DOS path")
  3241.  
  3242.  
  3243.           See Also:
  3244.              FileLocate
  3245.  
  3246.  
  3247.  
  3248.  
  3249.  
  3250.  
  3251.  
  3252.  
  3253.  
  3254.  
  3255.  
  3256.  
  3257.  
  3258.                                                                             79
  3259.  
  3260.                                                      CPML  FUNCTION  REFERENCE
  3261.  
  3262.  
  3263.  
  3264.           FileItemize
  3265.           Returns a space-delimited list of files.
  3266.  
  3267.           Syntax:
  3268.              FileItemize (file-list)
  3269.  
  3270.           Parameters:
  3271.              "file-list" =  a string containing zero or more filenames, which
  3272.                        may be wildcarded.
  3273.  
  3274.           Returns:
  3275.              (string)  space-delimited list of files.
  3276.  
  3277.           This function compiles a list of filenames and separates the names
  3278.           with spaces.
  3279.  
  3280.           Which filenames are itemized depends on the "file-list" parameter:
  3281.           If it is an empty string, all filenames highlighted in the Command
  3282.           Post file manager display are included.  If there are any filenames
  3283.           or wildcards in the string, all files matching the filenames are
  3284.           included regardless of which ones are highlighted.
  3285.           This is especially useful in conjunction with the ItemSelect
  3286.           function, which enables the user to choose an item from such a
  3287.           space-delimited list.
  3288.  
  3289.  
  3290.           Examples:
  3291.            &Edit INI files
  3292.              ;Get which .INI file to edit (meaningful in Win 3.0 only):
  3293.              IFiles= FileItemize("c:\windows\*.ini")
  3294.              IFile = ItemSelect(".INI Files",IFiles, " ")
  3295.              RunZoom ("Notepad", IFile)
  3296.              Drop (IFiles, IFile)
  3297.  
  3298.  
  3299.           See Also:
  3300.              DirItemize, WinItemize, ItemSelect
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.  
  3312.  
  3313.  
  3314.                                                                             80
  3315.  
  3316.                                                      CPML  FUNCTION  REFERENCE
  3317.  
  3318.  
  3319.  
  3320.           FileLocate
  3321.           Finds file in current directory or along the DOS PATH.
  3322.  
  3323.           Syntax:
  3324.              FileLocate (filename)
  3325.  
  3326.           Parameters:
  3327.              "filename" =root name, ".", and an extension.
  3328.  
  3329.           Returns:
  3330.              (string)  fully qualified path name.
  3331.  
  3332.           This function is used to obtain the fully qualified path name of a
  3333.           file.  The current directory is checked first, and if the file is
  3334.           not found the DOS path is searched.  This function returns the
  3335.           first occurrence of the file.
  3336.  
  3337.  
  3338.           Example:
  3339.            Edit &WIN.INI
  3340.              winini=FileLocate("win.ini")
  3341.              Terminate(winini=="","???","WIN.INI not found")
  3342.              Run("notepad.exe",winini)
  3343.              Exit
  3344.  
  3345.  
  3346.           See Also:
  3347.              FileExist
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.                                                                             81
  3371.  
  3372.                                                      CPML  FUNCTION  REFERENCE
  3373.  
  3374.  
  3375.  
  3376.           FileMove
  3377.           Moves files.
  3378.  
  3379.           Syntax:
  3380.              FileMove (source-list, destination, warning)
  3381.  
  3382.           Parameters:
  3383.              "source-list" =  one or more filenames separated by spaces.
  3384.              "destination" =  target filename.
  3385.              "warning" = @TRUE if you want a warning before overwriting
  3386.                        existing files;
  3387.                        @FALSE if no warning desired.
  3388.  
  3389.           Returns:
  3390.              (integer) @TRUE if the file was moved;
  3391.                        @FALSE if the source file was not found or had the
  3392.                        READ-ONLY attribute, or the target filename is invalid.
  3393.  
  3394.           Use this command to move an individual file, a group of files using
  3395.           wildcards, or several groups of files by separating the names with
  3396.           spaces.
  3397.  
  3398.           You can also move files to another drive, or to any COM or LPT
  3399.           device.
  3400.           "Source-list" may contain * and ? wildcards.  "Destination" may
  3401.           contain the * wildcard only.
  3402.  
  3403.  
  3404.           Errors:
  3405.              1006 "File Copy/Move: No matching files found"
  3406.              2002 "File Copy/Move: 'From' file illegal"
  3407.              2003 "File Copy/Move: 'To'   file illegal"
  3408.              2004 "File Copy/Move: Cannot copy/move wildcards into fixed root"
  3409.              2005 "File Copy/Move: Cannot copy/move wildcards into fixed
  3410.                   extension"
  3411.              2007 "File Move: Unable to rename source file"
  3412.              2015 "File Move:  Unable to remove source file"
  3413.  
  3414.           Example:
  3415.              FileMove("c:\config.sys","d:", @FALSE)
  3416.              FileMove("c:\*.sys","d:*.sys", @TRUE)
  3417.  
  3418.  
  3419.           See Also:
  3420.              FileCopy, FileDelete, FileExist, FileLocate, FileRename
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.                                                                             82
  3427.  
  3428.                                                      CPML  FUNCTION  REFERENCE
  3429.  
  3430.  
  3431.  
  3432.           FileRename
  3433.           Renames files.
  3434.  
  3435.           Syntax:
  3436.              FileRename (source-list, destination)
  3437.  
  3438.           Parameters:
  3439.              "source-list" =  one or more filenames separated by spaces.
  3440.              "destination" =  target filename.
  3441.  
  3442.           Returns:
  3443.              (integer) @TRUE if the file was renamed;
  3444.                        @FALSE if the source file was not found or had the
  3445.                        READ-ONLY attribute, or the target filename is invalid.
  3446.  
  3447.           Use this command to rename an individual file, a group of files
  3448.           using wildcards, or several groups of files by separating the names
  3449.           with spaces.
  3450.  
  3451.           Note: Unlike FileMove, you cannot make a file change its resident
  3452.           disk drive with FileRename.
  3453.           "Source-list" may contain * and ? wildcards.  "Destination" may
  3454.           contain the * wildcard only.
  3455.  
  3456.  
  3457.           Errors:
  3458.              1024 "File Rename: No matching files found"
  3459.              1025 "File Rename: Rename failed"
  3460.              2019 "File Rename: 'From' file illegal"
  3461.              2020 "File Rename: 'To' file illegal"
  3462.              2021 "File Rename: Attempt to rename across drive boundary. - Use
  3463.                   MOVE instead."
  3464.              2022 "File Rename: Cannot rename wildcards into a fixed filename
  3465.                   root"
  3466.              2023 "File Rename: Cannot rename wildcards into a fixed filename
  3467.                   extension"
  3468.  
  3469.           Example:
  3470.              FileRename("c:\config.sys","config.old")
  3471.              FileRename("c:\*.txt","*.bak")
  3472.  
  3473.  
  3474.           See Also:
  3475.              FileCopy, FileExist, FileLocate, FileMove
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.                                                                             83
  3483.  
  3484.                                                      CPML  FUNCTION  REFERENCE
  3485.  
  3486.  
  3487.  
  3488.           FileSize
  3489.           Finds the total size of a group of files.
  3490.  
  3491.           Syntax:
  3492.              FileSize (file-list)
  3493.  
  3494.           Parameters:
  3495.              "file-list" =  zero or more filenames, separated by spaces.
  3496.  
  3497.           Returns:
  3498.              (integer) total bytes taken up by the specified files.
  3499.  
  3500.           This function returns the total size of the specified files.  Note
  3501.           it doesn't handle wildcarded filenames.  You can, however, use
  3502.           FileItemize on a wildcarded filename and use the resulting string
  3503.           with as a FileSize parameter.
  3504.  
  3505.  
  3506.           Errors:
  3507.              3112 "FileSize:  File Not Found"
  3508.  
  3509.           Example:
  3510.              Size = FileSize (FileItemize(""))
  3511.              Message ("Size of Highlighted Files", Size)
  3512.  
  3513.  
  3514.           See Also:
  3515.              DiskFree
  3516.  
  3517.  
  3518.  
  3519.  
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.                                                                             84
  3539.  
  3540.                                                      CPML  FUNCTION  REFERENCE
  3541.  
  3542.  
  3543.  
  3544.           IniRead
  3545.           Reads data from the WIN.INI file.
  3546.  
  3547.           Syntax:
  3548.              IniRead (section, keyname, default)
  3549.  
  3550.           Parameters:
  3551.              "section" = the major heading to read the data from.
  3552.              "keyname =  the name of the item to read.
  3553.              "default" = string to return if the desired item is not found.
  3554.  
  3555.           Returns:
  3556.              (string)  data from WIN.INI file.
  3557.  
  3558.           This command allows a program to read data from the WIN.INI file.
  3559.  
  3560.           The WIN.INI file has the form:
  3561.              [section]
  3562.              keyname=settings
  3563.  
  3564.           Most of the entries in WIN.INI are set from the Windows Control
  3565.           Panel program, but individual applications can also use it to store
  3566.           option settings in their own sections.
  3567.  
  3568.  
  3569.           Example:
  3570.              ;Find the default output device:
  3571.              a=IniRead("windows","device","No Default")
  3572.              Message("Default Output Device",a)
  3573.  
  3574.  
  3575.           See Also:
  3576.              Environment, IniWrite
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.                                                                             85
  3595.  
  3596.                                                      CPML  FUNCTION  REFERENCE
  3597.  
  3598.  
  3599.  
  3600.           IniWrite
  3601.           Writes data to the WIN.INI file.
  3602.  
  3603.           Syntax:
  3604.              IniWrite (section, keyname, data)
  3605.  
  3606.           Parameters:
  3607.              "section" = major heading to write the data to.
  3608.              "keyname =  name of the data item to write.
  3609.              "data" =  string to write to the WIN.INI file.
  3610.  
  3611.           Returns:
  3612.              (integer) always @TRUE.
  3613.  
  3614.           This command allows a program to write data to the WIN.INI file.
  3615.           The "section" is added to the file if it doesn't already exist.
  3616.  
  3617.  
  3618.           Example:
  3619.           &WIN.INI Stuff
  3620.            Modify &LOAD= line
  3621.              ;Change the list of pgms to load upon Windows startup:
  3622.              LoadProgs = IniRead("windows","load","")
  3623.              NewProgs=AskLine("Add Pgm To LOAD= Line", "Add:", LoadProgs)
  3624.              IniWrite("windows","load",NewProgs)
  3625.  
  3626.  
  3627.           See Also:
  3628.              IniRead
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.  
  3645.  
  3646.  
  3647.  
  3648.  
  3649.  
  3650.                                                                             86
  3651.  
  3652.                                                      CPML  FUNCTION  REFERENCE
  3653.  
  3654.  
  3655.  
  3656.           IsDefined
  3657.           Determines if a variable name is currently defined.
  3658.  
  3659.           Syntax:
  3660.              IsDefined (var)
  3661.  
  3662.           Parameters:
  3663.              "var" =   a variable name.
  3664.  
  3665.           Returns:
  3666.              (integer) @YES if the variable is currently defined;
  3667.                        @NO if it was never defined or has been dropped.
  3668.  
  3669.           A variable is defined the first time it appears at the left of an
  3670.           equal sign in a statement.  It stays defined until it is explicitly
  3671.           Dropped.
  3672.  
  3673.  
  3674.           Example:
  3675.              Def = IsDefined (ThisVar)
  3676.              Terminate (Def==@FALSE, "ERROR!", "Variable not defined")
  3677.  
  3678.  
  3679.           See Also:
  3680.              Drop
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.                                                                             87
  3707.  
  3708.                                                      CPML  FUNCTION  REFERENCE
  3709.  
  3710.  
  3711.  
  3712.           IsMenuChecked
  3713.           Determines if a menuitem has a checkmark next to it.
  3714.  
  3715.           Syntax:
  3716.              IsMenuChecked (menuname)
  3717.  
  3718.           Parameters:
  3719.              "menuname" =name of the menu item to test.
  3720.  
  3721.           Returns:
  3722.              (integer) @YES if the menuitem has a checkmark;
  3723.                        @NO if it doesn't.
  3724.  
  3725.           You can place a checkmark next to a menu item with the MenuChange
  3726.           command, to indicate an option has been enabled.  This function
  3727.           lets you determine if the menu item has already been checked or
  3728.           not.
  3729.  
  3730.  
  3731.           Example:
  3732.              ;Assume we've defined a "Misc./Prompt Often" menuitem...
  3733.              Prompt = IsMenuChecked ("MiscPromptOften")
  3734.              IfPrompt = substr(";",1,(Prompt==@FALSE))
  3735.              execute %IfPrompt% Confirm = AskYesNo ("???", "Do you REALLY
  3736.                                         want to do this?")
  3737.              execute %IfPrompt% Terminate (Confirm!=@YES, "", "")
  3738.              ;some risky operation the user has just confirmed they want
  3739.              ;to carry out...
  3740.  
  3741.  
  3742.           See Also:
  3743.              IsMenuEnabled, MenuChange
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.                                                                             88
  3763.  
  3764.                                                      CPML  FUNCTION  REFERENCE
  3765.  
  3766.  
  3767.  
  3768.           IsMenuEnabled
  3769.           Determines if a menuitem has been enabled.
  3770.  
  3771.           Syntax:
  3772.              IsMenuEnabled (menuname)
  3773.  
  3774.           Parameters:
  3775.              "menuname" =name of the menu item to test.
  3776.  
  3777.           Returns:
  3778.              (integer) @YES if the menuitem is enabled;
  3779.                        @NO if it is disabled & grayed.
  3780.  
  3781.           You can disable a menu item with the MenuChange command if you want
  3782.           to prevent the user from choosing it.  It shows up on the screen as
  3783.           a grayed item.  IsMenuEnabled lets you determine if the menu item
  3784.           is currently enabled or not.
  3785.  
  3786.  
  3787.           Example:
  3788.              ;Allow editing of autoexec.bat file only if choice enabled
  3789.              Terminate (!IsMenuEnabled("UtilitiesEditBatFile"), "", "")
  3790.              Run ("Notepad.exe", "c:\autoexec.bat")
  3791.  
  3792.  
  3793.           See Also:
  3794.              IsMenuChecked, MenuChange
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.                                                                             89
  3819.  
  3820.                                                      CPML  FUNCTION  REFERENCE
  3821.  
  3822.  
  3823.  
  3824.           IsNumber
  3825.           Determines whether a variable contains a valid number.
  3826.  
  3827.           Syntax:
  3828.              IsNumber (string)
  3829.  
  3830.           Parameters:
  3831.              "string" =  string to test to see if it represents a valid
  3832.                        number.
  3833.  
  3834.           Returns:
  3835.              (integer) @YES if it contains a valid number;
  3836.                        @NO if it doesn't.
  3837.  
  3838.           This function determines if a string variable contains a valid
  3839.           integer.  Useful for checking user input prior to using it in
  3840.           computations.
  3841.  
  3842.  
  3843.           Example:
  3844.              a = AskLine("ISNUMBER","Enter a number","0")
  3845.              Terminate(!IsNumber(a),"", "You didn't enter a number")
  3846.  
  3847.  
  3848.           See Also:
  3849.              Abs, Char2Num
  3850.  
  3851.  
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.  
  3858.  
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.  
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.                                                                             90
  3875.  
  3876.                                                      CPML  FUNCTION  REFERENCE
  3877.  
  3878.  
  3879.  
  3880.           IsRunning
  3881.           Determines if another copy of Command Post is currently running.
  3882.  
  3883.           Syntax:
  3884.              IsRunning ( )
  3885.  
  3886.           Returns:
  3887.              (integer) @YES if another copy of Command Post is running;
  3888.                        @NO if this is the only one.
  3889.  
  3890.           There is no artificial restraint on the number of copies of Command
  3891.           Post you may run at once.
  3892.  
  3893.  
  3894.           Example:
  3895.              a=!(IsRunning())
  3896.              Is = strsub("not ", 1, 4*a)
  3897.              Message ("", "Another Command Post is %Is% running.")
  3898.              Drop (a, Is)
  3899.  
  3900.  
  3901.           See Also:
  3902.              OtherDir, OtherUpdate
  3903.  
  3904.  
  3905.  
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.  
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.                                                                             91
  3931.  
  3932.                                                      CPML  FUNCTION  REFERENCE
  3933.  
  3934.  
  3935.  
  3936.           ItemSelect
  3937.           Allows the user to choose an item from a listbox.
  3938.  
  3939.           Syntax:
  3940.              ItemSelect (title, list, delimiter)
  3941.  
  3942.           Parameters:
  3943.              "title" = the title of dialog box to display.
  3944.              "list" =  a string containing a list of items to choose from.
  3945.              "delimiter" =  a string containing the character to act as
  3946.                        delimiter between items in the list.
  3947.  
  3948.           Returns:
  3949.              (string)  the selected item.
  3950.  
  3951.           This function displays a dialog box with a listbox inside.  This
  3952.           listbox is filled with a list of items taken from a string you
  3953.           provide to the function.
  3954.  
  3955.           Each item in the string must be separated ("delimited") by a
  3956.           character, which you also pass to the function.
  3957.           The user selects one of the items by either doubleclicking on it,
  3958.           or single-clicking and pressing OK.  The item is returned as a
  3959.           string.
  3960.  
  3961.           If you create the list with the FileItemize or DirItemize functions
  3962.           you will be using a space-delimited list.  WinItemize, however,
  3963.           creates a tab-delimited list of window titles since titles can have
  3964.           embedded blanks.
  3965.  
  3966.           Example:
  3967.           &Graphics
  3968.            &PC Paintbrush
  3969.              Files = FileItemize("*.bmp")
  3970.              TheFile = ItemSelect("Bitmap Files",Files, " ")
  3971.              Run("pbrush.exe", TheFile)
  3972.  
  3973.           would produce (depending on what's in the current directory):
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.                                                                             92
  3987.  
  3988.                                                      CPML  FUNCTION  REFERENCE
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.           See Also:
  4007.              AskYesNo, Display,  DirItemize, FileItemize, WinItemize, Message,
  4008.              Pause, TextBox
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.  
  4038.  
  4039.  
  4040.  
  4041.  
  4042.                                                                             93
  4043.  
  4044.                                                      CPML  FUNCTION  REFERENCE
  4045.  
  4046.  
  4047.  
  4048.           LastError
  4049.           Returns the most-recent error encountered during the current menu
  4050.           item.
  4051.  
  4052.           Syntax:
  4053.              LastError ( )
  4054.  
  4055.           Returns:
  4056.              (integer) most-recent CPML error code encountered.
  4057.  
  4058.           CPML errors are numbered according to their severity.  "Minor"
  4059.           errors go from 1000 through 1999.  Moderate errors are 2000 through
  4060.           2999.  Fatal errors are numbered 3000 to 3999.
  4061.  
  4062.           Depending on which error mode is active when an error occurs, you
  4063.           may not get a chance to check the error code.  See ErrorMode for a
  4064.           discussion of default error handling.
  4065.           Don't bother checking for "fatal" error codes.  When a fatal error
  4066.           occurs, the menu item is cancelled before the next CPML statement
  4067.           gets to execute (regardless of which error mode is active).
  4068.  
  4069.           Calling LastError itself resets the last error indicator back to
  4070.           zero.
  4071.           A full listing of possible errors you can encounter in processing a
  4072.           menu item is in Appendix E - Errors.
  4073.  
  4074.  
  4075.           Example:
  4076.              ErrorMode (@OFF)
  4077.              FileCopy ("Data.dat", "c:\backups", @FALSE)
  4078.              ErrorMode (@CANCEL)
  4079.              Terminate (LastError()==1006,"Error","Please call
  4080.                                  Tech Support at 555-9999.")
  4081.  
  4082.           See Also:
  4083.              Debug, ErrorMode
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.                                                                             94
  4099.  
  4100.                                                      CPML  FUNCTION  REFERENCE
  4101.  
  4102.  
  4103.  
  4104.           LogDisk
  4105.           Logs (activates) a disk drive.
  4106.  
  4107.           Syntax:
  4108.              LogDisk (drive-letter)
  4109.  
  4110.           Parameters:
  4111.              "drive-letter" = is the disk drive to log into.
  4112.  
  4113.           Returns:
  4114.              (integer) @TRUE if the current drive was changed;
  4115.                        @FALSE if the drive doesn't exist.
  4116.  
  4117.           Use this command to change the logged disk drive.
  4118.  
  4119.           This command produces the same effect as if you typed the drive
  4120.           name from the DOS command prompt.
  4121.  
  4122.           Errors:
  4123.              1028 "LogDisk: Requested drive not online"
  4124.  
  4125.           Example:
  4126.              logdisk("c:")
  4127.  
  4128.  
  4129.           See Also:
  4130.              DirChange
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.                                                                             95
  4155.  
  4156.                                                      CPML  FUNCTION  REFERENCE
  4157.  
  4158.  
  4159.  
  4160.           Max
  4161.           Returns largest number in a list of numbers.
  4162.  
  4163.           Syntax:
  4164.              Max (integer [, integer]...)
  4165.  
  4166.           Parameters:
  4167.              "integer" = number.
  4168.  
  4169.           Returns:
  4170.              (integer) largest parameter.
  4171.  
  4172.           Use this function to determine the largest of a set of numbers.
  4173.  
  4174.  
  4175.           Example:
  4176.              a=Max(5, -37, 125, 34, 2345, -32767)
  4177.              Message("Largest number is",a)
  4178.  
  4179.  
  4180.           See Also:
  4181.              Abs, Average, Min
  4182.  
  4183.  
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.                                                                             96
  4211.  
  4212.                                                      CPML  FUNCTION  REFERENCE
  4213.  
  4214.  
  4215.  
  4216.           MenuChange
  4217.           Checks, unchecks, enables, or disables a menu item.
  4218.  
  4219.           Syntax:
  4220.              MenuChange (menuname, flags)
  4221.  
  4222.           Parameters:
  4223.              "menuname" =menu item whose status you wish to change.
  4224.              "flags" = @CHECK, @UNCHECK,
  4225.                        @ENABLE, or @DISABLE.
  4226.  
  4227.           Returns:
  4228.              (integer) always @TRUE.
  4229.  
  4230.           There are currently two ways you can modify a menu item:
  4231.  
  4232.           You can check and uncheck the item to imply that it corresponds to
  4233.           an option that can be turned on or off.
  4234.           You can temporarily disable the item (it shows up as gray) and
  4235.           later re-enable it.
  4236.  
  4237.           The two sets of flags (@Check/@UnCheck and @Enable/@Disable) can be
  4238.           combined in one function call by using the | (or) operator.
  4239.  
  4240.           Example:
  4241.              MenuChange (FilePrint, @Disable)
  4242.              MenuChange (WPWrite, @Enable|@Check)
  4243.  
  4244.  
  4245.           See Also:
  4246.              IsMenuChecked, IsMenuEnabled
  4247.  
  4248.  
  4249.  
  4250.  
  4251.  
  4252.  
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.                                                                             97
  4267.  
  4268.                                                      CPML  FUNCTION  REFERENCE
  4269.  
  4270.  
  4271.  
  4272.           Message
  4273.           Displays a message to the user.
  4274.  
  4275.           Syntax:
  4276.              Message (title, text)
  4277.  
  4278.           Parameters:
  4279.              "title" = title of the message box.
  4280.              "text" =  text to display in the message box.
  4281.  
  4282.           Returns:
  4283.              (integer) always @TRUE.
  4284.  
  4285.           Use this command to display a message to the user.  The user must
  4286.           respond by selecting the OK button before processing will continue.
  4287.  
  4288.  
  4289.           Example:
  4290.              Message("GUESSIT","Pick a number   between one and 100")
  4291.              Message("GUESSIT","Multiply your number by 2")
  4292.              Message("GUESSIT","Add 34")
  4293.              Message("GUESSIT","Divide by 2")
  4294.              Message("GUESSIT","Subtract your original number")
  4295.              Message("GUESSIT","Your answer is 17")
  4296.  
  4297.           produces:
  4298.  
  4299.  
  4300.  
  4301.  
  4302.  
  4303.  
  4304.  
  4305.  
  4306.           See Also:
  4307.              Display, Pause, Terminate
  4308.  
  4309.  
  4310.  
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.  
  4319.  
  4320.  
  4321.  
  4322.                                                                             98
  4323.  
  4324.                                                      CPML  FUNCTION  REFERENCE
  4325.  
  4326.  
  4327.  
  4328.           Min
  4329.           Returns lowest number in a list of numbers.
  4330.  
  4331.           Syntax:
  4332.              Min (integer [, integer]...)
  4333.  
  4334.           Parameters:
  4335.              "integer" = any integer number.
  4336.  
  4337.           Returns:
  4338.              (integer) lowest parameter.
  4339.  
  4340.           Use this function to determine the lowest of a set of integers.
  4341.  
  4342.  
  4343.           Example:
  4344.              a=Min( 5, -37, 125, 34, 2345, -32767)
  4345.              Message("Smallest number is",a)
  4346.  
  4347.  
  4348.           See Also:
  4349.              Abs, Average, Max
  4350.  
  4351.  
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.  
  4370.  
  4371.  
  4372.  
  4373.  
  4374.  
  4375.  
  4376.  
  4377.  
  4378.                                                                             99
  4379.  
  4380.                                                      CPML  FUNCTION  REFERENCE
  4381.  
  4382.  
  4383.  
  4384.           #NextFile
  4385.  
  4386.           Syntax:
  4387.              #NextFile  filename
  4388.  
  4389.           The #NextFile directive tells the CPML interpreter to append
  4390.           another.CPM file to the current one before building the menus.  In
  4391.           this manner you can build a common menu for a group of users, for
  4392.           example, and include a #NextFile directive to allow each user to
  4393.           customize part of their menus to suit their individual needs.  The
  4394.           default menu file CMDPOST.CPM calls the default user menu
  4395.           CMDUSER.CPM in just this way.
  4396.           #NextFile should appear only once in a menu file, as CPML only acts
  4397.           upon the first one it sees.  Also, you can only link one user menu
  4398.           in this manner.
  4399.  
  4400.  
  4401.           Example:
  4402.           ;(beginning of CMDPOST.CPM file)
  4403.           ;changed this directive to point to my own menu file
  4404.           ;instead of the default "cmduser.cpm":
  4405.           #NextFile MyOwn.cpm
  4406.              . . .
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.  
  4434.                                                                            100
  4435.  
  4436.                                                      CPML  FUNCTION  REFERENCE
  4437.  
  4438.  
  4439.  
  4440.           Num2Char
  4441.           Converts a number to its character equivalent.
  4442.  
  4443.           Syntax:
  4444.              Num2Char (integer)
  4445.  
  4446.           Parameters:
  4447.              "number" =  any number from 0 to 255.
  4448.  
  4449.           Returns:
  4450.              (string)  one-byte string containing the character the number
  4451.                        represents.
  4452.  
  4453.           Use this command to convert a number to its ASCII equivalent.
  4454.  
  4455.  
  4456.           Example:
  4457.              ; Build a variable containing a CRLF combo
  4458.              crlf=strcat(num2char(13),num2char(10))
  4459.              message("NUM2CHAR",strcat("line1",crlf,"line2"))
  4460.  
  4461.  
  4462.           See Also:
  4463.              Char2Num
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.                                                                            101
  4491.  
  4492.                                                      CPML  FUNCTION  REFERENCE
  4493.  
  4494.  
  4495.  
  4496.           OtherDir
  4497.           Finds the directory where the other copy of Command Post is
  4498.           running, if any.
  4499.  
  4500.           Syntax:
  4501.              OtherDir ( )
  4502.  
  4503.           Parameters:
  4504.              "string" =  pathname to "other" directory.
  4505.  
  4506.           Returns:
  4507.              (string)  the directory of the second-most recently used Command
  4508.                        Post window.  The current window is considered the most
  4509.                        recently used directory.
  4510.  
  4511.           Use this command to determine directory of the other Command Post
  4512.           window.  Useful in setting up copy and move operations between two
  4513.           Command Post copies.
  4514.  
  4515.  
  4516.           Example:
  4517.              a=DirGet()
  4518.              b=OtherDir()
  4519.              Message("Directory of this CmdPost window is",a)
  4520.              Message("Directory of the other CmdPost window is",b)
  4521.  
  4522.  
  4523.           See Also:
  4524.              DirGet, DirHome, OtherUpdate
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.  
  4543.  
  4544.  
  4545.  
  4546.                                                                            102
  4547.  
  4548.                                                      CPML  FUNCTION  REFERENCE
  4549.  
  4550.  
  4551.  
  4552.           OtherUpdate
  4553.           Updates another Command Post directory display.
  4554.  
  4555.           Syntax:
  4556.              OtherUpdate ( )
  4557.  
  4558.           Returns:
  4559.              (integer)   @TRUE if another copy of Command Post was found to
  4560.                        update;
  4561.                        @FALSE if this is the only copy running.
  4562.  
  4563.           This command updates the File Manager display of the next-most
  4564.           recently invoked copy of Command Post.  This is useful if your menu
  4565.           item changes a directory; i.e. if a file or directory is created,
  4566.           moved, renamed, or deleted.  OtherUpdate helps ensure the other
  4567.           Command Post display immediately reflects the change the user
  4568.           caused from this copy.
  4569.  
  4570.  
  4571.           Example:
  4572.              FileCopy ("MyFile.txt", OtherDir(), @FALSE)
  4573.              OtherUpdate ()
  4574.  
  4575.  
  4576.           See Also:
  4577.              OtherDir, SetDisplay
  4578.  
  4579.  
  4580.  
  4581.  
  4582.  
  4583.  
  4584.  
  4585.  
  4586.  
  4587.  
  4588.  
  4589.  
  4590.  
  4591.  
  4592.  
  4593.  
  4594.  
  4595.  
  4596.  
  4597.  
  4598.  
  4599.  
  4600.  
  4601.  
  4602.                                                                            103
  4603.  
  4604.                                                      CPML  FUNCTION  REFERENCE
  4605.  
  4606.  
  4607.  
  4608.           Pause
  4609.           Provides a message to user.  User may cancel processing.
  4610.  
  4611.           Syntax:
  4612.              Pause (title, text)
  4613.  
  4614.           Parameters:
  4615.              "title" = title of pause box.
  4616.              "text" =  text of the message to be displayed.
  4617.  
  4618.           Returns:
  4619.              (integer)   always @TRUE.
  4620.  
  4621.           This command displays a message to the user with an exclamation
  4622.           point icon.  The user may respond by selecting the OK button, or
  4623.           they may cancel the processing by selecting CANCEL.
  4624.  
  4625.           The Pause command is similar to the Message command except for the
  4626.           addition of the CANCEL button and icon.
  4627.  
  4628.           Example:
  4629.              Pause("Change Disks","Insert new disk into Drive A:")
  4630.  
  4631.           produces:
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.           See Also:
  4643.              Display, Message, Terminate
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.                                                                            104
  4659.  
  4660.                                                      CPML  FUNCTION  REFERENCE
  4661.  
  4662.  
  4663.  
  4664.           Random
  4665.           Computes a pseudo-random number.
  4666.  
  4667.           Syntax:
  4668.              Random (max)
  4669.  
  4670.           Parameters:
  4671.              "max" =   largest desired number.
  4672.  
  4673.           Returns:
  4674.              (integer) unpredictable positive number.
  4675.  
  4676.           This function will return a random integer between 0 and "max".
  4677.  
  4678.  
  4679.           Example:
  4680.           a = Random(79)
  4681.           Message("Random number between 0 and 79",a)
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.  
  4700.  
  4701.  
  4702.  
  4703.  
  4704.  
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.                                                                            105
  4715.  
  4716.                                                      CPML  FUNCTION  REFERENCE
  4717.  
  4718.  
  4719.  
  4720.           Run
  4721.           Runs a program as a normal window.
  4722.  
  4723.           Syntax:
  4724.              Run (program-name, parameters)
  4725.  
  4726.           Parameters:
  4727.              "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
  4728.                        file, or a data file.
  4729.              "parameters" = optional parameters as required by the applica-
  4730.                        tion.
  4731.  
  4732.           Returns:
  4733.              (integer) @TRUE if the program was found;
  4734.                        @FALSE if it wasn't.
  4735.  
  4736.           Use this command to run an application.
  4737.  
  4738.           If the drive and path are not part of the program name, the current
  4739.           directory will be examined first and then the DOS path will be
  4740.           searched to find the desired executable file.
  4741.           If the "program-name" doesn't have an extension of .EXE, .COM,
  4742.           .PIF, or .BAT, it will be run in accordance with whatever is in the
  4743.           [extensions] section of the WIN.INI file.  When this happens, any
  4744.           "parameters" you specified are ignored.
  4745.  
  4746.  
  4747.           Examples:
  4748.              Run("Notepad.exe","abc.txt")
  4749.              Run("clock.exe","")
  4750.              Run("paint.exe","pict.msp")
  4751.  
  4752.  
  4753.           See Also:
  4754.              RunHide, RunIcon, RunZoom, WinClose, WinWaitClose
  4755.  
  4756.  
  4757.  
  4758.  
  4759.  
  4760.  
  4761.  
  4762.  
  4763.  
  4764.  
  4765.  
  4766.  
  4767.  
  4768.  
  4769.  
  4770.                                                                            106
  4771.  
  4772.                                                      CPML  FUNCTION  REFERENCE
  4773.  
  4774.  
  4775.  
  4776.           RunHide
  4777.           Runs a program as a hidden window.
  4778.  
  4779.           Syntax:
  4780.              RunHide (program-name, parameters)
  4781.  
  4782.           Parameters:
  4783.              "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
  4784.                        file, or a data file.
  4785.              "parameters" = optional parameters as required by the
  4786.                        application.
  4787.  
  4788.           Returns:
  4789.              (integer) @TRUE if the program was found;
  4790.                        @FALSE if it wasn't.
  4791.  
  4792.           Use this command to run an application as a hidden window.
  4793.  
  4794.           If the drive and path are not part of the program name, the current
  4795.           directory will be examined first and then the DOS path will be
  4796.           searched to find the desired executable file.
  4797.           If the "program-name" doesn't have an extension of .EXE, .COM,
  4798.           .PIF, or .BAT, it will be run in accordance with whatever is in the
  4799.           [extensions] section of the WIN.INI file.  When this happens, any
  4800.           "parameters" you specified are ignored.
  4801.  
  4802.           Note:  When this command launches an application it informs it that
  4803.           you want it to run as a hidden window.  Whether or not the
  4804.           application honors your wish is beyond RunHide's control.
  4805.  
  4806.           Examples:
  4807.              RunHide("Notepad.exe","abc.txt")
  4808.              RunHide("clock.exe","")
  4809.              RunHide("paint.exe","pict.msp")
  4810.  
  4811.  
  4812.           See Also:
  4813.              Run, RunIcon, RunZoom, WinHide, WinClose, WinWaitClose
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.                                                                            107
  4827.  
  4828.                                                      CPML  FUNCTION  REFERENCE
  4829.  
  4830.  
  4831.  
  4832.           RunIcon
  4833.           Runs a program as an iconic (minimized) window.
  4834.  
  4835.           Syntax:
  4836.              RunIcon (program-name, parameters)
  4837.  
  4838.           Parameters:
  4839.              "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
  4840.                        file, or a data file.
  4841.              "parameters" = optional parameters as required by the
  4842.                        application.
  4843.  
  4844.           Returns:
  4845.              (integer) @TRUE if the program was found;
  4846.                        @FALSE if it wasn't.
  4847.  
  4848.           Use this command to run an application as an icon.
  4849.  
  4850.           If the drive and path are not part of the program name, the current
  4851.           directory will be examined first and then the DOS path will be
  4852.           searched to find the desired executable file.
  4853.           If the "program-name" doesn't have an extension of .EXE, .COM,
  4854.           .PIF, or .BAT, it will be run in accordance with whatever is in the
  4855.           [extensions] section of the WIN.INI file.  When this happens, any
  4856.           "parameters" you specified are ignored.
  4857.  
  4858.           Note:  When this command launches an application it merely informs
  4859.           it that you want it to begin as an icon.  Whether or not the
  4860.           application honors your wish is beyond RunIcon's control.
  4861.  
  4862.           Examples:
  4863.              RunIcon("Notepad.exe","abc.txt")
  4864.              RunIcon("clock.exe","")
  4865.              RunIcon("paint.exe","pict.msp")
  4866.  
  4867.  
  4868.           See Also:
  4869.              Run, RunHide, RunZoom, WinIconize, WinClose, WinWaitClose
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.                                                                            108
  4883.  
  4884.                                                      CPML  FUNCTION  REFERENCE
  4885.  
  4886.  
  4887.  
  4888.           RunZoom
  4889.           Runs a program as a full-screen (maximized) window.
  4890.  
  4891.           Syntax:
  4892.              RunZoom (program-name, parameters)
  4893.  
  4894.           Parameters:
  4895.              "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
  4896.                        file, or a data file.
  4897.              "parameters" = optional parameters as required by the
  4898.                        application.
  4899.  
  4900.           Returns:
  4901.              (integer) @TRUE if the program was found;
  4902.                        @FALSE if it wasn't.
  4903.  
  4904.           Use this command to run an application as a full-screen window.
  4905.  
  4906.           If the drive and path are not part of the program name, the current
  4907.           directory will be examined first and then the DOS path will be
  4908.           searched to find the desired executable file.
  4909.           If the "program-name" doesn't have an extension of .EXE, .COM,
  4910.           .PIF, or .BAT, it will be run in accordance with whatever is in the
  4911.           [extensions] section of the WIN.INI file.  When this happens, any
  4912.           "parameters" you specified are ignored.
  4913.  
  4914.           Note:  When this command launches an application it merely informs
  4915.           it that you want it to be maximized to full-screen.  Whether or not
  4916.           the application honors your wish is beyond RunZoom's control.
  4917.  
  4918.           Examples:
  4919.              RunZoom("Notepad.exe","abc.txt")
  4920.              RunZoom("clock.exe","")
  4921.              RunZoom("paint.exe","pict.msp")
  4922.  
  4923.  
  4924.           See Also:
  4925.              Run, RunHide, RunIcon, WinZoom, WinClose, WinWaitClose
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.                                                                            109
  4939.  
  4940.                                                      CPML  FUNCTION  REFERENCE
  4941.  
  4942.  
  4943.  
  4944.           SetDisplay
  4945.           Controls the display of files in the Command Post File Manager
  4946.           window.
  4947.  
  4948.           Syntax:
  4949.              SetDisplay (detail, sort-by, masks)
  4950.  
  4951.           Parameters:
  4952.              "detail" =  level of detail.  Use "SHORT" or "LONG".
  4953.              "sort-by" = how to sort the filenames.  Use "NAME", "KIND",
  4954.                        "SIZE", "DATE" or "UNSORTED".
  4955.              "masks" = list of masks for file display.
  4956.  
  4957.           Returns:
  4958.              (integer) @TRUE if valid options were specified;
  4959.                        @FALSE if invalid.
  4960.  
  4961.           Use this command to change and/or update the file display.
  4962.  
  4963.           Any of the fields may be null.  If a field is null the previous
  4964.           setting is used.  This command will alter the file display
  4965.           Parameters:, and then re-read all the files and update the display.
  4966.           A special form of this command, SETDISPLAY ("","",""), will update
  4967.           the file display without changing any of the previously set
  4968.           Parameters.
  4969.  
  4970.  
  4971.           Errors:
  4972.              2105 "SetDisplay: Display type not SHORT or LONG"
  4973.              2106 "SetDisplay: Sort Type not NAME, DATE, SIZE, KIND, or
  4974.                   UNSORTED"
  4975.  
  4976.           Example:
  4977.           Windows &SDK
  4978.            &Show SDK Development Files
  4979.              SetDisplay ("","","*.ICO *.CUR *.BMP *.DLG *.H")
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.                                                                            110
  4995.  
  4996.                                                      CPML  FUNCTION  REFERENCE
  4997.  
  4998.  
  4999.  
  5000.           StrCat
  5001.           Concatenates two or more strings.
  5002.  
  5003.           Syntax:
  5004.              StrCat (string1, string2[, stringN]...)
  5005.  
  5006.           Parameters:
  5007.              "string1", etc = at least two strings you want to "string"
  5008.                        together (so to speak).
  5009.  
  5010.           Returns:
  5011.              (string)  concatenation of the entire list of input strings.
  5012.  
  5013.           Use this command to stick character strings together, or to format
  5014.           display messages.
  5015.  
  5016.  
  5017.           Errors:
  5018.              2058 "StrCat function syntax error"
  5019.  
  5020.           Example:
  5021.              User=AskLine("Login", "Your Name:", "")
  5022.              Message("Login",strcat("Hi, ",User))
  5023.              ;note that this will do the same:
  5024.              Message("Login","Hi, %User%")
  5025.  
  5026.  
  5027.           See Also:
  5028.              StrFill, StrFix, StrTrim
  5029.  
  5030.  
  5031.  
  5032.  
  5033.  
  5034.  
  5035.  
  5036.  
  5037.  
  5038.  
  5039.  
  5040.  
  5041.  
  5042.  
  5043.  
  5044.  
  5045.  
  5046.  
  5047.  
  5048.  
  5049.  
  5050.                                                                            111
  5051.  
  5052.                                                      CPML  FUNCTION  REFERENCE
  5053.  
  5054.  
  5055.  
  5056.           StrCmp
  5057.           Compares two strings.
  5058.  
  5059.           Syntax:
  5060.              StrCmp (string1, string2)
  5061.  
  5062.           Parameters:
  5063.              "string1", "string2" =
  5064.                        strings to compare.
  5065.  
  5066.           Returns:
  5067.              (integer) -1, 0, or 1; depending on whether string1 is less than,
  5068.                        equal to, or greater than string2, respectively.
  5069.  
  5070.           Use this command to determine whether two strings are equal, or
  5071.           which precedes the other in an ASCII sorting sequence.
  5072.  
  5073.           Note:  This command has been included for semantic completeness.
  5074.           The relational operators >, >=, ==, !=, <=, and < provide the same
  5075.           capability.
  5076.  
  5077.           Example:
  5078.              a=AskLine("STRCMP","Enter a test line","")
  5079.              b=AskLine("STRCMP","Enter another test line","")
  5080.              c=strcmp(a,b)
  5081.              c=c+1
  5082.              d=strsub("less than   equal to    greater than",c*12,12)
  5083.              ;Note that above string is grouped into 12-character chunks.
  5084.              ;Desired chunk is removed with the strsub statement.
  5085.              message("STRCMP","%a% is %d% %b%")
  5086.  
  5087.  
  5088.           See Also:
  5089.              StrICmp, StrIndex, StrLen, StrScan, StrSub
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.  
  5100.  
  5101.  
  5102.  
  5103.  
  5104.  
  5105.  
  5106.                                                                            112
  5107.  
  5108.                                                      CPML  FUNCTION  REFERENCE
  5109.  
  5110.  
  5111.  
  5112.           StrFill
  5113.           Creates a string filled with a series of characters.
  5114.  
  5115.           Syntax:
  5116.              StrFill (filler, length)
  5117.  
  5118.           Parameters:
  5119.              "filler" =  a string to be repeated to create the return string.
  5120.                        If the filler string is null, spaces will be used
  5121.                        instead.
  5122.              "length" =  the length of the desired string.
  5123.  
  5124.  
  5125.           Returns:
  5126.              (string)  character string.
  5127.  
  5128.           Use this function to create a string consisting of multiple copies
  5129.           of the filler string concatenated together.
  5130.  
  5131.           Example:
  5132.              Message("My Stars",strfill("*",30))
  5133.  
  5134.  
  5135.           See Also:
  5136.              StrCat, StrFix, StrLen, StrTrim
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.  
  5162.                                                                            113
  5163.  
  5164.                                                      CPML  FUNCTION  REFERENCE
  5165.  
  5166.  
  5167.  
  5168.           StrFix
  5169.           Pads or truncates a string to a fixed length.
  5170.  
  5171.           Syntax:
  5172.              StrFix (base-string, pad-string, length)
  5173.  
  5174.           Parameters:
  5175.              "base-string" =  string to be adjusted to a fixed length.
  5176.              "pad-string" = appended to "base-string" if needed to fill out
  5177.                        the desired length.  If "pad-string" is null, spaces
  5178.                        are used instead.
  5179.              "length" =  length of the desired string.
  5180.  
  5181.           Returns:
  5182.              (string)  fixed size string.
  5183.  
  5184.           This function "fixes" the length of a string, either by truncating
  5185.           it on the right, or by appending enough copies of pad-string to
  5186.           achieve the desired length.
  5187.  
  5188.  
  5189.           Example:
  5190.              a=StrFix("Henry"," ",15)
  5191.              b=StrFix("Betty"," ",15)
  5192.              c=StrFix("George"," ",15)
  5193.              Message("Spaced Names",strcat(a,b,c))
  5194.  
  5195.  
  5196.           See Also:
  5197.              StrFill, StrLen, StrTrim
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.                                                                            114
  5219.  
  5220.                                                      CPML  FUNCTION  REFERENCE
  5221.  
  5222.  
  5223.  
  5224.           StriCmp
  5225.           Compares two strings without regard to case.
  5226.  
  5227.           Syntax:
  5228.              StrICmp (string1, string2)
  5229.  
  5230.           Parameters:
  5231.              "string1", "string2" =strings to compare.
  5232.  
  5233.           Returns:
  5234.              (integer) -1, 0, or 1; depending on whether string1 is less than,
  5235.                        equal to, or greater than string2, respectively.
  5236.  
  5237.           Use this command to determine whether two strings are equal, or
  5238.           which precedes the other in an ACSII sorting sequence, when case is
  5239.           ignored.
  5240.  
  5241.  
  5242.           Example:
  5243.              a=AskLine("STRICMP","Enter a test line","")
  5244.              b=AskLine("STRICMP","Enter another test line","")
  5245.              c=stricmp(a,b)
  5246.              c=c+1
  5247.              d=strsub("less than   equal to    greater than",c*12,12)
  5248.              ;Note that above string is grouped into 12-character chunks.
  5249.              ;Desired chunk is removed with the strsub statement.
  5250.              message("STRICMP","%a% is %d% %b%")
  5251.  
  5252.  
  5253.           See Also:
  5254.              StrCmp, StrIndex, StrLen, StrScan, StrSub
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.                                                                            115
  5275.  
  5276.                                                      CPML  FUNCTION  REFERENCE
  5277.  
  5278.  
  5279.  
  5280.           StrIndex
  5281.           Searches a string for a substring.
  5282.  
  5283.           Syntax:
  5284.              StrIndex (string, sub-string, start, direction)
  5285.  
  5286.           Parameters:
  5287.              "string" =  the string to be searched for a substring.
  5288.              "substring" =  the string to look for within the main string.
  5289.              "start" = the position in the main string to begin the search.
  5290.                        The first character of a string is position 1.
  5291.              "direction" =  the search direction.  @FWDSCAN searches forward,
  5292.                        while @BACKSCAN searches backwards.
  5293.  
  5294.           Returns:
  5295.              (integer) position of "sub-string" within "string";
  5296.                        0 if not found.
  5297.  
  5298.           This function searches for a substring within a "target" string.
  5299.           Starting at the "start" position, it goes forward or backward
  5300.           depending on the value of the "direction" parameter.  It stops when
  5301.           it finds the "substring" within the "target" string, and returns
  5302.           its position.
  5303.  
  5304.           A start position of 0 has special meaning depending on which
  5305.           direction you are scanning.  For forward searches zero indicates
  5306.           the search should start at the beginning of the string.  For
  5307.           reverse searches zero causes it to start at the end of the string.
  5308.  
  5309.           Errors:
  5310.              3100 "StrIndex/StrScan 3rd parameter out of bounds"
  5311.  
  5312.           Example:
  5313.              Instr = AskLine ("STRINDEX", "Type a sentence:", "")
  5314.              start=1
  5315.              end=strindex(InStr," ",start,@FWDSCAN)
  5316.              terminate(end==0,"Sorry...","No spaces found")
  5317.              message("STRINDEX",strcat("The first word is: ",
  5318.                                  strsub(InStr,start,end-1))
  5319.              exit
  5320.  
  5321.  
  5322.           See Also:
  5323.              StrLen, StrScan, StrSub
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.                                                                            116
  5331.  
  5332.                                                      CPML  FUNCTION  REFERENCE
  5333.  
  5334.  
  5335.  
  5336.           StrLen
  5337.           Provides the length of a string.
  5338.  
  5339.           Syntax:
  5340.              StrLen (string)
  5341.  
  5342.           Parameters:
  5343.              "string" =  any text string.
  5344.  
  5345.           Returns:
  5346.              (integer) length of string.
  5347.  
  5348.           Use this command to determine the length of a string variable or
  5349.           expression.
  5350.  
  5351.  
  5352.           Example:
  5353.              MyFile=AskLine("Filename","File to process:","")
  5354.              FilenameLen=strlen(MyFile)
  5355.              Terminate(FilenameLen>13, "", "Filename too long!")
  5356.  
  5357.  
  5358.           See Also:
  5359.              StrFill, StrFix, StrIndex, StrScan, StrTrim
  5360.  
  5361.  
  5362.  
  5363.  
  5364.  
  5365.  
  5366.  
  5367.  
  5368.  
  5369.  
  5370.  
  5371.  
  5372.  
  5373.  
  5374.  
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.  
  5381.  
  5382.  
  5383.  
  5384.  
  5385.  
  5386.                                                                            117
  5387.  
  5388.                                                      CPML  FUNCTION  REFERENCE
  5389.  
  5390.  
  5391.  
  5392.           StrLower
  5393.           Converts a string to lowercase.
  5394.  
  5395.           Syntax:
  5396.              StrLower (string)
  5397.  
  5398.           Parameters:
  5399.              "string" =  any text string.
  5400.  
  5401.           Returns:
  5402.              (string)  lowercase string.
  5403.  
  5404.           Use this command to convert a text string to lower case.
  5405.  
  5406.  
  5407.           Example:
  5408.              a=AskLine("STRLOWER","Enter text","")
  5409.              b=strlower(a)
  5410.              message(a,b)
  5411.  
  5412.  
  5413.           See Also:
  5414.              StrICmp, StrUpper
  5415.  
  5416.  
  5417.  
  5418.  
  5419.  
  5420.  
  5421.  
  5422.  
  5423.  
  5424.  
  5425.  
  5426.  
  5427.  
  5428.  
  5429.  
  5430.  
  5431.  
  5432.  
  5433.  
  5434.  
  5435.  
  5436.  
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.                                                                            118
  5443.  
  5444.                                                      CPML  FUNCTION  REFERENCE
  5445.  
  5446.  
  5447.  
  5448.           StrScan
  5449.           Searches string for occurrence of delimiters.
  5450.  
  5451.           Syntax:
  5452.              StrScan (string, delimiters, start, direction)
  5453.  
  5454.           Parameters:
  5455.              "string" =  the string that is to be searched.
  5456.              "delimiters" = a string of delimiters to search for within
  5457.                        "string".
  5458.              "start" = the position in the main string to begin the search.
  5459.                        The first character of a string is  position 1.
  5460.              "direction" =  the search direction.  @FWDSCAN searches forward,
  5461.                        while @BACKSCAN searches backwards.
  5462.  
  5463.           Returns:
  5464.              (integer) position of delimiter in string, or 0 if not found.
  5465.  
  5466.           This function searches for delimiters within a target "string".
  5467.           Starting at the "start" position, it goes forward or backward
  5468.           depending on the value of the "direction" parameter.  It stops when
  5469.           it finds any one of the characters in the "delimiters" string
  5470.           within the target "string".
  5471.  
  5472.  
  5473.           Errors:
  5474.              3100 "StrIndex/StrScan 3rd parameter out of bounds"
  5475.  
  5476.           Example:
  5477.              TheStr="123,456.789:abc"
  5478.              start=1
  5479.              end=strscan(TheStr,",.:",start,@FWDSCAN)
  5480.              terminate(end==0,"Sorry...","No delimiters found")
  5481.              message("The first parameter",strsub(
  5482.                                  TheStr,start,end-start+1))
  5483.              exit
  5484.  
  5485.  
  5486.           See Also:
  5487.              StrLen, StrSub
  5488.  
  5489.  
  5490.  
  5491.  
  5492.  
  5493.  
  5494.  
  5495.  
  5496.  
  5497.  
  5498.                                                                            119
  5499.  
  5500.                                                      CPML  FUNCTION  REFERENCE
  5501.  
  5502.  
  5503.  
  5504.           StrSub
  5505.           Extracts a substring out of an existing string.
  5506.  
  5507.           Syntax:
  5508.              StrSub (string, start, length)
  5509.  
  5510.           Parameters:
  5511.              "string" =  the string from which the substring is to be
  5512.                        extracted.
  5513.              "start" = character position within "string" where the sub-string
  5514.                        starts.  (The first character of the string is at
  5515.                        position 1).
  5516.              "length" =  length of desired substring.  If you specify a
  5517.                        length of zero it will return a null string.
  5518.  
  5519.           Returns:
  5520.              (string)  substring of parameter string.
  5521.  
  5522.           This function extracts a substring from within a "target" string.
  5523.           Starting at the "start" position, it copies up to "length"
  5524.           characters into the substring.
  5525.  
  5526.  
  5527.           Errors:
  5528.              3059 "Illegal Bounds for STRSUB function"
  5529.  
  5530.           Example:
  5531.              a="My dog has fleas"
  5532.              animal=strsub(a,4,3)
  5533.              Message("STRSUB","My animal is a %animal%")
  5534.  
  5535.  
  5536.           See Also:
  5537.              StrLen, StrScan
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.                                                                            120
  5555.  
  5556.                                                      CPML  FUNCTION  REFERENCE
  5557.  
  5558.  
  5559.  
  5560.           StrTrim
  5561.           Removes leading and trailing spaces from a character string.
  5562.  
  5563.           Syntax:
  5564.              StrTrim (string)
  5565.  
  5566.           Parameters:
  5567.              "string" =  a string with unwanted spaces at the beginning
  5568.                        and/or the end.
  5569.  
  5570.           Returns:
  5571.              (string)  string devoid of leading and trailing spaces.
  5572.  
  5573.           Use this function to remove unwanted spaces from the beginning and
  5574.           end of text data.
  5575.  
  5576.  
  5577.           Example:
  5578.              TheFile = AskLine("STRTRIM","Filename ('exit' cancels)","")
  5579.              TstExit = strtrim(strlower(TheFile))
  5580.              Terminate(TstExit=="exit","Cancelled","...by user request")
  5581.              ;processing of TheFile continues...
  5582.  
  5583.  
  5584.           See Also:
  5585.              StrFill, StrFix, StrLen
  5586.  
  5587.  
  5588.  
  5589.  
  5590.  
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.  
  5606.  
  5607.  
  5608.  
  5609.  
  5610.                                                                            121
  5611.  
  5612.                                                      CPML  FUNCTION  REFERENCE
  5613.  
  5614.  
  5615.  
  5616.           StrUpper
  5617.           Converts a string to uppercase.
  5618.  
  5619.           Syntax:
  5620.              StrUpper (string)
  5621.  
  5622.           Parameters:
  5623.              "string" =  any text string.
  5624.  
  5625.           Returns:
  5626.              (string)  uppercase string.
  5627.  
  5628.           Use this function to convert a text string to upper case.
  5629.  
  5630.  
  5631.           Example:
  5632.              a=AskLine("STRUPPER","Enter text","")
  5633.              b=strupper(a)
  5634.              message(a,b)
  5635.  
  5636.  
  5637.           See Also:
  5638.              StrICmp, StrLower
  5639.  
  5640.  
  5641.  
  5642.  
  5643.  
  5644.  
  5645.  
  5646.  
  5647.  
  5648.  
  5649.  
  5650.  
  5651.  
  5652.  
  5653.  
  5654.  
  5655.  
  5656.  
  5657.  
  5658.  
  5659.  
  5660.  
  5661.  
  5662.  
  5663.  
  5664.  
  5665.  
  5666.                                                                            122
  5667.  
  5668.                                                      CPML  FUNCTION  REFERENCE
  5669.  
  5670.  
  5671.  
  5672.           Terminate
  5673.           Conditionally ends the menuitem.
  5674.  
  5675.           Syntax:
  5676.              Terminate (expression, title, message)
  5677.  
  5678.           Parameters:
  5679.              "expression" = any logical expression.
  5680.              "title" = the title of a message box to be displayed before
  5681.                        termination.
  5682.              "message" = the message in the message box.
  5683.  
  5684.           Returns:
  5685.              (integer) always @TRUE.
  5686.  
  5687.           This command ends processing for the menu item if "expression" is
  5688.           nonzero.  Note that many functions return @TRUE (1) or @FALSE (0),
  5689.           which you can use to decide whether to cancel a menu item.
  5690.  
  5691.           If either "title" or "message" contains a string, a message box
  5692.           with a title and a message is displayed before exiting.
  5693.  
  5694.           Examples:
  5695.              ;Unconditional Termination w/o message box.
  5696.              ;Same as "Exit":
  5697.              Terminate(@TRUE,"","")
  5698.  
  5699.              ;Basically a no-op:
  5700.              Terminate(@FALSE,"","This will never terminate")
  5701.  
  5702.              ;Exits with message if a is less than zero:
  5703.              Terminate(a<0,"Error","Cannot use negative numbers")
  5704.  
  5705.  
  5706.  
  5707.  
  5708.  
  5709.  
  5710.  
  5711.  
  5712.              ;Exits w/o message if answer isn't "YES":
  5713.              Terminate(answer!="YES","","")
  5714.  
  5715.  
  5716.           See Also:
  5717.              Display, Pause, Message
  5718.  
  5719.  
  5720.  
  5721.  
  5722.                                                                            123
  5723.  
  5724.                                                      CPML  FUNCTION  REFERENCE
  5725.  
  5726.           TextBox
  5727.           Displays a file in a listbox on the screen and returns selected
  5728.           line, if any.
  5729.  
  5730.           Syntax:
  5731.              TextBox (title, filename)
  5732.  
  5733.           Parameters:
  5734.              "title" = listbox title.
  5735.              "filename" =file containing contents of listbox.
  5736.  
  5737.           Returns:
  5738.              (string) =  highlighted string, if any.
  5739.  
  5740.           The TextBox command loads a file into a Windows listbox and
  5741.           displays the listbox to the user.  The command has two primary
  5742.           uses:  First off, it can be used to display multi-line messages to
  5743.           the user.  In addition, because of its ability to return a selected
  5744.           line, it may be used as a multiple choice question box.  The line
  5745.           highlighted by the user (if any) will be returned to the program.
  5746.  
  5747.           If disk drive and path not are part of the filename,  the current
  5748.           directory will be examined first, and then the DOS path will be
  5749.           searched to find the desired file.
  5750.  
  5751.           Example:
  5752.              ;Display config.sys:
  5753.              a=TextBox("Choose a line","C:\CONFIG.SYS")
  5754.              display(3,"Chosen line",a)
  5755.  
  5756.  
  5757.  
  5758.  
  5759.  
  5760.  
  5761.  
  5762.  
  5763.  
  5764.  
  5765.  
  5766.  
  5767.  
  5768.  
  5769.  
  5770.  
  5771.  
  5772.  
  5773.  
  5774.  
  5775.           See Also:
  5776.              ItemSelect
  5777.  
  5778.                                                                            124
  5779.  
  5780.                                                      CPML  FUNCTION  REFERENCE
  5781.  
  5782.           Version
  5783.           Returns the version number of the currently-running Command Post
  5784.           language processor.
  5785.  
  5786.           Syntax:
  5787.              Version ( )
  5788.  
  5789.           Returns:
  5790.              (string) =  Command Post version number.
  5791.  
  5792.           Use this function to determine the version of Command Post that is
  5793.           running.  It is useful to verify that a menu generated with the
  5794.           latest version of the language will operate properly on what may be
  5795.           a different machine with a different version of Command Post
  5796.           installed.
  5797.  
  5798.  
  5799.           Example:
  5800.              a=Version()
  5801.  
  5802.  
  5803.           See Also:
  5804.              Environment, WinVersion
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.  
  5822.  
  5823.  
  5824.  
  5825.  
  5826.  
  5827.  
  5828.  
  5829.  
  5830.  
  5831.  
  5832.  
  5833.  
  5834.                                                                            125
  5835.  
  5836.                                                      CPML  FUNCTION  REFERENCE
  5837.  
  5838.  
  5839.  
  5840.           WinActivate
  5841.           Activates a previously running window.
  5842.  
  5843.           Syntax:
  5844.              WinActivate (partial-windowname)
  5845.  
  5846.           Parameters:
  5847.              "partial-windowname" =
  5848.                        either an initial portion of, or an entire window name.
  5849.                        The most-recently used window whose title matches the
  5850.                        name will be activated.
  5851.  
  5852.           Returns:
  5853.              (integer) @TRUE if a window was found to activate;
  5854.                        @FALSE if no windows were found.
  5855.  
  5856.           Use this command to activate windows for user input.
  5857.  
  5858.  
  5859.           Errors:
  5860.              1045 "WinActivate: Window not found"
  5861.  
  5862.           Example:
  5863.              Run("notepad.exe","")
  5864.              Run("clock.exe","")
  5865.              WinActivate("Notepad")
  5866.  
  5867.  
  5868.           See Also:
  5869.              WinCloseNot, WinGetActive, WinShow
  5870.  
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.  
  5879.  
  5880.  
  5881.  
  5882.  
  5883.  
  5884.  
  5885.  
  5886.  
  5887.  
  5888.  
  5889.  
  5890.                                                                            126
  5891.  
  5892.                                                      CPML  FUNCTION  REFERENCE
  5893.  
  5894.  
  5895.  
  5896.           WinArrange
  5897.           Arranges, tiles, and/or stacks application windows.
  5898.  
  5899.           Syntax:
  5900.              WinArrange (style)
  5901.  
  5902.           Parameters:
  5903.              style =   one of the following:  @STACK, @TILE (or @ARRANGE),
  5904.                        @ROWS, or @COLUMNS.
  5905.  
  5906.           Returns:
  5907.              (integer) always @TRUE.
  5908.  
  5909.           Use this command to rearrange the open windows on the screen.  (Any
  5910.           iconized programs are unaffected.)
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.                                 @STACKED          @TILED
  5923.  
  5924.  
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.                                 @ROWS          @COLUMNS
  5934.  
  5935.           When you specify @ROWS and you have more than four open windows, or
  5936.           if you specify @COLUMNS and you have more than three open windows,
  5937.           Command Post will revert to @TILE.
  5938.  
  5939.  
  5940.           See Also:
  5941.              WinItemize, WinHide, WinIconize, WinPlace, WinShow, WinZoom
  5942.  
  5943.  
  5944.  
  5945.  
  5946.                                                                            127
  5947.  
  5948.                                                      CPML  FUNCTION  REFERENCE
  5949.  
  5950.           WinClose
  5951.           Closes an open window.
  5952.  
  5953.           Syntax:
  5954.              WinClose (partial-windowname)
  5955.  
  5956.           Parameters:
  5957.              "partial-windowname" =
  5958.                        either an initial portion of, or an entire window name.
  5959.                        The most-recently used window whose title matches the
  5960.                        name will be closed.
  5961.  
  5962.           Returns:
  5963.              (integer) @TRUE if a window was found to close;
  5964.                        @FALSE if no windows were found.
  5965.  
  5966.           Use this command to close windows.
  5967.  
  5968.           This command will not close the current Command Post window.  You
  5969.           can, however, call EndSession to end the current Windows session.
  5970.  
  5971.           Errors:
  5972.              1039 "WinClose: Window not found"
  5973.  
  5974.           Example:
  5975.              Run ("notepad.exe","")
  5976.              WinClose("Notepad")
  5977.  
  5978.  
  5979.           See Also:
  5980.              WinCloseNot, WinHide, WinIconize, WinWaitClose
  5981.  
  5982.  
  5983.  
  5984.  
  5985.  
  5986.  
  5987.  
  5988.  
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.  
  6001.  
  6002.                                                                            128
  6003.  
  6004.                                                      CPML  FUNCTION  REFERENCE
  6005.  
  6006.  
  6007.  
  6008.           WinCloseNot
  6009.           Closes all windows, except those provided as parameters:.
  6010.  
  6011.           Syntax:
  6012.              WinCloseNot (partial-windowname [, partial-windowname]...)
  6013.  
  6014.           Parameters:
  6015.              partial-windowname =
  6016.                        either an initial portion of, or an entire window name.
  6017.                        Any windows whose titles match the partial names will
  6018.                        stay open.
  6019.  
  6020.           Returns:
  6021.              (integer) always @TRUE.
  6022.  
  6023.           Use this command to close all windows except those specifically
  6024.           listed in the parameter strings.
  6025.  
  6026.           At least one partial windowname must be given.  A null-string
  6027.           parameter would match all windows, or in other words close nothing.
  6028.  
  6029.           Errors:
  6030.              2038 "WinCloseNot Function Syntax error"
  6031.  
  6032.           Example:
  6033.              ;The statement below will close all windows except:
  6034.              ;1) MS-DOS Executive (starts with 'MS-D')
  6035.              ;2) Clock  (starts with 'Clo' )
  6036.  
  6037.              WinCloseNot("MS-D","Clo")
  6038.  
  6039.  
  6040.           See Also:
  6041.              WinItemize, WinClose, WinHide, WinIconize, WinWaitClose
  6042.  
  6043.  
  6044.  
  6045.  
  6046.  
  6047.  
  6048.  
  6049.  
  6050.  
  6051.  
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.                                                                            129
  6059.  
  6060.                                                      CPML  FUNCTION  REFERENCE
  6061.  
  6062.  
  6063.  
  6064.           WinGetActive
  6065.           Gets the title of the active window.
  6066.  
  6067.           Syntax:
  6068.              WinGetActive ( )
  6069.  
  6070.           Returns:
  6071.              (string)  title of active window.
  6072.  
  6073.           Use this command to determine which window is currently active.
  6074.  
  6075.  
  6076.           Example:
  6077.              CurrentWin=WinGetActive()
  6078.  
  6079.  
  6080.           See Also:
  6081.              WinItemize, WinActivate
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.  
  6090.  
  6091.  
  6092.  
  6093.  
  6094.  
  6095.  
  6096.  
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.  
  6107.  
  6108.  
  6109.  
  6110.  
  6111.  
  6112.  
  6113.  
  6114.                                                                            130
  6115.  
  6116.                                                      CPML  FUNCTION  REFERENCE
  6117.  
  6118.  
  6119.  
  6120.           WinHide
  6121.           Hides a window.
  6122.  
  6123.           Syntax:
  6124.              WinHide (partial-windowname)
  6125.  
  6126.           Parameters:
  6127.              "partial-windowname" =
  6128.                        either an initial portion of, or an entire window name.
  6129.                        The most-recently used window whose title matches the
  6130.                        name will be hidden.
  6131.  
  6132.           Returns:
  6133.              (integer) @TRUE if a window was found to hide;
  6134.                        @FALSE if no windows were found.
  6135.  
  6136.           Use this command to hide windows.  The programs are still running
  6137.           when they are hidden.
  6138.  
  6139.           A partial-windowname of "" hides the current Command Post window.
  6140.  
  6141.           Errors:
  6142.              1040 "WinHide: Window not found"
  6143.  
  6144.           Example:
  6145.              Run("notepad.exe","")
  6146.              WinHide("Notepad")
  6147.              WinShow("Notepad")
  6148.  
  6149.  
  6150.           See Also:
  6151.              WinClose, WinIconize, WinPlace
  6152.  
  6153.  
  6154.  
  6155.  
  6156.  
  6157.  
  6158.  
  6159.  
  6160.  
  6161.  
  6162.  
  6163.  
  6164.  
  6165.  
  6166.  
  6167.  
  6168.  
  6169.  
  6170.                                                                            131
  6171.  
  6172.                                                      CPML  FUNCTION  REFERENCE
  6173.  
  6174.  
  6175.  
  6176.           WinIconize
  6177.           Iconizes a window.
  6178.  
  6179.           Syntax:
  6180.              WinIconize (partial-windowname)
  6181.  
  6182.           Parameters:
  6183.              "partial-windowname" =
  6184.                        either an initial portion of, or an entire window name.
  6185.                        The most-recently used window whose title matches the
  6186.                        name will be iconized.
  6187.  
  6188.           Returns:
  6189.              (integer) @TRUE if a window was found to iconize;
  6190.                        @FALSE if no windows were found.
  6191.  
  6192.           Use this command to turn a window into an icon at the bottom of the
  6193.           screen.
  6194.  
  6195.           A partial-windowname of "" iconizes the current Command Post
  6196.           window.
  6197.  
  6198.           Errors:
  6199.              1041 "WinIconize: Window not found"
  6200.  
  6201.           Example:
  6202.              Run("clock.exe","")
  6203.              WinIconize("Clo") ; partial window name used here
  6204.  
  6205.  
  6206.           See Also:
  6207.              WinClose, WinHide, WinPlace, WinShow, WinZoom
  6208.  
  6209.  
  6210.  
  6211.  
  6212.  
  6213.  
  6214.  
  6215.  
  6216.  
  6217.  
  6218.  
  6219.  
  6220.  
  6221.  
  6222.  
  6223.  
  6224.  
  6225.  
  6226.                                                                            132
  6227.  
  6228.                                                      CPML  FUNCTION  REFERENCE
  6229.  
  6230.  
  6231.  
  6232.           WinItemize
  6233.           Returns a tab-delimited list of all open windows.
  6234.  
  6235.           Syntax:
  6236.              WinItemize ( )
  6237.  
  6238.           Returns:
  6239.              (string)  list of all open windows' titles.
  6240.  
  6241.           This function compiles a list of all the open application windows'
  6242.           titles and separates the titles by tabs.  This is especially useful
  6243.           in conjunction with the ItemSelect function, which enables the user
  6244.           to choose an item from such a tab-delimited list.
  6245.  
  6246.           Note this behaves somewhat differently than FileItemize and
  6247.           DirItemize, which create space-delimited lists.  This is because
  6248.           window titles regularly contain embedded spaces.
  6249.  
  6250.           Example:
  6251.           &Windows
  6252.            &Find a window
  6253.              AllWins = WinItemize()
  6254.              HTab = Num2Char(9)
  6255.              MyWind = ItemSelect("Windows",AllWins, HTab)
  6256.              WinActivate(MyWind)
  6257.  
  6258.  
  6259.           See Also:
  6260.              DirItemize, FileItemize, ItemSelect
  6261.  
  6262.  
  6263.  
  6264.  
  6265.  
  6266.  
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.  
  6276.  
  6277.  
  6278.  
  6279.  
  6280.  
  6281.  
  6282.                                                                            133
  6283.  
  6284.                                                      CPML  FUNCTION  REFERENCE
  6285.  
  6286.  
  6287.  
  6288.           WinPlace
  6289.           Places a window anywhere on the screen.
  6290.  
  6291.           Syntax:
  6292.              WinPlace (x-ulc, y-ulc, x-brc, y-brc, partial-windowname)
  6293.  
  6294.           Parameters:
  6295.              x-ulc =   how far from the left of the screen to place the upper-
  6296.                        left corner (0-1000).
  6297.              y-ulc =   how far from the top of the screen to place the upper-
  6298.                        left corner (0-1000).
  6299.              x-brc =   how far from the left of the screen to place the
  6300.                        bottom-right corner (10-1000) or @NORESIZE.
  6301.              y-brc =   how far from the top of the screen to place the bottom-
  6302.                        right corner (10-1000) or @NORESIZE or @ABOVEICONS.
  6303.              "partial-windowname" =
  6304.                        either an initial portion of, or an entire window name.
  6305.                        The most-recently used window whose title matches the
  6306.                        name will be moved to the new position.
  6307.  
  6308.           Returns:
  6309.              (integer) @TRUE if a window was found to move;
  6310.                        @FALSE if no windows were found.
  6311.  
  6312.           Use this command to move windows on the screen.  (You cannot,
  6313.           however, move icons or windows that have been maximized to full
  6314.           screen.)  A partial-windowname of "" moves the current Command Post
  6315.           window.
  6316.  
  6317.           The "x-ulc", "y-ulc", "x-brc", and "y-brc" parameters are based on
  6318.           a logical screen that is 1000 points wide by 1000 points high.
  6319.           You can move the window without changing the width and/or height by
  6320.           specifying @NORESIZE for the "x-brc" and/or "y-brc" parameters,
  6321.           respectively.
  6322.  
  6323.           You can fix the bottom of the window to sit just above the line of
  6324.           icons along the bottom of the screen by specifying a "y-brc" of
  6325.           @ABOVEICONS.
  6326.           Some sample parameters:
  6327.              Upper left quarter of the screen:  0, 0, 500, 500
  6328.              Upper right quarter:  500, 0, 500, 1000
  6329.              Center quarter:  250, 250, 750, 750
  6330.              Lower left eighth:  0, 750, 500, 1000
  6331.  
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.                                                                            134
  6339.  
  6340.                                                      CPML  FUNCTION  REFERENCE
  6341.  
  6342.           A handy utility program is included with Command Post, called
  6343.           WinInfo.exe.  This program lets you take an open window that is
  6344.           sized and positioned the way you like it, and automatically create
  6345.           the proper WinPlace statement for you.  It puts the text into the
  6346.           Clipboard, from which you can paste it into your menu code:
  6347.  
  6348.  
  6349.  
  6350.  
  6351.  
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.  
  6358.  
  6359.  
  6360.  
  6361.           You'll need a mouse to use WinInfo.  While WinInfo is the active
  6362.           window, place the mouse over the window you wish to create the
  6363.           WinPlace statement for, and press the spacebar.  The new statement
  6364.           will be placed into the Clipboard.  Then press the Esc key to close
  6365.           WinInfo.
  6366.  
  6367.           Errors:
  6368.              1044 "WinPlace: Window not found"
  6369.  
  6370.           Example:
  6371.              WinPlace(0,0,200,200,"Clock")
  6372.  
  6373.  
  6374.           See Also:
  6375.              WinArrange, WinHide, WinIconize, WinShow, WinZoom
  6376.  
  6377.  
  6378.  
  6379.  
  6380.  
  6381.  
  6382.  
  6383.  
  6384.  
  6385.  
  6386.  
  6387.  
  6388.  
  6389.  
  6390.  
  6391.  
  6392.  
  6393.  
  6394.                                                                            135
  6395.  
  6396.                                                      CPML  FUNCTION  REFERENCE
  6397.  
  6398.  
  6399.  
  6400.           WinShow
  6401.           Shows a window in its "normal" state.
  6402.  
  6403.           Syntax:
  6404.              WinShow (partial-windowname)
  6405.  
  6406.           Parameters:
  6407.              "partial-windowname" =
  6408.                        either an initial portion of, or an entire window name.
  6409.                        The most-recently used window whose title matches the
  6410.                        name will be shown.
  6411.  
  6412.           Returns:
  6413.              (integer) @TRUE if a window was found to show;
  6414.                        @FALSE if no windows were found.
  6415.  
  6416.           Use this command to restore a window to its "normal" size and
  6417.           position.
  6418.  
  6419.           A partial-windowname of "" restores the current Command Post
  6420.           window.
  6421.  
  6422.           Errors:
  6423.              1043 "WinShow: Window not found"
  6424.  
  6425.           Example:
  6426.              RunZoom("notepad.exe","")
  6427.              ;other processing...
  6428.              WinShow("Notepad")
  6429.  
  6430.  
  6431.           See Also:
  6432.              WinArrange, WinHide, WinIconize, WinZoom
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.  
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.                                                                            136
  6451.  
  6452.                                                      CPML  FUNCTION  REFERENCE
  6453.  
  6454.  
  6455.  
  6456.           WinTitle
  6457.           Changes the title of a window.
  6458.  
  6459.           Syntax:
  6460.              WinTitle (partial-windowname, new-name)
  6461.  
  6462.           Parameters:
  6463.              "partial-windowname" =
  6464.                        either an initial portion of, or an entire window name.
  6465.                        The most-recently used window whose title matches the
  6466.                        name will be shown.
  6467.              "new-name" =the new name of the window.
  6468.  
  6469.           Returns:
  6470.              (integer) @TRUE if a window was found to rename;
  6471.                        @FALSE if no windows were found.
  6472.  
  6473.           Use this command to change a window's title.
  6474.  
  6475.           A partial-windowname of "" refers to the current Command Post
  6476.           window.
  6477.           Note:  Some applications may rely upon their window's title staying
  6478.           the same!  It should be used with caution and adequate testing.
  6479.  
  6480.  
  6481.           Example:
  6482.           &Windows (special)
  6483.            Make &Uppercase
  6484.              HTab = Num2Char(9)
  6485.              AllWinds = WinItemize()
  6486.              MyWin=ItemSelect("Uppercase Windows", AllWinds, HTab)
  6487.              WinTitle(MyWin, StrUpper(MyWin))
  6488.              Drop (HTab, AllWinds, MyWin)
  6489.  
  6490.  
  6491.           See Also:
  6492.              WinItemize
  6493.  
  6494.  
  6495.  
  6496.  
  6497.  
  6498.  
  6499.  
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.  
  6506.                                                                            137
  6507.  
  6508.                                                      CPML  FUNCTION  REFERENCE
  6509.  
  6510.  
  6511.  
  6512.           WinVersion
  6513.           Provides the version number of the current Windows system.
  6514.  
  6515.           Syntax:
  6516.              WinVersion (level)
  6517.  
  6518.           Parameters:
  6519.              "level" = either @MAJOR or @MINOR.
  6520.  
  6521.           Returns:
  6522.              (integer) either major or minor part of the Windows version
  6523.                        number.
  6524.  
  6525.           Use this command to determine which version of Windows is currently
  6526.           running.
  6527.  
  6528.           @MAJOR returns the integer part of the Windows version number; i.e.
  6529.           1.0, 2.11, 3.0, etc.
  6530.           @MINOR returns the decimal part of the Windows version number; i.e.
  6531.           1.0, 2.11, 3.0, etc.
  6532.  
  6533.  
  6534.           Example:
  6535.           &Info
  6536.            Windows &Version
  6537.              MinorVer=WinVersion(@MINOR)
  6538.              MajorVer=WinVersion(@MAJOR)
  6539.              Message("Windows Version",strcat(MajorVer,".",MinorVer))
  6540.  
  6541.  
  6542.           See Also:
  6543.              Version
  6544.  
  6545.  
  6546.  
  6547.  
  6548.  
  6549.  
  6550.  
  6551.  
  6552.  
  6553.  
  6554.  
  6555.  
  6556.  
  6557.  
  6558.  
  6559.  
  6560.  
  6561.  
  6562.                                                                            138
  6563.  
  6564.                                                      CPML  FUNCTION  REFERENCE
  6565.  
  6566.  
  6567.  
  6568.           WinWaitClose
  6569.           Suspends the menu execution until a specified window has been
  6570.           closed.
  6571.  
  6572.           Syntax:
  6573.              WinWaitClose (partial-windowname)
  6574.  
  6575.           Parameters:
  6576.              "partial-windowname" =
  6577.                        either an initial portion of, or an entire window name.
  6578.                        WinWaitClose suspends execution until all matching
  6579.                        windows have been closed.
  6580.  
  6581.           Returns:
  6582.              (integer) @TRUE if at least one window was found to wait for;
  6583.                        @FALSE if no windows were found.
  6584.  
  6585.           Use this command to suspend the menu item's execution until the
  6586.           user has finished using a given window and has manually closed it.
  6587.  
  6588.  
  6589.           Example:
  6590.              ;WinWaitClose command example
  6591.              run("clock.exe","")
  6592.              Display(4,"Note","Close Clock to continue")
  6593.              WinWaitClose("Clock")
  6594.              Message("Continuing...","Clock closed")
  6595.  
  6596.  
  6597.           See Also:
  6598.              Delay, Yield
  6599.  
  6600.  
  6601.  
  6602.  
  6603.  
  6604.  
  6605.  
  6606.  
  6607.  
  6608.  
  6609.  
  6610.  
  6611.  
  6612.  
  6613.  
  6614.  
  6615.  
  6616.  
  6617.  
  6618.                                                                            139
  6619.  
  6620.                                                      CPML  FUNCTION  REFERENCE
  6621.  
  6622.  
  6623.  
  6624.           WinZoom
  6625.           Maximizes a window to full-screen.
  6626.  
  6627.           Syntax:
  6628.              WinZoom (partial-windowname)
  6629.  
  6630.           Parameters:
  6631.              "partial-windowname" =
  6632.                        either an initial portion of, or an entire window name.
  6633.                        The most-recently used window whose title matches the
  6634.                        name will be shown.
  6635.  
  6636.           Returns:
  6637.              (integer) @TRUE if a window was found to zoom;
  6638.                        @FALSE if no windows were found.
  6639.  
  6640.           Use this command to "zoom" windows to full screen size.
  6641.  
  6642.           A partial-windowname of "" zooms the current Command Post window.
  6643.  
  6644.           Errors:
  6645.              1042 "WinZoom: Window not found"
  6646.  
  6647.           Example:
  6648.              Run("notepad.exe","")
  6649.              WinZoom("Notepad")
  6650.              WinShow("Notepad")
  6651.  
  6652.  
  6653.           See Also:
  6654.              WinHide, WinIconize, WinPlace, WinShow
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.  
  6670.  
  6671.  
  6672.  
  6673.  
  6674.                                                                            140
  6675.  
  6676.                                                      CPML  FUNCTION  REFERENCE
  6677.  
  6678.  
  6679.  
  6680.           Yield
  6681.           Provides time for other windows to do processing.
  6682.  
  6683.           Syntax:
  6684.              Yield
  6685.  
  6686.           Returns:
  6687.              nothing.
  6688.  
  6689.           Use this command to give other running windows time to process.
  6690.           This command will allow each open window to process 20 or more
  6691.           messages.
  6692.  
  6693.  
  6694.           Example:
  6695.              ;run PageMaker and give it some time to start up...
  6696.              PMFile = AskLine ("PageMaker", "File to run:", "")
  6697.              run("PM.EXE", PMFile)
  6698.              yield
  6699.              yield
  6700.              yield
  6701.  
  6702.  
  6703.           See Also:
  6704.              Delay
  6705.  
  6706.  
  6707.  
  6708.  
  6709.  
  6710.  
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.  
  6717.  
  6718.  
  6719.  
  6720.  
  6721.  
  6722.  
  6723.  
  6724.  
  6725.  
  6726.  
  6727.  
  6728.  
  6729.  
  6730.                                                                            141
  6731.