In'side Shareware 1995 March

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

/ In'side Shareware 1995 March / ish0395.iso / win_util / dtsearch / batch.doc < prev next >

Wrap

Text File | 1994-06-01 | 29KB | 750 lines

dtSearch Batch Script Language User's Manual Copyright 1994 DT Software, Inc. Contents 1. Introduction: Basic Batch Indexing . . . . . . . . . 1 a. Automatic Generation of Batch Scripts . . . . . . 1 b. Running a batch script . . . . . . . . . . . . . 2 2. Script files . . . . . . . . . . . . . . . . . . . . 2 3. Indexing Commands . . . . . . . . . . . . . . . . . . 3 a. Create Index . . . . . . . . . . . . . . . . . . 3 b. Add Documents to Index . . . . . . . . . . . . . 4 c. Indexing subdirectories . . . . . . . . . . . . . 5 d. Update index . . . . . . . . . . . . . . . . . . 5 e. Compress an Index . . . . . . . . . . . . . . . . 5 4. Search Commands . . . . . . . . . . . . . . . . . . . 5 a. Index Searches . . . . . . . . . . . . . . . . . 5 b. Search Results . . . . . . . . . . . . . . . . . 6 c. Listing files . . . . . . . . . . . . . . . . . . 6 d. Search Reports . . . . . . . . . . . . . . . . . 7 5. Listing commands . . . . . . . . . . . . . . . . . . 7 a. LIST WORDS . . . . . . . . . . . . . . . . . . . 8 b. LIST FILES . . . . . . . . . . . . . . . . . . . 8 c. LIST INFO . . . . . . . . . . . . . . . . . . . . 8 d. LIST TEXT . . . . . . . . . . . . . . . . . . . . 9 6. Other Commands . . . . . . . . . . . . . . . . . . . 9 7. Environment variables . . . . . . . . . . . . . . . . 10 8. DDE API . . . . . . . . . . . . . . . . . . . . . . . 10 9. Reference . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction: Basic Batch Indexing ---------------------------------------------------------------- Batch mode indexing allows you to create, update, and compress a document index by running dtSearch from the command line or, in Windows, using DDE. Batch mode indexing can be useful if, for example, you want to perform a complex and time- consuming series of tasks every night to update your indexes. To set up a batch indexing job, first create a "script" that lists the tasks that you want dtSearch to perform. A script is a text file that lists a series of indexing commands that dtSearch will carry out. a. Automatic Generation of Batch Scripts The easiest way to create a script is to use the Create Batch Script option in the Index menu. When you select this option, a dialog box will appear that is almost identical to the "Add Documents to Index" dialog box. Fill out the box exactly as you would if you were updating an index. See the section on "Adding Documents to an Index" in the "Indexing Documents" chapter for more information about the 2 options in the Create Batch Script dialog box. When you are done setting up the indexing job, choose OK to create a script. A dialog box will pop up asking for the name of the script to create. Enter a name for the script and choose OK. dtSearch will then store all of the information you have provided (the index to update, the directories to index, etc.) in a script file that you can run later. b. Running a batch script To run the script that you created, first exit dtSearch. A batch script cannot be run from the DOS shell option in the File menu. After you are out of dtSearch, type the following at the DOS prompt: DTSEARCH /SCRIPT MYSCRIPT.JOB where "MYSCRIPT.JOB" is the name of your script. You should be in the directory where dtSearch is installed when you do this. If you created the script in a different directory, you will need to supply the full pathname of the script, e.g., C:\WHATEVER\MYSCRIPT.JOB. dtSearch will then perform the indexing task you specified. dtSearch will record any errors encountered during the job in a file called MYSCRIPT.LOG. Errors and informational messages will not be displayed on the screen, since dtSearch assumes that batch jobs will run without someone watching them. After a batch indexing job, you should check the log file to see if any errors occurred. This is all that you need to know to set up basic batch indexing tasks. 2. Script files ---------------------------------------------------------------- A script file is any text file that dtSearch can read. You can create a script using the Create Batch Script option in the Index menu, or you can create a script by hand. Before you try to write your own scripts, you may want to create an example using the Create Batch Script function so you can see what a batch script looks like. After you create the script, choose View File in the File menu to read it. Using Edit File, you can easily edit the script to create a new script. You can also create a script outside of dtSearch. A script can be ASCII text or it can be in one of the word processor formats that dtSearch recognizes, such as WordPerfect or WordStar. The first line of a script must consist of the words DTSEARCH SCRIPT. 3 A script consists of a series of "SET" statements that specify the documents to be indexed and the index to use, and commands such as "ADD" and "COMPRESS." dtSearch ignores any line beginning with a *, so you can include comments in a script. Here is an example: DTSEARCH SCRIPT * Create the index SET INDEXNAME = MyIndex CREATE * Add documents from C:\DOCS SET DOCPATH = C:\DOCS SET FILTER = *.DOC *.TXT *.WPF ADD * Compress the index COMPRESS This script would (1) create an index called "MyIndex," (2) add to the index documents in the directory C:\DOCS, and (3) compress the index. (You can combine several different indexing and searching operations in a single script.) To run this script, put it in the file UPDATE.JOB in the dtSearch directory and execute the command: DTSEARCH /SCRIPT UPDATE.JOB from the dtSearch directory. dtSearch will then execute the script, logging any error messages to the file UPDATE.LOG. 3. Indexing Commands ---------------------------------------------------------------- a. Create Index To create an index, set up a script like this: DTSEARCH SCRIPT SET INDEXNAME = MyIndex SET INDEXPATH = C:\DOCINDEX CREATE The two SET statements tell the program what you want to call the index and the directory you want to put it into. The "CREATE" statement tells dtSearch to create the index in the specified directory. There are three options you can use with CREATE: ARCHIVE, CASE, and ACCENT. ARCHIVE: Use this option if you want to create an archive index. This is an index that contains the text of indexed documents, in compressed form. 4 CASE: Use this option if you want the index to be case- sensitive. ACCENT: Use this option if you want the index to be accent- sensitive. To use one or more of these options, simply list them on the same line as the CREATE command: CREATE ARCHIVE CASE WARNING: Please be careful when using CREATE. If you create an index that already exists, dtSearch will delete the old index and create a new, empty index in its place. In interactive mode, you will get a warning message before this happens, but in batch mode dtSearch simply assumes that you really want to create a new index. b. Add Documents to Index To add documents to an index in a batch script, you need to select an index to add to, list the directories to index, and list the file name filters you want to use. Use "SET DOCPATH =" to tell dtSearch the directory in which the documents are located. If you want to index more than one directory, list the directories with plus signs ("+") separating them, like this: SET DOCPATH = C:\ONE + C:\TWO + C:\THREE + C:\FOUR + C:\FIVE If the list of directories will take up more than one line, make sure that each line ends in a plus sign so that dtSearch knows to look on the next line for more directories. To specify file name filters, use "SET FILTER =". Use "SET EXCLUDE =" to specify files that you do not want to index. After you have provided the information dtSearch needs to index your documents, use "ADD" to add the documents to the index. Example: DTSEARCH SCRIPT SET INDEXNAME = MyIndex SET DOCPATH = C:\DOCS + C:\DOCS2 + C:\DOCS3 SET FILTER = *.DOC *.TXT *.WPF SET EXCLUDE = A*.DOC ADD This would add documents from C:\DOCS, C:\DOCS2, and C:\DOCS3 to 5 the index "MyIndex." The CREATE function needs to know both the name and the directory for an index, and so both the SET INDEXNAME and the SET INDEXPATH must be present to create an index. The ADD function just needs to know which index you want to add documents to, so you can use either the name (SET INDEXNAME) or the path (SET INDEXPATH) to specify the index. c. Indexing subdirectories If you want dtSearch to index a directory and all of its subdirectories, add "&SUBS" after the name of the directory in the SET DOCPATH command, like this: SET DOCPATH = C:\DOCS &SUBS This way you do not have to update your script each time you add a subdirectory to the C:\DOCS directory. d. Update index The UPDATEFILES command in a script will cause dtSearch to reindex any documents in an index that have been modified since the index was last updated. If a document no longer exists, dtSearch will remove it from the index. This is the batch mode equivalent to the "Update files in index" option in the Add Documents to Index dialog box. Example: DTSEARCH SCRIPT SET INDEXNAME = MyIndex UPDATEFILES NOTE: For compatibility with earlier versions of dtSearch, the REINDEX command has the same effect as UPDATEFILES. e. Compress an Index To compress an index, use SET INDEXNAME or SET INDEXPATH to specify the index to compress and then use the COMPRESS command. Example: DTSEARCH SCRIPT SET INDEXNAME = MyIndex COMPRESS 4. Search Commands ---------------------------------------------------------------- a. Index Searches The following is an example of a batch script that would 6 perform an indexed search: DTSEARCH SCRIPT SET REQUEST = apple and pear + and banana SET INDEXES = Index1 + Index2 + Index3 SET SORT = HITS SET RESULTS = c:\dtsearch\search1.dat SEARCH SET REQUEST tells dtSearch what you want to search for. Note that since the request was too long to fit on one line the first line ends in a + to indicate that the request continues on the next line. SET INDEXES tells dtSearch which indexes you want to search. If you want to search more than one index, be sure to use a + to separate the names of the indexes you want to search. Use SET SORT to specify how the search results will be sorted. Options are: HITS Sort by hits. NAME Sort by name. DATE Sort by date. NONE Unsorted. You can use ASCENDING or DESCENDING after the type of search to specify an ascending or descending sort. For example: SET SORT = NAME DESCENDING This would specify a sort in reverse alphabetical order. By default, name sorts are ascending and hits and date sorts are descending. b. Search Results After your search, you will want to be able to see the results. To store the results of your search in a dtSearch "Search Results" file, use SET RESULTS to tell dtSearch the name of the file to create, like this: SET RESULTS = c:\mysearch.dat This tells dtSearch to write the results of the search to c:\mysearch.dat. After your search, you can choose View File in the File menu to view c:\mysearch.dat. Your search results will appear in the same way as other search results in dtSearch. 7 c. Listing Files A second way to view your search results is to tell dtSearch to create a listing file, which is simply a list of the retrieved documents in Ascii text format. If you view this file in dtSearch, it will look like a list of names and will not act like a search results window. Listing files are useful if you want to use another program to process the results of your search. To create a listing file, add a > and the name of the file to create after the SEARCH command, like this: SEARCH > listing.txt To append your search results to an existing file, use >> instead of >, like this: SEARCH >> listing.txt The listing file will contain a header with your search request, the date of the search, and the number of files retrieved. To suppress this header, add SET HEADER = NO to your script before the SEARCH command. Ordinarily, a listing file will contain only the names of the retrieved files. If you want the number of hits in each file to be included in the file, add COUNT after the SEARCH command, like this: SEARCH COUNT > listing.txt d. Search Reports The REPORT command will create a search report based on search results. Example: REPORT results.dat report.dat 30 This would create a search report in report.dat based on the search results in results.dat. The report would contain 30 words of context surrounding each hit retrieved. 5. Listing commands ---------------------------------------------------------------- The LIST command will list words in an index, files in an index, information about an index, or the text of a file. By default, the output of a LIST command will go into your LOG file. To redirect it to another file, use the same > and >> symbols used in the SEARCH command, like this: LIST WORDS > words.lst 8 a. LIST WORDS LIST WORDS will create a list of all of the words in the currently selected index. Example: SET INDEXNAME = MyIndex LIST WORDS > words.lst LIST WORDS COUNT will list, next to each word, the number of times it occurs in the index. To selectively list words in an index, use a filter, like this: LIST WORDS ="APPL*" > words.lst This will list all words that match APPL*. The filter can contain wildcards like * and ?, the phonic search character #, the stemming character ~, and the fuzzy search character %. For example, LIST WORDS ="AP%%PLICATION" LIST WORDS ="#APPLICATION" The first command would list all words that match a fuzzy search for APPLICATION. The second command would list all words that sound like APPLICATION. b. LIST FILES LIST FILES works exactly like LIST WORDS except that it lists filenames instead of words. The > and >> symbols work the same way, and you can use the same types of filters. For example, SET INDEXNAME = MyIndex LIST FILES ="SMITH*.DOC" > smith.lst This would list all files in MyIndex whose name matches SMITH*.DOC. c. LIST INFO LIST INFO lists the information about an index that appears in the Index Information dialog box. This includes the date the indexes was created and last modified, the number of documents in the index, the size of the index, etc. Example: SET INDEXNAME = MyIndex LIST INFO 9 d. LIST TEXT LIST TEXT provides an easy way to extract the text from a file that is in a format that dtSearch recognizes. Example: LIST TEXT smith.doc > smith.txt If smith.doc is a WordPerfect file, smith.txt would contain the text of that file as it would appear in dtSearch. Another example: SET INDEXES = MyIndex SET REQUEST = apple w/5 pear SET RESULTS = results.dat SEARCH REPORT results.dat report.dat 30 LIST TEXT report.dat > report.txt This script would search MyIndex for "apple w/5 pear", write the results to results.dat, prepare a search report based on results.dat, and then extract the text of the search report to report.txt. 6. Other Commands ---------------------------------------------------------------- QUIT terminates execution of a script and also causes the program to exit. dtSearch for DOS will automatically exit after running a script, but dtSearch for Windows will not exit after running a script unless the script ends with a QUIT command. This makes it possible for another Windows program to start dtSearch for Windows and pass it several scripts to execute using the DDE interface. If you want dtSearch for Windows to exit after it is done running a script, just add QUIT as the last line of the batch script. The WINDOW commands control the appearance of the dtSearch main window. WINDOW MIN reduces it to an icon. WINDOW MAX maximizes it to fill the screen. WINDOW NORMAL displays the window at its default size. OPTION allows you to change a dtSearch setup option. What follows the OPTION line is treated as if it were a line in the dtSearch OPTIONS.DAT file. For example, OPTIONS.DAT contains the line SearchLimit = 99 10 Which specifies the maximum number of files to retrieve in a search. To change the search limit, use the command OPTION SearchLimit = 999 7. Environment variables ---------------------------------------------------------------- If you include an environment variable in a batch script command, dtSearch will substitute it with the value of the variable in the current environment. For example, if the variable %DTSDIR% has the value "C:\DTSEARCH", then a script could include the line SEARCH > %DTSDIR%\RESULTS.LST dtSearch would interpret this to mean SEARCH > C:\DTSEARCH\RESULTS.LST 8. DDE API ---------------------------------------------------------------- dtSearch for Windows responds to a DDE-based API so you can use dtSearch for Windows to perform searching or indexing tasks in another program. The DDE API is based on batch scripts. To enable the dtSearch DDE interface, run DTSWIN /DDE. A window labelled "DDE Server" will appear in dtSearch for Windows. To execute a script, connect to the service "dtSearch" with the topic "script," then send a DDE Execute message with the name of the script to execute. dtSearch will execute the script and record the results in a file with the same name as the script ending with .LOG. 9. Reference ---------------------------------------------------------------- Words in capital letters are keywords. Items in braces -- { } -- are optional. The {> filename} parameter means that output from the command can be redirected to a file. Use >> instead of > if you want the output to be appended to an existing file. ADD Begin adding documents to an index. Use SET INDEXNAME or SET INDEXPATH to specify the index, SET FILTER to specify filename filters, and SET DOCPATH to specify directories. COMPRESS Compress an index. Use SET INDEXNAME or SET INDEXPATH to specify the index to compress. 11 CREATE {ARCHIVE} {CASE} {ACCENT} Create a new index. Use SET INDEXNAME to specify the name of the index and SET INDEXPATH to specify the directory. Options: ARCHIVE Create an archive index that stores the text of indexed files. CASE Create a case-sensitive index. ACCENT Create an accent-sensitive index. LIST FILES {="filter"} {> filename} List files in an index. Use SET INDEXNAME or SET INDEXPATH to specify the index. The optional filter, if present, will select the files to be listed. LIST INFO {> filename} List information about an index (the information that is displayed in the Index Information dialog box). Use SET INDEXNAME or SET INDEXPATH to specify the index. LIST WORDS {COUNT} {="filter"} {> filename} List words in an index. Use SET INDEXNAME or SET INDEXPATH to specify the index. The optional filter, if present, will select the words to be listed. The filter can include wildcards (* and ?), fuzzy (%) and phonic searching (#), and stemming(~). LIST TEXT filename1 {> filename2} List the text of filename1, writing the output to filename2. OPTION option-text Changes a user option in the dtSearch OPTIONS.DAT file. The text following the word OPTION is treated as if it were a line in OPTIONS.DAT. QUIT Exit dtSearch. REPORT ResultsName ReportName WordsOfContext Create a search report in ReportName based on search results in ResultsName. 12 SEARCH {COUNT} {> filename} Perform a search. Use SET INDEXES to specify the indexes to search, SET REQUEST to specify the search request, SET RESULTS to specify the name of the search results file, and SET SORT to specify how the results should be sorted. SEARCH > filename will list the full name of each retrieved document. SEARCH COUNT > filename will list the number of hits and the name of each retrieved document. SET EXCLUDE = {filename filters} Specify files not to be indexed. More than one filter can be included (use spaces to separate them). SET DOCPATH = path1 + path2 + ... Specify the directories to be indexed. If the list extends over more than one line, each line (except the last) should end in a + sign so dtSearch knows that the list continues on the next line. &SUBS after a directory name means index the directory and any subdirectories. SET FILTER = {filename filters} Specify files to be indexed. More than one filter can be included (use spaces to separate them). SET HEADER = {YES|NO} A search listing will contain a header with your search request, the date of the search, and the number of files retrieved. To suppress this header, use SET HEADER = NO. SET INDEXES = list of indexes Select indexes to be searched. List the names of each index to search with + signs between them if you want to search more than one index. SET INDEXNAME = name Specify the name of an index to update or create. SET INDEXPATH = Specify the directory of an index to update or create. 13 SET LIB = filename Select a new index library. If the library does not exist, it will be created. SET REQUEST = search request Enter a search request for a SEARCH command. SET RESULTS = filename Specify the name of the search results file to create in a search. If you view this file in dtSearch using View File in the File menu, it will act exactly like the search results files created in an interactive search. SET SORT = {HITS|DATE|NAME|NONE} {ASCENDING|DESCENDING} Specify how you want the results of a search to be sorted. UPDATEFILES Check each file in an index and reindex it if it has changed since it was last indexed. If the file has been deleted, remove it from the index. WINDOW {MAX|MIN|NORMAL} In dtSearch for Windows, change the appearance of the dtSearch main window.