OS/2 Shareware BBS: 11 Util

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

/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / ff_tools.zip / manual.doc < prev next >

Wrap

Text File | 1994-01-28 | 43KB | 1,252 lines

Forefront Toolkit Version 1.00 Copyright 1993-94, Forefront Technology ALL RIGHTS RESERVED Shareware Edition - January, 1994 INTRODUCTION SYSTEM REQUIREMENTS DOS: An IBM AT Compatible PC, or PS/2 computer. 384K RAM. DOS Version 3.3 to 6.2. OS/2: Standard or Extended Edition OS/2 1.21, 1.3 or OS/2 2.x INSTALLATION You do not need to install the Forefront Toolkit on your hard disk to use the tools. All of the tools can be run from the floppy drive. If you want to install the tools on your hard disk you can follow this procedure to install them. To install the toolkit on your hard disk, first insert the Forefront Toolkit disk into drive A:. Then create a directory for the toolkit and change to that directory. Finally type: COPY A:*.* If you would like to use the tools from any directory on your hard disk, you will also need to add the toolkit directory to the PATH statement in the AUTOEXEC.BAT (DOS) or CONFIG.SYS (OS/2) file. TABLE OF CONTENTS INTRODUCTION...................................................2 SYSTEM REQUIREMENTS.........................................2 INSTALLATION................................................2 TABLE OF CONTENTS..............................................3 The TOOLKIT....................................................4 ABOUT THE TOOLKIT...........................................4 HOW TO GET HELP.............................................4 ERROR LEVEL CODES...........................................4 CONVENTIONS.................................................5 DELALL......................................................7 FF..........................................................9 FS.........................................................13 KILL.......................................................17 TEE........................................................19 ...........................................................19 TOUCH......................................................20 TS.........................................................22 The TOOLKIT ABOUT THE TOOLKIT The Forefront Toolkit is a collection bimodal tools that can be used for file management, program development, remote support, and batch file enhancement. The tools in the kit fully support the OS/2 envi- ronment; HPFS long file names, OS/2 protected mode operation, and DOS operation. Since the tools are bimodal, they can run in OS/2, an OS/2 DOS Box, or real DOS. This is one of the most powerful features of the package. It means no more switching to DOS to search for a file or to search for text in a file. Those of you who work sometimes in DOS and sometimes in OS/2, now can use just one set of tools instead of one set for DOS and another for OS/2. HOW TO GET HELP Each tool in the kit has an on-line summary screen which displays the tool's command-line usage, a brief description of each optional parameter, and a brief description of what the tool does. To display the on-line help screen simply type the name of the tool you want help for followed by the '-?' parameter. For example, to display the on- line help screen for TS type: TS -? ERROR LEVEL CODES The tools in the Forefront Toolkit are frequently used in batch files. So that you may determine the results of running one of the tools in the toolkit, all of the tools return ERRORLEVEL codes. The following is a table of possible return codes that can be checked using the ERRORLEVEL test: 0 - No errors occurred, the operation was successful. 1 - Command-line arguments were invalid or missing. 2 - Memory or other system resources could not be allocated. 3 - Operator terminated operation by pressing <ESC>. The following are extended codes that can be returned for some tools if the -X option is valid and specified when invoking them. 4 - Some files were not processed due to errors. 5 - No matching files were found. 6 - No matching text string was found. 7 - Premature termination of delay by operator keypress. 8 - No matching process running. 9 - No unique process running. 10 - Specified process is currently running. The -X option is valid for the following tools with the following possible extended return codes: DELALL 4, 5 FF 5 FS 5 KILL 8, 9 TOUCH 4, 5 TS 4, 5, 6 For more information about creating batch files using the ERROR- LEVEL values see your OS/2 or DOS manual. CONVENTIONS Each explanation for a tool is divided into several sections. First is a few paragraphs on the operation and use of the tool. Then come the Caveats, Usage, Output, and Examples sections, as explained below. Caveats: Each tool has a Caveat section to describe warnings or limita- tions on use of the tool. Usage is: Each tool has a Usage section which describes the information which the tool needs in order to do its job. It also describes how to format that information in a way the tool will recognize. All tools which require filespecs allow up to ten of them. If multiple filespecs are specified, and all of them have the same path and drive, then the operation of the tool occurs in one pass. Otherwise, it occurs in multiple passes, i.e., one for each drive\path\filespec combination. Brackets [ ] enclose related parameters which are of two types: Required parameters All parameters which must be included in order for a tool to work have been underlined in the tool's Usage section. Optional parameters All parameters which need not be included in order for a tool to work have been enclosed with [ ] in the tool's Usage section. Output: Many tools have an Output section to show you what the output of the tool looks like and to explain what it means. Examples: Most tools have a selection of examples to get you started and show you the possibilities. DELALL The DELALL tool searches some or all of the directory tree in order to find and delete the files and directories you have selected. There is no way in either DOS or in OS/2 to delete all files in a directory and then delete the empty directory too. This tool deletes all files that are not open, locked, or write protected even if they have the System, Hidden, Read-only, or Archive attributes set. You may abort this utility, once it has started, by pressing the ESC key. The tool will ask you to confirm your decision. Press the ESC key again to confirm. Processing will stop as soon as it has finished deleting the current file or subdirectory. See also: DEL (DOS or OS/2), Caveats: DELALL ignores all file attributes when deleting files. This means that all hidden, archived, system, or read-only files which match the filespec will be deleted. All type-ahead keys are flushed from the keyboard buffer. Use extreme caution when using the -E option under OS/2 2.x. If you start from the root directory of the OS/2 2.x boot partition and specify a filespec from the root and the -E option, you may remove folders from the desktop. This is because OS/2 2.x creates empty directories for each folder on the desktop. DELALL will not delete files that are locked or in use. This means that files such as EA DATA. SF will not be deleted while running in OS/2. This also means that you will not be able to remove directories if another process running under OS/2 is using the directory as it's default directory. Usage is: DELALL [d:] [path] filespec [options] [ [ d:][path]filespec ] ] Where: [d:] Is an optional letter of the disk drive to search. If you do not include it, the current drive will be used. Drive option is invalid when the -A option is specified. [path] Is an optional path to begin searching. If you do not include path, the current directory will be used, unless of course the -A option has been specified. Path is invalid when the -A option is specified. filespecIdentifies the file(s) you want to delete. Filespec may include the * and ? wildcards in order to find all files which have the same kind of name. (Empty subdirectories will be removed when the '*' or '*.*' wildcards have been specified.) For HPFS filenames containing spaces, enclose the entire drive, path, and filespec in quotes, eg. "c:\mydir\my new data". You can find out if a file system is HPFS by using the DISKINFO tool. [options]May be any of the following: -A Search all drives (A: through Z:) for filespec. This option starts at the root of each drive. For safety, '*' and '*.*' wildcards are not valid with this option. -E Remove empty subdirectories which are in the path. If you want to remove subdirectories that are empty, but specify a filespec other than '*' or '*.*' then use this parameter. -T Display totals only. -Q Quiet mode. Do not list the directories as they are being searched. This option is useful when output is being piped to the OS/2 MORE command. -X Enable extended return codes. -Y Answer 'YES' to all prompts. This option is useful when DELALL is run from a batch file. -? Display on-line help screen. Output: Since this utility could delete all files on your disk, as a safety precaution the first output of this utility is the ques- tion asking if you are sure. Press the Y key if you want to proceed. To let you know how far DELALL has progressed it names the files it deletes, and, as DELALL enters each new subdirectory to be searched, the path of the subdirectory will be displayed (unless the -Q option was specified). When it has finished, the utility displays the total number of files it has deleted, the number of bytes in those files, and the number of directories removed. Sample output screen: DELALL, Version 1.00, (C) 1993 Forefront Technology DELete ALL files matching pattern * Delete ... TEST\beta Delete ... TEST\delall.MAP Delete ... TEST\level12\delall.obj Delete ... TEST\level12\delall.old Remove ... TEST\level12 Remove ... TEST 4 files deleted totaling 86,488 bytes. 2 directories removed. Examples: To delete all files on the floppy A: drive: DELALL A:\*.* To delete all of the .BAK files in the current directory and all directories below the current one: DELALL *.BAK To delete all of the .BAK files on the current disk: DELALL \*.BAK To delete all of the .BAK files on all disk drives: DELALL *.BAK -A To remove a previous version of some software package which resides on the C drive beginning in a directory called XYZSS, you could execute the following lines from a batch file: ECHO Now removing XYZ Super System. Please wait... DELALL C:\XYZSS\* -Y -Q -T CLS ECHO XYZ Super System now removed. To delete all files ending in .TXT from the current directory and all of its subdirectories, and remove any empty subdirectories: DELALL *.TXT -E or DELALL -E *.TXT To delete all files ending in .BAK or .SAV in one pass: DELALL *.BAK *.SAV FF The FF tool searches some or all of the directory tree in order to find and display the directory locations of the files you have selected. FF ignores all file attributes when looking for matching files, so even hidden or system files will be found. You may abort this utility, once it has started, by pressing the ESC key. The tool will ask you to confirm your decision. Press the ESC key again to confirm. Processing will stop as soon as it has finished with the current file or subdirectory. Caveats: All type-ahead keys are flushed from the keyboard buffer. Usage is: FF [d:] [path] filespec [options] [ [ d:] [path] filespec ] ] Where: [d:] Is an optional letter of the drive to search. If you do not include it, the current drive will be used. Drive is invalid when the -A option is specified. [path] Is an optional path to begin searching. If you do not include path, the current directory will be used. Path is invalid when the -A option is specified. filespecFilespec may include the * and ? wildcards in order to find all files which have the same kind of name. For HPFS filenames containing spaces, enclose the entire drive, path, and filespec in quotes, eg. "c:\mydir\my new data". You can find out if a file system is HPFS by using the DISKINFO tool. [options]May any of the following: -A Search all drives (A: through Z:) for files. This option starts the search at the root of each drive. -I Display the ISO (International Standards Organization) sortable date format of YY/MM/DD. -P Pause the display after each screen is filled. -Q Quiet mode. Do not display the directories as they are being searched. This option is useful when output is being piped to the OS/2 MORE command. -X Enable extended return codes. -? Display the on-line help screen. Output: FF first displays a banner which tells you what filespec is being used in the search. Remaining output is in four columns: The first column displays the date associated with the file. It will be in MM/DD/YY form unless the -I option is specified. In DOS there is only one date associated with a file and that date is the one FF displays. In OS/2 there are three dates associated with each file. They are Date Created, Date Last Accessed, and Date Last Written. In OS/2 the date displayed is the Date Last Written. This is consistent with the OS/2 DIR command. The second column lists the time associated with the file. This is a twelve hour time with a 'p' suffix for P.M., and an 'a' suffix for A.M. In DOS there is only one time associated with a file and that time is displayed. In OS/2 there are three times associated with each file. They are Time Created, Time of Last Access, and Time Last Written. FF displays the Time Last Writ- ten. This is consistent with the OS/2 DIR command. The next column gives the size of the file in bytes, and the last column displays the pathname of the matching file. When all matching files have been found, FF displays the total number of files it found. Sample output with standard date format (Notice the HPFS format long names): FILE FIND, Version 1.00, (C) 1993 Forefront Technology FIND FILES matching pattern *.BAK 01/10/93 10:44p 30,481 \DeScribe\beta_notes_099.BAK 01/17/93 05:39p 147,347 \DeScribe\notes_for_docs.BAK 01/17/93 05:30p 27,164 \DeScribe\quick_reference.BAK 12/10/92 08:13p 10,148 \DeScribe\ideas\idea_list.BAK 4 files found. Examples: To find all files which match *.BAK on the current drive: FF \*.BAK To find all files which have "TOM" anywhere in the filename: FF *TOM* To find all files called "letter to tom" on an HPFS file system: FF "letter to tom" To find all .C and .H files on all drives: FF *.C *.H -A To display all .DLL files on all drives, and pause the output after every screen full of names: FF *.DLL -P -A FS The FS tool finds and displays both the actual file size and the allocated disk space of each file you have selected. After all of the selected files have been processed, the utility shows total actual file size and allocated disk space for all displayed files. Most disk files have more space allocated to the file than there is data stored there. Slack space is the difference between actual file size and allocated disk space. FS ignores all file attributes when looking for matching files. This means that both System and Hidden files can be found. You may abort this utility, once it has started, by pressing the ESC key. The tool will ask you to confirm your decision. Press the ESC key again to confirm. Processing will stop as soon as it has finished with the current file or subdirectory. Related utilities are: FF. Caveats: FS does not display slack space in a DOS Box because the file system is virtual FAT (File Allocation Table), but the actual file system may be HPFS (High Performance File System) or other non-FAT file system. If the actual file system is other than FAT, the slack space calculation in an internal DOS com- puter would be misleading. Slack space calculation in an external DOS Box (VM boot image) will be calculated normally but may also be incorrect if the underlying file system is other than FAT. All type-ahead keys are flushed from the keyboard buffer. Usage is: FS [d:] [path] filespec [options] [ [ d:] [path] filespec ] ] Where: [d:] Is an optional letter of the drive to search. If you do not include it, the current drive will be used. Drive is invalid when the -A option is specified. [path] Is an optional path to begin searching. If you do not include path, the current directory will be used. Path is invalid when the -A option is specified. filespecFilespec may include the * and ? wildcards in order to find all files which have the same kind of name. For HPFS filenames containing spaces, enclose the entire drive, path, and filespec in quotes, eg. "c:\mydir\my new data". You can find out if a file system is HPFS by using the DISKINFO tool. [options]May be any of the following: -A Search all drives (A: through Z:) for files. This option starts the search at the root of each drive, and auto- matically selects the -S option. -I Include subtotals for each subdirectory. -P Pause the display when the screen is full. -Q Quiet mode. Do not list the directories as they are being searched. This option is useful in conjunction with the OS/2 MORE command. -S Include subdirectories in the search. -T Display total file size, but do not display the size of individual files. -X Enable extended return codes. -? Display on-line help screen. Output: FS first displays a banner which tells you what filespec is being sought. The rest of the output is divided into two columns fol- lowed by summary information. The first column displays the size in bytes of the matching file. This is the actual size of the file, not the amount of space allocated on the disk. The second column is the pathname of the matching file. The summary gives first the total number of bytes in all matching files, and the number of files that were found. The next line is the slack space information. Note that this line may not display if FS is run in a DOS Box. Last is the drive information. The first line displays the drive. The next line displays the total number of bytes of disk space on the drive. The last line displays the number of bytes available and the percentage of disk space available. Sample output screen: FILE SIZE, Version 1.00, (C) 1993, Forefront Technology FILE SIZE of files matching pattern *.* 3,326 CONFIG.LAP 40,415 README 3,588 CONFIG.BK$ 325 AUTOEXEC.BAT 3,185 CONFIG.GWR 3,027 CONFIG.WAS 3,717 CONFIG.$SY 3,185 CONFIG.WAL 43 FS.OUT 806,912 EA DATA. SF 8,516 OS2LDR.MSG 2,760 OS2DUMP 734,366 OS2KRNL 28,160 OS2LDR 89 OS2VER 1,099 OS2BOOT 224 WP ROOT. SF 1,784 IBMLVL.INI 3,726 CONFIG.SYS Totals for all matching files 1,648,447 total bytes used in 19 files. 1,667,072 bytes disk space allocated, 1% slack space. Drive C: information 115,171,328 bytes total disk space. 37,142,528 bytes available, 32% of disk. Examples: To find the size of all files in the current directory: FS *.* To find the size of all files on the A: drive and all of its subdirectories: FS A:\*.* -S To find the size of all backup (*.BAK) files on all drives: FS *.BAK -A To find the size of all files in a directory and all of its sub- directories, and display subtotals for each subdirectory: FS *.* -S -I KILL The KILL tool is available for OS/2 only. It allows you to ter- minate a process or program without having to use any of the menus or functions of that process or program. Optionally you may kill a process and all of its child processes. The ability to kill a process from outside that process is especially useful in program development when a programming bug has made it impos- sible to terminate the process normally. This utility is also useful for remote program support to stop programs that you cannot switch to. In the interactive mode this tool displays a list of the entries in the OS/2 switch list. You may select one item on that list to kill. This is useful if you do not know the program's PID. Related OS/2 utilities: PSTAT and DETACH. Caveats: Use this tool with great care. You must be sure that you have the right PID, as any data in the killed process or its chil- dren may be lost. Be sure to save to disk any memory- resident data in a program you want to kill. It is possible under OS/2 2.x to kill the Desktop. If you do this, the Workplace Shell automatically starts back up in 30 seconds. When in doubt, use the interactive mode to reduce the chances of killing the Desktop or other OS/2 internal process. KILL assumes that if it got a successful operation status from OS/2 that the process was killed. It is possible that KILL will not report an error and will not kill a process. This can happen for two reasons: One, the program being killed has installed a signal handling routine to perform cleanup when killed, and is either not done cleaning up, or is ignoring the signal (usually a programming bug). Two, the program being killed is in the middle of a system call and can not be ter- minated until it returns from that call. Usually if KILL cannot kill a program then neither can the OS/2 task manager. Some processes (like the Workplace Shell) have multiple entries in the OS/2 internal switch list. These entries can have the same PID if a different window handle is specified. Usage is: KILL pid [options] Where: [pid] Identifies the process or program you want to stop. The default format for PID is decimal. Optionally you can use PSTAT format which is a hexadecimal number proceeded with '0x', i.e., 0x3c. Hexadecimal process numbers can be determined by using the PSTAT /C command. [options]May be any of the following: -N Kill process by name. Format for this option is -N:string where string is the process name of the process that you want to kill. -T Kill the entire process tree which starts with the parent process specified by the PID, including any process started from that parent or its children. -X Enable extended return codes. -? Display on-line help screen. Output: None in the command mode. In interactive mode a list of all programs in the OS/2 switch list. KILL, Version 1.00, (C) 1993, Forefront Technology Entry: 15 Title: DeScribe 4.0:1 Entry: 8 Title: SWLIST.EXE Entry: 4 Title: OS/2 2.0 Desktop Entry to kill or <ENTER> to abort: Examples: This example uses the -N option to kill a process by name. We will kill the process NNLINK as part of a command file that shuts down a communications session. ECHO Now terminating communications session... KILL -N:NNLINK CMSTOP ... TEE The TEE tool redirects the standard output of a given program to a file as well as to the standard output device. This is useful for saving the output of a program to a file for later examina- tion. Output will be stored in the indicated file, and will be displayed on the screen as well. Caveats: Since TEE is invoked after a command, it there is an error in the TEE parameters the tool will beep and display an error message, then wait 5 seconds and continue to display the screen output of the command without routing the output to a file. Usage is: command | TEE filename [options] Where: command Is the command which runs the program whose output you want to redirect. The line of text will contain the name of the program, plus any parameters necessary to run that program. filenameIs the name of the file to which you want the output of the command line directed. [options]May be any of the following: -A Append output to the existing contents of the file given in filename, rather than writing over them. -? Display on-line help screen. Examples: To capture the output of a compile to the ERR file: cl -DTEST -G2s test | TEE err TOUCH This tool allows you to change the time and date of matching files or create a file of 0 bytes with the current time and date. This utility is often used to trigger recompiles of programs or modules, or to set time time/date of all files in a release. You can set the date or date/time of files with TOUCH. By default TOUCH uses the current date and time unless the -D and -T parameters are used. The -D and -T parameters allow you to specify a date and time to use when touching files. If you specify a single file to touch and that file does not exist, then TOUCH will create it as a zero length file with the specified or current date. This feature is to maintain compat- ibility with other TOUCH utilities. You may abort this utility, once it has started, by pressing the ESC key. The tool will ask you to confirm your decision. Press the ESC key again to confirm. Processing will stop as soon as it has finished with the current file or subdirectory. Caveats: All type-ahead keys are flushed from the keyboard buffer. Usage is: TOUCH [d:][path] filspec [options] [ [ d:] [path] filespec ] ] Where: [d:] Is the letter of the drive to search. This is optional. If you do not include it, the current drive will be used. Drive is invalid when the -A option is specified. [path] Is an optional path to begin searching. If you do not include path, the current directory will be used. Path is invalid when the -A option is specified. filespecFilespec may include the * and ? wildcards in order to find all files which have the same kind of name. For HPFS filenames containing spaces, enclose the entire drive, path, and filespec in quotes, eg. "c:\mydir\my new data". You can find out if a file system is HPFS by using the DISKINFO tool. [options]May be any of the following: -A Search all drives (A: through Z:) for filespec. This option starts the path at the root of each drive. Using this option automatically selects the -S option. -D Set the date from parameters supplied on the command line, eg. -DMM/DD/YY where MM is the desired month, DD the desired date, and YY the desired year. -Q Quiet mode. Do not list the directories as they are being searched. -S Include subdirectories. -T Set the time from parameters supplied on the command line, eg. -THH:MM where HH is the desired hour, and MM is the desired minute. This option is only valid when the -D option has been specified previously on the command line. -X Enable extended return codes. -? Display on-line help screen. Examples: [C:\]touch *.bat -a TOUCH, Version 1.00, (C) 1993, Forefront Technology TOUCH files matching pattern *.BAT using 01/18/93 16:39 C:\AUTOEXEC.BAT D:\AUTOEXEC.BAT D:\OS2\MDOS\HELP.BAT 3 files found. 3 files touched. [C:\]touch *\help.bat -a -d01/18/93 -t01:01 TOUCH, Version 1.00, (C) 1993, Forefront Technology TOUCH files matching pattern HELP.BAT using 01/18/93 01:01 D:\OS2\MDOS\HELP.BAT 1 file found. 1 file touched. TS This tool allows you to search the specified files for the specified text. This utility is used mostly by programmers to find certain functions or variables in a group of program files. TS first determines if the file being searched is binary or plain text, then it searches the file for the text. If the text is found, it is displayed on the screen. If the file is binary, as much of the text string is displayed as is printable and the byte offset in the file is displayed. If the file is ASCII text, then the line containing the text is displayed and the line number is displayed. You may abort this utility, once it has started, by pressing the ESC key. The tool will ask you to confirm your decision. Press the ESC key again to confirm. Processing will stop as soon as TS has finished with the current file or subdirectory. Caveats: All type-ahead keys are flushed from the keyboard buffer. Usage is: TS text [d:][path] filspec [options] [ [ d:] [path] filespec ] ] Where: text Is the string of characters you want to find. If there is more than one word in text, you must enclose it in quotes, eg., "My search string.". If the search text is entered on the command line, there is no way to include quotes (") in the search text as they will be stripped off by the command processor. If you need to include quotes in the search text, use the interactive mode. [d:] Is the letter of the drive to search. This is optional. If you do not include it, the current drive will be used. Drive is invalid when the -A option is specified. [path] Is an optional path to begin searching. If you do not include path, the current directory will be used. Path is invalid when the -A option is specified. filespecFilespec may include the * and ? wildcards in order to find all files which have the same kind of name. For HPFS filenames containing spaces, enclose the entire drive, path, and filespec in quotes, eg. "c:\mydir\my new data". You can find out if a file system is HPFS by using the DISKINFO tool. [options]May be any of the following: -A Search all drives (A: through Z:) for path\filespec. This option starts the path at the root of each drive, and is ignored if the filespec is *.*. Using this option automatically selects the -S option. -C Case sensitive. Text must match exactly including case of characters. By default the match ignores case. -F Display filename only. Specifying this option will dis- play only the filename of the files that contain the text, not the line number or offset to the text. -I Enable interactive mode. When displaying text in inter- active mode, you are presented with a screen containing the 5 lines above and below the line containing the text string. The text string will be displayed in reverse video to highlight it's position in the match line. -P Pause the display when each screen is full. -Q Quiet mode. Do not list the directories as they are being searched. -S Include subdirectories in the search. -X Enable extended return codes. -? Display an on-line help screen. Examples: [C:\]ts path *.bat -a -s TEXT SEARCH, Version 1.00, (C) 1993, Forefront Technology Find files matching pattern *.BAT that contain text "PATH" C:\AUTOEXEC.BAT(2) PATH=C:\DOS;C:\SYMAX; D:\AUTOEXEC.BAT(5) PATH D:\OS2;D:OS2\MDOS;D:\OS2\MDOS\WINOS2; 2 occurrences of PATH found in 2 files.