Black Box 4

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

/ Black Box 4 / BlackBox.cdr / dosutils / xdosman.arj / CHAPT7.DOC < prev next >

Wrap

Text File | 1991-11-28 | 41.9 KB | 1,465 lines

Chapter 7. The X-DOS Batch Language Introduction In addition to the internal and external commands detailed in Chapter 6., X-DOS offers a complete batch language. The batch language commands can be entered in batch files to allow you to write simple programs to carry out repetitive tasks. You can create a batch file containing batch commands in ED, the editor included with X-DOS and then run this batch file from the command line. Files created in this way are called batch files because they contain a batch of commands, and all such files must have an extension of .BAT. Each line of a batch file is treated as a separate command just as if it had been typed in at the command line. The AUTOEXEC.BAT file is an example of a batch file, though this is a special file in that X-DOS will always look for this file each time you boot up your system. The commands detailed in this chapter are only for use in batch files and cannot be run directly from the command line. Please note, however, that the internal and external commands can also be entered in batch files. With a little practice you will soon be writing batch files to prompt for user input, display information on the screen, make conditional decisions, call other batch files and much more. 7-1 The @ Batch Command Purpose: This batch command suppresses echoing to the screen of any command it precedes. The output from a command preceded by the @ sign is still displayed on the screen. Type: Internal to COMMAND.COM Syntax: @[command] [parameters] Where: command - is the name of the command you do not want to display on the screen. parameters - are any parameters needed by the command you do not want to display on the screen. Remarks: Since the ECHO OFF command turns off the display of all succeeding commands in a batch file, the most important use of the @ sign is to ensure that the ECHO OFF command itself does not show on the screen. The @ sign is also useful in situations where you want to display the commands that are executed in the batch file except for maybe one or two commands. Examples: If you want to ensure that all commands in your batch file are not displayed on the screen, you normally want to place the ECHO OFF command as the first line of your batch file. To make sure that the ECHO OFF command itself is not displayed on the screen you can precede it with the @ sign, like this: @ECHO OFF ECHO OFF is not displayed on the screen when you run the batch file. 7-2 The ANSWER Batch Command Purpose: This batch command prompts you for keyboard input. Your input is stored in an environment variable named ANSWER which can later be used by a named substitution variable from within a batch file or from any program. Type: Internal to COMMAND.COM Syntax: ANSWER [prompt] Where: prompt - is an optional text string which ANSWER will display on the screen while waiting for input from the user. Remarks: The input you type when ANSWER prompts you is changed to upper-case before it is assigned to the ANSWER variable in the environment. You can therefore not make case dependent tests on ANSWER input. If the optional prompt is not specified, ANSWER will not display anything on the screen that will inform the user that input is expected. Use the ECHO or REVECHO commands prior to the ANSWER command or use the optional prompt with ANSWER to make the user aware that keyboard input is expected. ANSWER returns an error code which can be examined by the ERRORLEVEL option of the IF command. The errorlevel will be set to 0 if the ANSWER variable is successfully stored in the environment. If there is insufficient room in the environment to store the ANSWER variable or if the environment area is corrupted, ANSWER returns an error code of 1. You should not use the >, < or | characters in the ANSWER prompt since they would be interpreted as redirection symbols. Examples: In the following example we assume that you have created a batch file in which you want to prompt the user for a password before continuing execution of the batch file. To do this you should include the following line in your batch file: ANSWER Enter Your password : If the user types "SECRET" as his password, the ANSWER variable is set equal to SECRET in the environment. To verify this try to make a batch file which only contains the above line and execute it. 7-3 Then type the password SECRET. When the batch file is finished executing you can execute the SET command, like this: SET You will see a listing of all current environment variables. Among them you should see one saying: ANSWER=SECRET You can then later use a named environment variable to use or check the setting of the ANSWER environment variable. A real batch file in which ANSWER is used could look similar to this: ANSWER Please enter your name : IF %ANSWER%&==& GOTO TOP ECHO Hello %ANSWER%, how are you today? You may be wondering about the purpose of the fourth line of the batch file, IF %ANSWER%&==& GOTO TOP. It simply checks to see that you have entered any text. If the ANSWER environment variable is empty, which is the case if you only press [Enter], the line will be interpreted by X-DOS like this: IF &==& GOTO TOP The & character is only used to ensure that both sides of the == signs contain information. You do not have to use the & character.You can actually use any character just as long as it is the same character on both sides of the == signs. If the above IF test is TRUE (&==&) then you know that the ANSWER environment variable is empty and you can take a proper action. In the above example we simply go back and prompt the user to enter his or her name again. 7-4 The BEEP Batch Command Purpose: This batch command produces a beep on the computer's speaker which can be used to get the user's attention during batch file execution. Type: Internal to COMMAND.COM Syntax: BEEP Remarks: This batch command is useful in situations where you want to make the user aware that input is needed or an error has occurred. 7-5 The CALL Batch Command Purpose: This batch command allows one batch file to call another batch file, execute this batch file, and then return to the calling batch file and resume execution right after the CALL command. Type: Internal to COMMAND.COM Syntax: CALL [d:][path]filename Where: d:path - is the drive and path to the batch file you want to call. filename - is the name of the batch file you want to call. Remarks: The CALL command gives you great flexibility in setting up modular batch files. This is especially useful if you are making batch files which will be executed by different users. If you do not specify a command from which X-DOS should continue executing after it returns to the calling batch file, X-DOS automatically starts execution from the command following the CALL command. You can have up to 10 nested CALL commands. This, in other words, means that you can have one batch file call another batch file which calls another batch file, which calls another batch file, up to 10 nested calls. You can also make recursive calls which means that a batch file calls itself. Just remember to ensure that you do not set the batch file up to run in an endless loop, which can easily happen if you do not insert some kind of termination condition. Examples: We assume that you insert the command: CALL C:\BATCH\JOHN.BAT in a batch file. When you execute the batch file, and X-DOS reaches the CALL command, it will abort the execution of the current batch file and hand over control to the JOHN.BAT batch file in the C:\BATCH directory. When this batch file terminates, X-DOS will return to the calling batch file and continue execution right after the CALL C:\BATCH\JOHN.BAT command. 7-6 The CHECK Batch Command Purpose: This batch command enhances the batch language by reporting a variety of parameters that can range from disk information to time and date functions. Any results that the CHECK command returns can be evaluated with the ERRORLEVEL batch sub-command. Type: Internal to COMMAND.COM Syntax: CHECK keyword [parameters] Where: keyword - is one of the keywords which are recognized by the CHECK command. Each of these keywords are described below. parameters - are any parameters which may be required by the specified keyword. Remarks: CHECK should come in very handy in automating many of the mundane tasks you perform. As an example, maybe you go through and delete all of your *.BAK files the beginning of every month. You can identify the months changing by including the CHECK day command in your batch file. If the day is equal to one (1), it is a good indication that the month has changed. You can then branch to your sub-routine for deleting the *.BAK files. Disk Related Keywords DISKSPACE returns the amount of free disk space on the specified drive, or on the default drive in terms of whole 16K byte blocks. If there is 120K of free disk space, DISKSPACE returns the value of 8, which can be used with ERRORLEVEL to indicate 8 blocks are free. FILESIZE reports the length of a given file in kilobytes. A value of 255 means that the file length is 255K or greater in size.FILEFOUND takes the place of other DOSs IF EXIST conditional testing and returns a 0 if a file exists and a 1 if it does not exist. FILETEXT searches for a text string inside a file. See the example below: CHECK filetext C:\DOS\NOTES.MSG `Things to do:' In the above example, NOTES.MSG is checked for on Drive C: in the sub-directory \DOS and if present, the string Things to do: is searched for. If the string is found, a 0 is returned; if not, or if an error is encountered, such as the file is not on the specified path, a 1 is returned. You must enclose the string to 7-7 be searched for in single quotes (`'). Hardware Related Keywords MEMORY - number of 16K memory blocks. VIDEOTYPE - Monochrome Display Adapter (MGA or Hercules). Color Graphics Adapter (CGA). Enhanced Graphics Adapter (EGA or VGA). MATHCO - Math co-processor installed. Math co-processor not installed. These options check the hardware configuration. You may have a program that you keep in two different versions, (i.e. 43 line format for EGA, and 25 line format for monochrome) and you wish to know what video card is installed so that you can call the appropriate configuration. Or, you may have a program installed for both, with co-processor and without co-processor. CHECK will identify these things for you and report to your batch file what it has found. Miscellaneous Keywords TIME - returns the current time. DAY - returns the current day. MONTH - returns the current month. KEYPRESS - returns the ASCII code of any key pressed. Using those keys that produce an extended code like the function keys and the arrow keys will set the ERRORLEVEL. These keys in conjunction with X-DOS's KEYIN command, listed elsewhere in this section, enhance the ability of the batch language to interact with the user. Examples: Here are some examples of the options of CHECK, in everyday use. The following batch file will delete all .BAK files if free disk space is less than 64K. CHECK DISKSPACE A:IF NOT ERRORLEVEL 4 DEL A:*.BAK This batch file will delete a file if it exceeds 16K in size. CHECK FILESIZE %1 IF ERRORLEVEL 17 DEL %1 This batch file decides whether to delete a file on the default drive, based on whether it is present on another specified drive. CHECK FILEFOUND B:EXAMPLE.FLE IF ERRORLEVEL 1 DEL C:EXAMPLE.FLE The following batch file chooses which configuration 7-8 of an installed program to use, based on the video card that is installed. CHECK VIDEOTYPE IF ERRORLEVEL 1 GOTO COLORVIDEOWS1GOTO END:COLORVIDEOWS2:END 7-9 The DELAY Batch Command Purpose: This batch command lets you delay batch file processing for a specified amount of time. Type: Internal to COMMAND.COM Syntax: DELAY xx Where: xx - are the number of seconds to delay batch file processing. Remarks: The DELAY command is handy when you want to display important messages that the user should read before the batch file automatically continues execution. Examples: If you want to display the message: Remember to turn off your computer! and then delay batch file execution for 3 seconds to allow the user enough time to read the message, include the following two lines in a batch file: ECHO Remember to turn off you computer! DELAY 3 7-10 The ECHO Batch Command Purpose: This batch command is used to display a message on the screen or to suppress output to the screen. Type: Internal to COMMAND.COM Syntax: ECHO [ON | OFF] or ECHO [message] Where: ON - turns ON the display of the commands in a batch file so that they are displayed on the screen as they are being executed. ECHO ON is the default setting. OFF - turns OFF the display of the commands in a batch file. This way only the output from the commands that X-DOS executes in the batch file is displayed. message - displays a message on the screen. This message can be up to 127 characters long. Remarks: The default setting of ECHO ON is very practical when you are developing a batch file and want to be able to see which commands are being executed from the batch file for debugging purposes. Once a batch file is running flawlessly, there is no longer any reason to display the commands that are executed from the batch file. To suppress the display of the commands, turn the ECHO mode OFF at the beginning of the batch file. When the ECHO mode is turned OFF, you can use the ECHO command to display a message on the screen. The REVECHO command also displays a message on the screen in a similar manner, but in reverse video. If you expect the user to type in an answer to your message you should use the ANSWER command to display the message. If you execute ECHO without any parameters, it will display the current setting of the ECHO mode, which is either ON or OFF. If you have turned ECHO mode ON, you can disable echoing of individual commands by putting the `@' symbol in front of the command. Examples: If you want to suppress the display of the commands that are executed in a batch file, you need to turn the ECHO mode OFF. To do that you will need to the following ECHO command at the top of the batch file: 7-11 ECHO OFF You can view the status of the current ECHO mode by typing: ECHO 7-12 The FOR Batch Command Purpose: This batch command is used in combination with the IN and DO batch sub-commands to repeat execution of a X- DOS command or another program. Type: Internal to COMMAND.COM Syntax: FOR %%V IN (params) DO command %%V Where: V - is a one-character substitution variable which can be other characters than the character 'V' used here. This variable cannot be a digit (0 to 9) in order to avoid confusion with the other substitution variables that can be used in the params section of the FOR command. params - is a list of parameters which in turn are passed to the %%V substitution variable. These parameters can be any mixture of text strings, substitution variables, and named substitution variables. command - is the name of the command you want to execute including any necessary parameters that the command needs. Remarks: When the FOR command executes it will take each filespec in params and set it in place of the %%V substitution variable. If a filespec includes any wildcards, each filename matching the filespec replaces the %%V variable one by one. You will notice that the substitution variable %%V has two percentage signs (%%) in front of it instead only one percentage sign (%). The reason for this is that you want X-DOS to assign values to the substitution variables of filespecs the first time around and then assign the values of the substitution variables of filespecs to the %%V substitution variable the second time around. Each time X-DOS assigns values to substitution variables it removes one percentage sign. Examples: If you want to create a batch file that can delete multiple filespecs by issuing only one command, you can include a FOR command like this: FOR %%M IN (%1 %2 %3 %4) DO DEL %%M 7-13 The GOTO Batch Command Purpose: This batch command continues to execute the batch file a different place as specified by a label name. Type: Internal to COMMAND.COM Syntax: GOTO [:]labelname Where: labelname - is a reference to a label some place in the batch file. You must specify a colon (:) in front of a label name in a batch file. Remarks: The GOTO command instructs X-DOS to jump to a specific place in a batch file which has the specified label name assigned to it. A label is any combination of up to eight alphanumeric characters and must always be preceded by a colon (:). References to labels do not need to be preceded by a colon (:). The GOTO command is normally used in combination with the ERRORLEVEL command to branch to another place in the batch file if a condition is true or not true. Examples: The following example batch file shows how you can use the GOTO command: :STARTIF ERRORLEVEL 5 GOTO EXITECHO HELLOEXIT: 7-14 The IF Batch Command Purpose: This batch command is used with the EXIST, ERRORLEVEL, and NOT sub-commands to execute or skip execution of a command based on a conditional decision. Type: Internal to COMMAND.COM Syntax: IF [NOT] condition command Where: NOT - means that the command will be executed if the condition is FALSE. condition - is one of three possible expressions: ERRORLEVEL number - makes the condition TRUE if the program previously executed by COMMAND.COM returned an exit code equal to , or greater than, number. string1==string2 - makes the condition TRUE if string1 equals string2 after a substitution of substitution variables have occurred. For this condition to make any sense, one or both of the text strings have to be a substitution variable. EXIST [d:][path]filespec - makes the condition TRUE if a file or range of files exist. You can specify an optional drive and path to where you want IF to check for the file(s). command - is any X-DOS command or other program which will be executed if the condition is TRUE, or, if the NOT parameter is specified, is FALSE. Remarks: Any of the three conditions may be preceded by the NOT command to indicate that the following command should be executed only if the condition is not True. Special care must be taken when comparing two strings of the form string1==string2 of which one or both of the strings are named substitution variables. You must ensure that variables, referenced by string1 and/or string2, have been set up in the environment. Otherwise, substitution variables without a reference in the environment are literally going to be substituted with nothing. Look at the following example: IF NOT %TEST%==BAD ECHO Test completed successfully. If an environment variable named TEST is set to any 7-15 value, the batch file is going to perform as expected. The ECHO statement is going to be executed in all instances except when TEST is set to `BAD'. But, if no variable named TEST is found in the environment, X-DOS interprets the above command this way: IF NOT %TEST%==BAD ECHO Test completed successfully. Since on TEST variable was found in the environment, X-DOS substituted %TEST% with absolutely nothing. When the test is performed, string1 is missing and you will receive a syntax error. You can avoid this situation by testing for the existence of the TEST variable in the environment. A way of doing this is to make a test similar to this: IF %TEST%&==& GOTO NO_VAR By including the '&' character on both sides of the '==' signs, you ensure that the left side at least will consist of the '&' character. If this test is true (&==&) then you know that the environment variable TEST is missing and you should make the batch file jump to a place where you give the proper error message. Examples: If you want to create a batch file which you want to use in place of the DEL command to ensure that you do not accidentally delete files with an extension of .DOC by using the *.DOC filespec. This file, which we call NDEL.BAT, could look like this: IF %1== *.DOC GOTO WARNINGDEL %1 GOTO EXIT:WARNING ECHO You cannot delete files with the *.DOC filespec!!!:EXIT 7-16 The KEYIN Batch Command Purpose: This batch command enables you to create interactive batch files which accept only a predefined set of keys. This command is especially useful when making batch file menu systems. Type: Internal to COMMAND.COM Syntax: KEYIN A [B C 1 (...)] Where: A - is any one ASCII character that KEYIN will use accept before continuing execution of the batch file. B C 1 - are additional ASCII characters that KEYIN will accept before continuing execution of the batch file. (...) - shows that KEYIN accepts several more ASCII characters as parameters. You can specify as many parameters as will fit on the command line and you do not have to separate the parameters with spaces. Remarks: The ASCII characters that you use as parameters for the KEYIN command do not have to be separated by spaces and each KEYIN parameter can only consist of one character. KEYIN is not case sensitive and therefore treats upper- and lower-case letters the same. The KEYIN command uses IF ERRORLEVEL testing to check the input from the user and screen out illegal entries, meaning any ASCII characters which are not specified as KEYIN parameters. Any illegal entries are automatically assigned the exit code 0 and can therefore be dealt with equally by the author of the batch file. The first KEYIN parameter is assigned the exit code 1, the second KEYIN parameter is assigned the exit code 2, and so forth. Therefore, when you use IF ERRORLEVEL testing to check the user's input, you must always put the IF ERRORLEVEL testing with the highest exit code on top of the IF ERRORLEVEL testing list since the ERRORLEVEL command always check for exit codes equal to or higher than the specified ERRORLEVEL number. Examples: Suppose the following BATCH file : :START ECHO 1. Word Processing 7-17 ECHO 2. Spreadsheet ECHO 3. Database ECHO 4. Exit ECHO INPUT YOUR CHOICE KEYIN 1234IF ERRORLEVEL 4 GOTO EXIT IF ERRORLEVEL 3 GOTO DATAB IF ERRORLEVEL 2 GOTO SPREAD IF ERRORLEVEL 1 GOTO WP : WP .... : SPREAD .... : DATAB .... : EXIT 7-18 The LOCATE Batch Command Purpose: This batch command places the cursor at a specified location on your screen to allow you to display text anywhere on the screen. Type: Internal to COMMAND.COM Syntax: LOCATE [R][,C] Where: R - is the screen row in decimal numbers. The upper- left corner of the screen is row 0 and the screen has 25 or 43 rows. C - is the screen column in decimal numbers. The upper-left corner of the screen is column 0 and the screen has 80 columns. Remarks: You can use LOCATE with only the Row (R) parameter in which case the column defaults to column 0. It is also possible to use the LOCATE command with only the Column (C) parameter. Just precede the column parameter with a comma. 7-19 The LOOP Batch Command Purpose: This batch command can be used to loop part of a batch file a number of times. Type: Internal to COMMAND.COM Syntax: LOOP /IlabelnameLOOP..IF [NOT] ERRORLEVEL number GOTO labelname Where: I - sets the loop counter to 0. You should always initialize the LOOP command before beginning the actual looping to ensure that it starts counting from 0. Remarks: The initial LOOP statement with the /I parameter resets the counter for LOOP. You should always initialize the LOOP command before beginning the actual looping. The second LOOP statement actually performs the loop until a condition is met according to the ERRORLEVEL checking. Every time the LOOP command is executed without any parameters it increases the exit code by one. In your IF ERRORLEVEL testing you just specify a value which reflects the number of times you want the loop to be executed. Please be aware that IF ERRORLEVEL testing does not support exit codes above 255, which then is the maximum number of loops you can perform with one LOOP command. 7-20 The PAUSE Batch Command Purpose: This batch command stops batch file execution until the user presses a key. You can optionally specify a message which will be displayed on the screen when the PAUSE command is executed. Type: Internal to COMMAND.COM Syntax: PAUSE [message] Where: message - is the message to be displayed while the PAUSE command waits from input from the user. Remarks: If no message is entered after PAUSE, the PAUSE command will display the default message "Press any key to continue". The user must then press any key at this point to continue the execution of the batch file. If you need the user to enter input which is going to be used later in the batch file you should use the ANSWER command instead of the PAUSE command. Examples: If you want to display the message "You have now completed the installation" on the screen from a batch file, you can do so by including the following PAUSE statement: PAUSE You have now completed the installation 7-21 The REM Batch and Configuration Command Purpose: Inserts comments or remarks in a batch file Type: Internal to COMMAND.COM Syntax: REM [text] Where: text - is any string of character up to 127 bytes long Remarks: When X-DOS encounters a REM command in a batch file it automatically skips the command and jumps to the next line in the batch file.You can also use the colon (:) to insert remarks in your batch file. The colon is used in batch files to distinguish labels which are just treated as normal text by X-DOS. Just ensure that the first word of the remark is not the name of a valid label that you are already using elsewhere in the batch file. Examples: You want to create a batch file which copies multiple filespecs onto the diskette in the A: drive and you want to include a remark at the top of the batch file which explains the purpose of the batch file. Such a remark could look like this: REM This batch file copies several filespecs onto a diskette in the A: drive REM You must specify the filespecs as parameters to this batch file. 7-22 The REVECHO Batch Command Purpose: This command is used to display text on the screen in reverse text. Type: Internal to COMMAND.COM Syntax: REVECHO [text] Where: text - is any string of character up to 127 bytes long Remarks: The X-DOS ECHO command provides a simple way to display messages from within batch files. REVECHO works the same way, except that it displays the message in reverse video. By using REVECHO in combination with the LOCATE command and the LOOP command, you can make a message flash on the screen. Since REVECHO looks at the existing color and reverses it each subsequent time you execute it, the color will appear to flash if executed many times in succession. Examples: A batch file which would flash the message "Warning!" in the middle of the screen could look similar to this: CLS LOOP /I :FLASHMES LOOP>LOCATE 12,35 REVECHO Warning! IF NOT ERRORLEVEL 100 GOTO FLASHMES 7-23 The SHIFT Batch Command Purpose: The shift command makes it possible for you to use more than the standard ten substitution variables, %0 to %9. Type: Internal to COMMAND.COM Syntax: SHIFT Remarks: SHIFT will let you move the value of a substitution variable down one step at a time (e.g., from %4 to %3 to %2 etc.). When you do this, you will lose the value of the lowest substitution variable, %0. If you need to retain a lower value, you can use the SET command to store the value of the %0 substitution variable in an environment variable before executing the SHIFT command. The SHIFT command can also be used even if you use less than the maximum ten substitution variables. Examples: To see how the SHIFT command works we have made a simple batch file: REM Test of the SHIFT commandECHO %0 %1 %2SHIFTECHO %0 %1 %2SHIFTECHO %0 %1 %2 You will need to run this batch file with parameters from the command line in order to see how it works. We call this batch file TEST.BAT and execute it with three parameters, number1, number2, and number3, like this: TEST number1 number2 number3 The output to your screen will look like this: TEST number1 number2number1 number2 number3number2 number3 7-24