home *** CD-ROM | disk | FTP | other *** search
/ Lion Share / lionsharecd.iso / utils_mz / xdosman.zip / CHAPT7.DOC < prev    next >
Text File  |  1991-11-28  |  43KB  |  1,465 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                    Chapter 7.
  9.  
  10.                             The X-DOS Batch Language
  11.  
  12.      Introduction
  13.  
  14.           In addition to the internal and external commands detailed in
  15.           Chapter 6., X-DOS offers a complete batch language. The batch
  16.           language commands can be entered in batch files to allow you to
  17.           write simple programs to carry out repetitive tasks. You can
  18.           create a batch file containing batch commands in ED, the editor
  19.           included with X-DOS and then run this batch file from the command
  20.           line.
  21.  
  22.           Files created in this way are called batch files because they
  23.           contain a batch of commands, and all such files must have an
  24.           extension of .BAT. Each line of a batch file is treated as a
  25.           separate command just as if it had been typed in at the command
  26.           line. The AUTOEXEC.BAT file is an example of a batch file, though
  27.           this is a special file in that X-DOS will always look for this
  28.           file each time you boot up your system.
  29.  
  30.           The commands detailed in this chapter are only for use in batch
  31.           files and cannot be run directly from the command line. Please
  32.           note, however, that the internal and external commands can also
  33.           be entered in batch files.
  34.           With a little practice you will soon be writing batch files to
  35.           prompt for user input, display information on the screen, make
  36.           conditional decisions, call other batch files and much more.
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                       7-1
  63.  
  64.  
  65.  
  66.  
  67.      The @ Batch Command
  68.  
  69.           Purpose:    This batch command suppresses echoing to the screen
  70.                       of any command it precedes. The output from a command
  71.                       preceded by the @ sign is still displayed on the
  72.                       screen.
  73.  
  74.           Type:       Internal to COMMAND.COM
  75.  
  76.           Syntax:     @[command] [parameters]
  77.  
  78.           Where:      command - is the name of the command you do not want
  79.                       to display on the screen.
  80.  
  81.                       parameters - are any parameters needed by the command
  82.                       you do not want to display on the screen.
  83.  
  84.           Remarks:    Since the ECHO OFF command turns off the display of
  85.                       all succeeding commands in a batch file, the most
  86.                       important use of the @ sign is to ensure that the
  87.                       ECHO OFF command itself does not show on the screen.
  88.                       The @ sign is also useful in situations where you
  89.                       want to display the commands that are executed in the
  90.                       batch file except for maybe one or two commands.
  91.  
  92.           Examples:   If you want to ensure that all commands in your batch
  93.                       file are not displayed on the screen, you normally
  94.                       want to place the ECHO OFF command as the first line
  95.                       of your batch file. To make sure that the ECHO OFF
  96.                       command itself is not displayed on the screen you can
  97.                       precede it with the @ sign, like this:
  98.  
  99.                                     @ECHO OFF
  100.  
  101.                       ECHO OFF is not displayed on the screen when you run
  102.                       the batch file.
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.                                       7-2
  124.  
  125.  
  126.  
  127.  
  128.      The ANSWER Batch Command
  129.  
  130.           Purpose:    This batch command prompts you for keyboard input.
  131.                       Your input is stored in an environment variable named
  132.                       ANSWER which can later be used by a named
  133.                       substitution variable from within a batch file or
  134.                       from any program.
  135.  
  136.           Type:       Internal to COMMAND.COM
  137.  
  138.           Syntax:     ANSWER [prompt]
  139.  
  140.           Where:      prompt - is an optional text string which ANSWER will
  141.                       display on the screen while waiting for input from
  142.                       the user.
  143.  
  144.           Remarks:    The input you type when ANSWER prompts you is changed
  145.                       to upper-case before it is assigned to the ANSWER
  146.                       variable in the environment. You can therefore not
  147.                       make case dependent tests on ANSWER input.
  148.  
  149.                       If the optional prompt is not specified, ANSWER will
  150.                       not display anything on the screen that will inform
  151.                       the user that input is expected. Use the ECHO or
  152.                       REVECHO commands prior to the ANSWER command or use
  153.                       the optional prompt with ANSWER to make the user
  154.                       aware that keyboard input is expected.
  155.  
  156.                       ANSWER returns an error code which can be examined by
  157.                       the ERRORLEVEL option of the IF command. The
  158.                       errorlevel will be set to 0 if the ANSWER variable is
  159.                       successfully stored in the environment. If there is
  160.                       insufficient room in the environment to store the
  161.                       ANSWER variable or if the environment area is
  162.                       corrupted, ANSWER returns an error code of 1.
  163.  
  164.                       You should not use the >, < or | characters in the
  165.                       ANSWER prompt since they would be interpreted as
  166.                       redirection symbols.
  167.  
  168.           Examples:   In the following example we assume that you have
  169.                       created a batch file in which you want to prompt the
  170.                       user for a password before continuing execution of
  171.                       the batch file. To do this you should include the
  172.                       following line in your batch file:
  173.  
  174.                           ANSWER Enter Your password :
  175.  
  176.                       If the user types "SECRET" as his password, the
  177.                       ANSWER variable is set equal to SECRET in the
  178.                       environment. To verify this try to make a batch file
  179.                       which only contains the above line and execute it.
  180.  
  181.  
  182.  
  183.  
  184.                                       7-3
  185.  
  186.  
  187.  
  188.  
  189.  
  190.                       Then type the password SECRET. When the batch file is
  191.                       finished executing you can execute the SET command,
  192.                       like this:
  193.  
  194.                                       SET
  195.  
  196.                       You will see a listing of all current environment
  197.                       variables. Among them you should see one saying:
  198.  
  199.                                  ANSWER=SECRET
  200.  
  201.                       You can then later use a named environment variable
  202.                       to use or check the setting of the ANSWER environment
  203.                       variable. A real batch file in which ANSWER is used
  204.                       could look similar to this:
  205.  
  206.                         ANSWER Please enter your name :
  207.  
  208.                             IF %ANSWER%&==& GOTO TOP
  209.  
  210.                     ECHO Hello %ANSWER%, how are you today?
  211.  
  212.                       You may be wondering about the purpose of the fourth
  213.                       line of the batch file, IF %ANSWER%&==& GOTO TOP. It
  214.                       simply checks to see that you have entered any text.
  215.                       If the ANSWER environment variable is empty, which is
  216.                       the case if you only press [Enter], the line will be
  217.                       interpreted by X-DOS like this:
  218.  
  219.                                 IF &==& GOTO TOP
  220.  
  221.                       The & character is only used to ensure that both
  222.                       sides of the == signs contain information. You do not
  223.                       have to use the & character.You can actually use any
  224.                       character just as long as it is the same character on
  225.                       both sides of the == signs. If the above IF test is
  226.                       TRUE (&==&) then you know that the ANSWER environment
  227.                       variable is empty and you can take a proper action.
  228.                       In the above example we simply go back and prompt the
  229.                       user to enter his or her name again.
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.                                       7-4
  246.  
  247.  
  248.  
  249.  
  250.      The BEEP Batch Command
  251.  
  252.           Purpose:    This batch command produces a beep on the computer's
  253.                       speaker which can be used to get the user's attention
  254.                       during batch file execution.
  255.  
  256.           Type:       Internal to COMMAND.COM
  257.  
  258.           Syntax:     BEEP
  259.  
  260.           Remarks:    This batch command is useful in situations where you
  261.                       want to make the user aware that input is needed or
  262.                       an error has occurred.
  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.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.                                       7-5
  307.  
  308.  
  309.  
  310.  
  311.      The CALL Batch Command
  312.  
  313.           Purpose:    This batch command allows one batch file to call
  314.                       another batch file, execute this batch file, and then
  315.                       return to the calling batch file and resume execution
  316.                       right after the CALL command.
  317.  
  318.           Type:       Internal to COMMAND.COM
  319.  
  320.           Syntax:     CALL [d:][path]filename
  321.  
  322.           Where:      d:path - is the drive and path to the batch file you
  323.                       want to call.
  324.  
  325.                       filename - is the name of the batch file you want to
  326.                       call.
  327.  
  328.           Remarks:    The CALL command gives you great flexibility in
  329.                       setting up modular batch files. This is especially
  330.                       useful if you are making batch files which will be
  331.                       executed by different users.
  332.  
  333.                       If you do not specify a command from which X-DOS
  334.                       should continue executing after it returns to the
  335.                       calling batch file, X-DOS automatically starts
  336.                       execution from the command following the CALL
  337.                       command. You can have up to 10 nested CALL commands.
  338.                       This, in other words, means that you can have one
  339.                       batch file call another batch file which calls
  340.                       another batch file, which calls another batch file,
  341.                       up to 10 nested calls. You can also make recursive
  342.                       calls which means that a batch file calls itself.
  343.                       Just remember to ensure that you do not set the batch
  344.                       file up to run in an endless loop, which can easily
  345.                       happen if you do not insert some kind of termination
  346.                       condition.
  347.  
  348.           Examples:   We assume that you insert the command:
  349.  
  350.                              CALL C:\BATCH\JOHN.BAT
  351.  
  352.                       in a batch file. When you execute the batch file, and
  353.                       X-DOS reaches the CALL command, it will abort the
  354.                       execution of the current batch file and hand over
  355.                       control to the JOHN.BAT batch file in the C:\BATCH
  356.                       directory. When this batch file terminates, X-DOS
  357.                       will return to the calling batch file and continue
  358.                       execution right after the CALL C:\BATCH\JOHN.BAT
  359.                       command.
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.                                       7-6
  368.  
  369.  
  370.  
  371.  
  372.      The CHECK Batch Command
  373.  
  374.           Purpose:    This batch command enhances the batch language by
  375.                       reporting a variety of parameters that can range from
  376.                       disk information to time and date functions. Any
  377.                       results that the CHECK command returns can be
  378.                       evaluated with the ERRORLEVEL batch sub-command.
  379.  
  380.           Type:       Internal to COMMAND.COM
  381.  
  382.           Syntax:     CHECK keyword [parameters]
  383.  
  384.           Where:      keyword - is one of the keywords which are recognized
  385.                       by the CHECK command. Each of these keywords are
  386.                       described below.
  387.  
  388.                       parameters - are any parameters which may be required
  389.                       by the specified keyword.
  390.  
  391.           Remarks:    CHECK should come in very handy in automating many of
  392.                       the mundane tasks you perform. As an example, maybe
  393.                       you go through and delete all of your *.BAK files the
  394.                       beginning of every month. You can identify the months
  395.                       changing by including the CHECK day command in your
  396.                       batch file. If the day is equal to one (1), it is a
  397.                       good indication that the month has changed. You can
  398.                       then branch to your sub-routine for deleting the
  399.                       *.BAK files.
  400.  
  401.           Disk Related Keywords
  402.           DISKSPACE returns the amount of free disk space on the specified
  403.           drive, or on the default drive in terms of whole 16K byte blocks.
  404.           If there is 120K of free disk space, DISKSPACE returns the value
  405.           of 8, which can be used with ERRORLEVEL to indicate 8 blocks are
  406.           free.
  407.  
  408.           FILESIZE reports the length of a given file in kilobytes. A value
  409.           of 255 means that the file length is 255K or greater in
  410.           size.FILEFOUND takes the place of other DOSs IF EXIST conditional
  411.           testing and returns a 0 if a file exists and a 1 if it does not
  412.           exist.
  413.  
  414.           FILETEXT searches for a text string inside a file. See the
  415.           example below:
  416.  
  417.                 CHECK filetext C:\DOS\NOTES.MSG `Things to do:'
  418.  
  419.           In the above example, NOTES.MSG is checked for on Drive C: in the
  420.           sub-directory \DOS and if present, the string Things to do: is
  421.           searched for. If the string is found, a 0 is returned; if not, or
  422.           if an error is encountered, such as the file is not on the
  423.           specified path, a 1 is returned. You must enclose the string to
  424.  
  425.  
  426.  
  427.  
  428.                                       7-7
  429.  
  430.  
  431.  
  432.  
  433.           be searched for in single quotes (`').
  434.  
  435.           Hardware Related Keywords
  436.           MEMORY - number of 16K memory blocks.
  437.  
  438.           VIDEOTYPE - Monochrome Display Adapter (MGA or Hercules). Color
  439.           Graphics Adapter (CGA). Enhanced Graphics Adapter (EGA or VGA).
  440.  
  441.           MATHCO - Math co-processor installed. Math co-processor not
  442.           installed.
  443.  
  444.           These options check the hardware configuration. You may have a
  445.           program that you keep in two different versions, (i.e. 43 line
  446.           format for EGA, and 25 line format for monochrome) and you wish
  447.           to know what video card is installed so that you can call the
  448.           appropriate configuration. Or, you may have a program installed
  449.           for both, with co-processor and without co-processor.
  450.           CHECK will identify these things for you and report to your batch
  451.           file what it has found.
  452.  
  453.           Miscellaneous Keywords
  454.           TIME - returns the current time.
  455.  
  456.           DAY - returns the current day.
  457.  
  458.           MONTH - returns the current month.
  459.  
  460.           KEYPRESS  - returns the ASCII code of any key pressed.
  461.           Using those keys that produce an extended code like the function
  462.           keys and the arrow keys will set the ERRORLEVEL. These keys in
  463.           conjunction with X-DOS's KEYIN command, listed elsewhere in this
  464.           section, enhance the ability of the batch language to interact
  465.           with the user.
  466.  
  467.           Examples:   Here are some examples of the options of CHECK, in
  468.                       everyday use. The following batch file will delete
  469.                       all .BAK files if free disk space is less than 64K.
  470.  
  471.                CHECK DISKSPACE A:IF NOT ERRORLEVEL 4 DEL A:*.BAK
  472.  
  473.                       This batch file will delete a file if it exceeds 16K
  474.                       in size.
  475.  
  476.                    CHECK FILESIZE %1 IF ERRORLEVEL 17 DEL %1
  477.  
  478.                       This batch file decides whether to delete a file on
  479.                       the default drive, based on whether it is present on
  480.                       another specified drive.
  481.  
  482.         CHECK FILEFOUND B:EXAMPLE.FLE IF ERRORLEVEL 1 DEL C:EXAMPLE.FLE
  483.  
  484.                       The following batch file chooses which configuration
  485.  
  486.  
  487.  
  488.  
  489.                                       7-8
  490.  
  491.  
  492.  
  493.  
  494.                       of an installed program to use, based on the video
  495.                       card that is installed.
  496.  
  497.             CHECK VIDEOTYPE IF ERRORLEVEL 1 GOTO COLORVIDEOWS1GOTO
  498.  
  499.                              END:COLORVIDEOWS2:END
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.                                       7-9
  551.  
  552.  
  553.  
  554.  
  555.      The DELAY Batch Command
  556.  
  557.           Purpose:    This batch command lets you delay batch file
  558.                       processing for a specified amount of time.
  559.  
  560.           Type:       Internal to COMMAND.COM
  561.  
  562.           Syntax:     DELAY xx
  563.  
  564.           Where:      xx - are the number of seconds to delay batch file
  565.                       processing.
  566.  
  567.           Remarks:    The DELAY command is handy when you want to display
  568.                       important messages that the user should read before
  569.                       the batch file automatically continues execution.
  570.  
  571.           Examples:   If you want to display the message:
  572.  
  573.                       Remember to turn off your computer!
  574.  
  575.                       and then delay batch file execution for 3 seconds to
  576.                       allow the user enough time to read the message,
  577.                       include the following two lines in a batch file:
  578.  
  579.                 ECHO Remember to turn off you computer! DELAY 3
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.                                       7-10
  612.  
  613.  
  614.  
  615.  
  616.      The ECHO Batch Command
  617.  
  618.           Purpose:    This batch command is used to display a message on
  619.                       the screen or to suppress output to the screen.
  620.  
  621.           Type:       Internal to COMMAND.COM
  622.  
  623.           Syntax:     ECHO [ON | OFF]
  624.                       or
  625.                       ECHO [message]
  626.  
  627.           Where:      ON - turns ON the display of the commands in a batch
  628.                       file so that they are displayed on the screen as they
  629.                       are being executed. ECHO ON is the default setting.
  630.  
  631.                       OFF - turns OFF the display of the commands in a
  632.                       batch file. This way only the output from the
  633.                       commands that X-DOS executes in the batch file is
  634.                       displayed.
  635.  
  636.                       message - displays a message on the screen. This
  637.                       message can be up to 127 characters long.
  638.  
  639.           Remarks:    The default setting of ECHO ON is very practical when
  640.                       you are developing a batch file and want to be able
  641.                       to see which commands are being executed from the
  642.                       batch file for debugging purposes. Once a batch file
  643.                       is running flawlessly, there is no longer any reason
  644.                       to display the commands that are executed from the
  645.                       batch file. To suppress the display of the commands,
  646.                       turn the ECHO mode OFF at the beginning of the batch
  647.                       file.
  648.  
  649.                       When the ECHO mode is turned OFF, you can use the
  650.                       ECHO command to display a message on the screen. The
  651.                       REVECHO command also displays a message on the screen
  652.                       in a similar manner, but in reverse video. If you
  653.                       expect the user to type in an answer to your message
  654.                       you should use the ANSWER command to display the
  655.                       message.
  656.  
  657.                       If you execute ECHO without any parameters, it will
  658.                       display the current setting of the ECHO mode, which
  659.                       is either ON or OFF. If you have turned ECHO mode ON,
  660.                       you can disable echoing of individual commands by
  661.                       putting the `@' symbol in front of the command.
  662.  
  663.           Examples:   If you want to suppress the display of the commands
  664.                       that are executed in a batch file, you need to turn
  665.                       the ECHO mode OFF. To do that you will need to the
  666.                       following ECHO command at the top of the batch file:
  667.  
  668.  
  669.  
  670.  
  671.  
  672.                                       7-11
  673.  
  674.  
  675.  
  676.  
  677.                                     ECHO OFF
  678.  
  679.                       You can view the status of the current ECHO mode by
  680.                       typing:
  681.  
  682.                                       ECHO
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.                                       7-12
  734.  
  735.  
  736.  
  737.  
  738.      The FOR Batch Command
  739.  
  740.           Purpose:    This batch command is used in combination with the IN
  741.                       and DO batch sub-commands to repeat execution of a X-
  742.                       DOS command or another program.
  743.  
  744.           Type:       Internal to COMMAND.COM
  745.  
  746.           Syntax:     FOR %%V IN (params) DO command %%V
  747.  
  748.           Where:      V - is a one-character substitution variable which
  749.                       can be other characters than the character 'V' used
  750.                       here. This variable cannot be a digit (0 to 9) in
  751.                       order to avoid confusion with the other substitution
  752.                       variables that can be used in the params section of
  753.                       the FOR command.
  754.  
  755.                       params - is a list of parameters which in turn are
  756.                       passed to the %%V substitution variable. These
  757.                       parameters can be any mixture of text strings,
  758.                       substitution variables, and named substitution
  759.                       variables.
  760.  
  761.                       command - is the name of the command you want to
  762.                       execute including any necessary parameters that the
  763.                       command needs.
  764.  
  765.           Remarks:    When the FOR command executes it will take each
  766.                       filespec in params and set it in place of the %%V
  767.                       substitution variable. If a filespec includes any
  768.                       wildcards, each filename matching the filespec
  769.                       replaces the %%V variable one by one.
  770.  
  771.                       You will notice that the substitution variable %%V
  772.                       has two percentage signs (%%) in front of it instead
  773.                       only one percentage sign (%). The reason for this is
  774.                       that you want X-DOS to assign values to the
  775.                       substitution variables of filespecs the first time
  776.                       around and then assign the values of the substitution
  777.                       variables of filespecs to the %%V substitution
  778.                       variable the second time around. Each time X-DOS
  779.                       assigns values to substitution variables it removes
  780.                       one percentage sign.
  781.  
  782.           Examples:   If you want to create a batch file that can delete
  783.                       multiple filespecs by issuing only one command, you
  784.                       can include a FOR command like this:
  785.                       FOR %%M IN (%1 %2 %3 %4) DO DEL %%M
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.                                       7-13
  795.  
  796.  
  797.  
  798.  
  799.      The GOTO Batch Command
  800.  
  801.           Purpose:    This batch command continues to execute the batch
  802.                       file a different place as specified by a label name.
  803.  
  804.           Type:       Internal to COMMAND.COM
  805.  
  806.           Syntax:     GOTO [:]labelname
  807.  
  808.           Where:      labelname - is a reference to a label some place in
  809.                       the batch file. You must specify a colon (:) in front
  810.                       of a label name in a batch file.
  811.  
  812.           Remarks:    The GOTO command instructs X-DOS to jump to a
  813.                       specific place in a batch file which has the
  814.                       specified label name assigned to it. A label is any
  815.                       combination of up to eight alphanumeric characters
  816.                       and must always be preceded by a colon (:).
  817.                       References to labels do not need to be preceded by a
  818.                       colon (:).
  819.  
  820.                       The GOTO command is normally used in combination with
  821.                       the ERRORLEVEL command to branch to another place in
  822.                       the batch file if a condition is true or not true.
  823.  
  824.           Examples:   The following example batch file shows how you can
  825.                       use the GOTO command:
  826.                  :STARTIF ERRORLEVEL 5 GOTO EXITECHO HELLOEXIT:
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.                                       7-14
  856.  
  857.  
  858.  
  859.  
  860.      The IF Batch Command
  861.  
  862.           Purpose:    This batch command is used with the EXIST,
  863.                       ERRORLEVEL, and NOT sub-commands to execute or skip
  864.                       execution of a command based on a conditional
  865.                       decision.
  866.  
  867.           Type:       Internal to COMMAND.COM
  868.  
  869.           Syntax:     IF [NOT] condition command
  870.  
  871.           Where:      NOT - means that the command will be executed if the
  872.                       condition is FALSE.
  873.  
  874.                       condition - is one of three possible expressions:
  875.  
  876.                       ERRORLEVEL number - makes the condition TRUE if the
  877.                       program previously executed by COMMAND.COM returned
  878.                       an exit code equal to , or greater than, number.
  879.  
  880.                       string1==string2 - makes the condition TRUE if
  881.                       string1 equals string2 after a substitution of
  882.                       substitution variables have occurred. For this
  883.                       condition to make any sense, one or both of the text
  884.                       strings have to be a substitution variable.
  885.  
  886.                       EXIST [d:][path]filespec - makes the condition TRUE
  887.                       if a file or range of files exist. You can specify an
  888.                       optional drive and path to where you want IF to check
  889.                       for the file(s).
  890.  
  891.                       command - is any X-DOS command or other program which
  892.                       will be executed if the condition is TRUE, or, if the
  893.                       NOT parameter is specified, is FALSE.
  894.  
  895.           Remarks:    Any of the three conditions may be preceded by the
  896.                       NOT command to indicate that the following command
  897.                       should be executed only if the condition is not True.
  898.  
  899.                       Special care must be taken when comparing two strings
  900.                       of the form string1==string2 of which one or both of
  901.                       the strings are named substitution variables. You
  902.                       must ensure that variables, referenced by string1
  903.                       and/or string2, have been set up in the environment.
  904.                       Otherwise, substitution variables without a reference
  905.                       in the environment are literally going to be
  906.                       substituted with nothing. Look at the following
  907.                       example:
  908.  
  909.               IF NOT %TEST%==BAD ECHO Test completed successfully.
  910.  
  911.                       If an environment variable named TEST is set to any
  912.  
  913.  
  914.  
  915.  
  916.                                       7-15
  917.  
  918.  
  919.  
  920.  
  921.                       value, the batch file is going to perform as
  922.                       expected. The ECHO statement is going to be executed
  923.                       in all instances except when TEST is set to `BAD'.
  924.                       But, if no variable named TEST is found in the
  925.                       environment, X-DOS interprets the above command this
  926.                       way:
  927.               IF NOT %TEST%==BAD ECHO Test completed successfully.
  928.  
  929.                       Since on TEST variable was found in the environment,
  930.                       X-DOS substituted %TEST% with absolutely nothing.
  931.                       When the test is performed, string1 is missing and
  932.                       you will receive a syntax error. You can avoid this
  933.                       situation by testing for the existence of the TEST
  934.                       variable in the environment. A way of doing this is
  935.                       to make a test similar to this:
  936.  
  937.                            IF %TEST%&==& GOTO NO_VAR
  938.  
  939.                       By including the '&' character on both sides of the
  940.                       '==' signs, you ensure that the left side at least
  941.                       will consist of the '&' character. If this test is
  942.                       true (&==&) then you know that the environment
  943.                       variable TEST is missing and you should make the
  944.                       batch file jump to a place where you give the proper
  945.                       error message.
  946.  
  947.           Examples:   If you want to create a batch file which you want to
  948.                       use in place of the DEL command to ensure that you do
  949.                       not accidentally delete files with an extension of
  950.                       .DOC by using the *.DOC filespec. This file, which we
  951.                       call NDEL.BAT, could look like this:
  952.  
  953.       IF %1== *.DOC GOTO WARNINGDEL %1 GOTO EXIT:WARNING ECHO You cannot
  954.  
  955.                   delete files with the *.DOC filespec!!!:EXIT
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.                                       7-16
  978.  
  979.  
  980.  
  981.  
  982.      The KEYIN Batch Command
  983.  
  984.           Purpose:    This batch command enables you to create interactive
  985.                       batch files which accept only a predefined set of
  986.                       keys. This command is especially useful when making
  987.                       batch file menu systems.
  988.  
  989.           Type:       Internal to COMMAND.COM
  990.  
  991.           Syntax:     KEYIN A [B C 1 (...)]
  992.  
  993.           Where:      A - is any one ASCII character that KEYIN will use
  994.                       accept before continuing execution of the batch file.
  995.  
  996.                       B C 1 - are additional ASCII characters that KEYIN
  997.                       will accept before continuing execution of the batch
  998.                       file.
  999.  
  1000.                       (...) - shows that KEYIN accepts several more ASCII
  1001.                       characters as parameters. You can specify as many
  1002.                       parameters as will fit on the command line and you do
  1003.                       not have to separate the parameters with spaces.
  1004.  
  1005.           Remarks:    The ASCII characters that you use as parameters for
  1006.                       the KEYIN command do not have to be separated by
  1007.                       spaces and each KEYIN parameter can only consist of
  1008.                       one character. KEYIN is not case sensitive and
  1009.                       therefore treats upper- and lower-case letters the
  1010.                       same.
  1011.  
  1012.                       The KEYIN command uses IF ERRORLEVEL testing to check
  1013.                       the input from the user and screen out illegal
  1014.                       entries, meaning any ASCII characters which are not
  1015.                       specified as KEYIN parameters. Any illegal entries
  1016.                       are automatically assigned the exit code 0 and can
  1017.                       therefore be dealt with equally by the author of the
  1018.                       batch file. The first KEYIN parameter is assigned the
  1019.                       exit code 1, the second KEYIN parameter is assigned
  1020.                       the exit code 2, and so forth.
  1021.  
  1022.                       Therefore, when you use IF ERRORLEVEL testing to
  1023.                       check the user's input, you must always put the IF
  1024.                       ERRORLEVEL testing with the highest exit code on top
  1025.                       of the IF ERRORLEVEL testing list since the
  1026.                       ERRORLEVEL command always check for exit codes equal
  1027.                       to or higher than the specified ERRORLEVEL number.
  1028.  
  1029.           Examples:   Suppose the following BATCH file :
  1030.                                      :START
  1031.  
  1032.                             ECHO 1. Word Processing
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.                                       7-17
  1039.  
  1040.  
  1041.  
  1042.  
  1043.                               ECHO 2. Spreadsheet
  1044.  
  1045.                                 ECHO 3. Database
  1046.  
  1047.                                   ECHO 4. Exit
  1048.  
  1049.                              ECHO INPUT YOUR CHOICE
  1050.  
  1051.                       KEYIN 1234IF ERRORLEVEL 4 GOTO EXIT
  1052.  
  1053.                            IF ERRORLEVEL 3 GOTO DATAB
  1054.  
  1055.                           IF ERRORLEVEL 2 GOTO SPREAD
  1056.  
  1057.                             IF ERRORLEVEL 1 GOTO WP
  1058.  
  1059.                                       : WP
  1060.  
  1061.                                       ....
  1062.  
  1063.                                     : SPREAD
  1064.  
  1065.                                       ....
  1066.  
  1067.                                     : DATAB
  1068.  
  1069.                                       ....
  1070.  
  1071.                                      : EXIT
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.                                       7-18
  1100.  
  1101.  
  1102.  
  1103.  
  1104.      The LOCATE Batch Command
  1105.  
  1106.           Purpose:    This batch command places the cursor at a specified
  1107.                       location on your screen to allow you to display text
  1108.                       anywhere on the screen.
  1109.  
  1110.           Type:       Internal to COMMAND.COM
  1111.  
  1112.           Syntax:     LOCATE [R][,C]
  1113.  
  1114.           Where:      R - is the screen row in decimal numbers. The upper-
  1115.                       left corner of the screen is row 0 and the screen has
  1116.                       25 or 43 rows.
  1117.  
  1118.                       C - is the screen column in decimal numbers. The
  1119.                       upper-left corner of the screen is column 0 and the
  1120.                       screen has 80 columns.
  1121.  
  1122.           Remarks:    You can use LOCATE with only the Row (R) parameter in
  1123.                       which case the column defaults to column 0. It is
  1124.                       also possible to use the LOCATE command with only the
  1125.                       Column (C) parameter. Just precede the column
  1126.                       parameter with a comma.
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.                                       7-19
  1161.  
  1162.  
  1163.  
  1164.  
  1165.      The LOOP Batch Command
  1166.  
  1167.           Purpose:    This batch command can be used to loop part of a
  1168.                       batch file a number of times.
  1169.  
  1170.           Type:       Internal to COMMAND.COM
  1171.  
  1172.           Syntax:     LOOP /IlabelnameLOOP..IF [NOT] ERRORLEVEL number GOTO
  1173.                       labelname
  1174.  
  1175.           Where:      I - sets the loop counter to 0. You should always
  1176.                       initialize the LOOP command before beginning the
  1177.                       actual looping to ensure that it starts counting from
  1178.                       0.
  1179.  
  1180.           Remarks:    The initial LOOP statement with the /I parameter
  1181.                       resets the counter for LOOP. You should always
  1182.                       initialize the LOOP command before beginning the
  1183.                       actual looping. The second LOOP statement actually
  1184.                       performs the loop until a condition is met according
  1185.                       to the ERRORLEVEL checking.
  1186.  
  1187.                       Every time the LOOP command is executed without any
  1188.                       parameters it increases the exit code by one. In your
  1189.                       IF ERRORLEVEL testing you just specify a value which
  1190.                       reflects the number of times you want the loop to be
  1191.                       executed.
  1192.  
  1193.           Please be aware that IF ERRORLEVEL testing does not support exit
  1194.           codes above 255, which then is the maximum number of loops you
  1195.           can perform with one LOOP command.
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.                                       7-20
  1222.  
  1223.  
  1224.  
  1225.  
  1226.      The PAUSE Batch Command
  1227.  
  1228.           Purpose:    This batch command stops batch file execution until
  1229.                       the user presses a key. You can optionally specify a
  1230.                       message which will be displayed on the screen when
  1231.                       the PAUSE command is executed.
  1232.  
  1233.           Type:       Internal to COMMAND.COM
  1234.  
  1235.           Syntax:     PAUSE [message]
  1236.  
  1237.           Where:      message - is the message to be displayed while the
  1238.                       PAUSE command waits from input from the user.
  1239.  
  1240.           Remarks:    If no message is entered after PAUSE, the PAUSE
  1241.                       command will display the default message "Press any
  1242.                       key to continue". The user must then press any key at
  1243.                       this point to continue the execution of the batch
  1244.                       file. If you need the user to enter input which is
  1245.                       going to be used later in the batch file you should
  1246.                       use the ANSWER command instead of the PAUSE command.
  1247.  
  1248.           Examples:   If you want to display the message "You have now
  1249.                       completed the installation" on the screen from a
  1250.                       batch file, you can do so by including the following
  1251.                       PAUSE statement:
  1252.  
  1253.                  PAUSE You have now completed the installation
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.                                       7-21
  1283.  
  1284.  
  1285.  
  1286.  
  1287.      The REM Batch and Configuration Command
  1288.  
  1289.           Purpose:    Inserts comments or remarks in a batch file
  1290.  
  1291.           Type:       Internal to COMMAND.COM
  1292.  
  1293.           Syntax:     REM [text]
  1294.  
  1295.           Where:      text - is any string of character up to 127 bytes
  1296.                       long
  1297.  
  1298.           Remarks:    When X-DOS encounters a REM command in a batch file
  1299.                       it automatically skips the command and jumps to the
  1300.                       next line in the batch file.You can also use the
  1301.                       colon (:) to insert remarks in your batch file. The
  1302.                       colon is used in batch files to distinguish labels
  1303.                       which are just treated as normal text by X-DOS. Just
  1304.                       ensure that the first word of the remark is not the
  1305.                       name of a valid label that you are already using
  1306.                       elsewhere in the batch file.
  1307.  
  1308.           Examples:   You want to create a batch file which copies multiple
  1309.                       filespecs onto the diskette in the A: drive and you
  1310.                       want to include a remark at the top of the batch file
  1311.                       which explains the purpose of the batch file. Such a
  1312.                       remark could look like this:
  1313.  
  1314.      REM This batch file copies several filespecs onto a diskette in the A:
  1315.  
  1316.                                      drive
  1317.  
  1318.  
  1319.  
  1320.       REM You must specify the filespecs as parameters to this batch file.
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.                                       7-22
  1344.  
  1345.  
  1346.  
  1347.  
  1348.      The REVECHO Batch Command
  1349.  
  1350.           Purpose:    This command is used to display text on the screen in
  1351.                       reverse text.
  1352.  
  1353.           Type:       Internal to COMMAND.COM
  1354.  
  1355.           Syntax:     REVECHO [text]
  1356.  
  1357.           Where:      text - is any string of character up to 127 bytes
  1358.                       long
  1359.  
  1360.           Remarks:    The X-DOS ECHO command provides a simple way to
  1361.                       display messages from within batch files. REVECHO
  1362.                       works the same way, except that it displays the
  1363.                       message in reverse video.
  1364.  
  1365.                       By using REVECHO in combination with the LOCATE
  1366.                       command and the LOOP command, you can make a message
  1367.                       flash on the screen. Since REVECHO looks at the
  1368.                       existing color and reverses it each subsequent time
  1369.                       you execute it, the color will appear to flash if
  1370.                       executed many times in succession.
  1371.  
  1372.           Examples:   A batch file which would flash the message "Warning!"
  1373.                       in the middle of the screen could look similar to
  1374.                       this:
  1375.  
  1376.                                       CLS
  1377.  
  1378.                                     LOOP /I
  1379.  
  1380.                                    :FLASHMES
  1381.  
  1382.                                LOOP>LOCATE 12,35
  1383.  
  1384.                                 REVECHO Warning!
  1385.  
  1386.                       IF NOT ERRORLEVEL 100 GOTO FLASHMES
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.                                       7-23
  1405.  
  1406.  
  1407.  
  1408.  
  1409.      The SHIFT Batch Command
  1410.  
  1411.           Purpose:    The shift command makes it possible for you to use
  1412.                       more than the standard ten substitution variables, %0
  1413.                       to %9.
  1414.  
  1415.           Type:       Internal to COMMAND.COM
  1416.  
  1417.           Syntax:     SHIFT
  1418.  
  1419.           Remarks:    SHIFT will let you move the value of a substitution
  1420.                       variable down one step at a time (e.g., from %4 to %3
  1421.                       to %2 etc.). When you do this, you will lose the
  1422.                       value of the lowest substitution variable, %0. If you
  1423.                       need to retain a lower value, you can use the SET
  1424.                       command to store the value of the %0 substitution
  1425.                       variable in an environment variable before executing
  1426.                       the SHIFT command.
  1427.  
  1428.                       The SHIFT command can also be used even if you use
  1429.                       less than the maximum ten substitution variables.
  1430.  
  1431.           Examples:   To see how the SHIFT command works we have made a
  1432.                       simple batch file:
  1433.      REM Test of the SHIFT commandECHO %0 %1 %2SHIFTECHO %0 %1 %2SHIFTECHO
  1434.  
  1435.                                     %0 %1 %2
  1436.  
  1437.                       You will need to run this batch file with parameters
  1438.                       from the command line in order to see how it works.
  1439.                       We call this batch file TEST.BAT and execute it with
  1440.                       three parameters, number1, number2, and number3, like
  1441.                       this:
  1442.  
  1443.                           TEST number1 number2 number3
  1444.  
  1445.                       The output to your screen will look like this:
  1446.  
  1447.            TEST number1 number2number1 number2 number3number2 number3
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.                                       7-24