DESCRIBE - Directory Descriptor Extension TABLE OF CONTENTS General Information 1 Invoking DESCRIBE 2 Alter a descriptor field 3 Change to a new drive 3 DOS Command request 4 File directory display 4 Help information 4 Interchange data LOAD and SAVE 4 Modify listing format 5 Remove descriptors from a disk 6 Search for a string 6 DESCRIBE: Copyright 1984 by MISOSYS, INC., All rights reserved. DESCRIBE is published by MISOSYS, Inc., Sterling VA 22170. LDOS and LS-DOS are trademarks of Logical Systems Inc. TRSDOS is a trademark of Tandy Corp. GENERAL INFORMATION This documentation covers the Model I/III version of DESCRIBE which functions under the LDOS 5.1 operating system. It also covers the TRSDOS 6.x or LS-DOS 6.x version of DESCRIBE called PRO-DESCRIBE. The specific version of DESCRIBE is noted on the diskette label supplied with this package. The program and its overlays are stored in a Partitioned Data Set. This file has a password which limits its access to READ. If for any reason you need to write to the DESCRIBE/CMD file (such as to apply a patch) or to RENAME the file, or any other access which is greater than READ, use the password, ".DESCRIBE". DESCRIBE provides the user with an extension to the DOS directory which incorporates a 63-character descriptor record. This facility gives you the convenience of a complete description for each file - anytime that the file is accessible. INVOKING DESCRIBE DESCRIBE is easily invoked in two formats. To invoke the utility for a maintenance purpose (such as to edit a descriptor field), just enter the command, DESCRIBE or whatever name you have RENAMEd the program data set. A menu of operations will be displayed. If you only want to display a file directory display for a disk that has been extended with descriptors, invoke DESCRIBE with the command, DESCRIBE ambigspec where "ambigspec" is considered to be an ambiguous file specification. This takes the form of a file name field, a file extension field, and a mandatory drive specification. Within the filename and extension fields, the character "*" will match all other characters remaining in the field while the character "?" will match all other characters in that position. If the filename field is blank, it will default to "*". If the extension field is blank, it will match only a file with no extension. If you omit both fields, the ambigspec defaults to */*:d. If you select the maintenance mode of invocation, the displayed menu will look something like the following screen. DESCRIBE 1.0 Copyright (c) 1984 MISOSYS, Inc. lter descriptor field nterchange data hange to a new drive odify listing format OS Command request emove descriptors ile directory display earch for a string elp information eit to DOS DESCRIBE is a tool to extend your disk directory with a descriptor field for each file. The field is 63 characters in length and is used by you to add information describing each file stored in the directory. DESCRIBE provides commands to manage these descriptors as well as provide you the means to construct customized sorted directory displays to the display screen, your printer, and even a disk file. DESCRIBE also has a command to allow you to invoke a DOS command as if you were at DOS Ready. While the main menu is displayed, a blinking cursor is positioned to the left of a command letter. Commands can be accessed by depressing the letter contained within angle brackets or by moving the cursor via UP/DOWN arrows to the command "word" then depressing . Alter a Descriptor A is used to ALTER or EDIT the descriptor field. When you enter this command, the screen will display a file's name along with the MOD date and attributes. If any descriptor field is present, it will also be displayed. The prompt tells you to use the UP/DOWN/ENTER keys to scroll through each filespec. If you wish to edit a descriptor field, depress the letter "E". The editing keys at your disposal are: CLEAR-LEFT-ARROW Delete the character at the cursor and shrink the line by one position CLEAR-RIGHT-ARROW Expand the line by one character LEFT-ARROW Move the cursor left one position RIGHT-ARROW Move the cursor right one position ENTER Store changes and proceed to next file BREAK Abort changes and proceed to next file If the file's name is prefixed with a question mark, it means that file has been added to the disk since the directory was extended. This "flag" will automatically disappear once you edit the descriptor field. As an aside, once you delete a file from a directory after you have "described" it, the description will not come up during the ALTER- command. Change to a New Drive During the maintenance operations, the directory descriptor extension for a diskette is kept in a memory buffer. The CHANGE command is used to identify the disk drive you want to describe. You must use this command to identify the first disk to operate with. Thereafter, each time you wish to change to a different disk, YOU MUST INVOKE THIS HANGE COMMAND PRIOR TO SWITCHING DISKETTES. That's to give DESCRIBE an opportunity to update the descriptor data and close the directory. The program attempts to ensure that the disk to update is the same as the current one by matching the disk pack identification. This is not failsafe! It is strongly recommended that you assign a unique disk name to each diskette in your collection. Aside from the importance for a program such as DESCRIBE to uniquely identify each diskette from another, catalog programs such as ZCAT need uniquely assigned diskette names. It's a good practice to get into. DOS Command Request This DESCRIBE command allows you to enter any command acceptable at the DOS Ready prompt. Your command will be invoked by the DOS. At its conclusion, a prompt to "Press to continue" will be displayed. After you depress the key, the DESCRIBE menu will re-appear; the descriptor buffer will be intact. File Directory Display This "F" command is used to obtain the directory listing of files. The display is formatted according to the user defined format specification. This specification can be customized via the "M" command. The listing will be titled if the first character of the specification is a plus sign ("+"). The title is constructed with headings appropriate to each data item in the listing (see the "M" command for titling details). A line of dashes completes the title. The listing format for each file is controlled by the sequence of keywords and other characters contained in the format specification. When you invoke the "F" command, the prompt, Output to isplay,

rinter, or ile? will be displayed in the status line. This gives you an opportunity to select the destination device for the listing. Depressing "D" followed by will select the video display screen. This will produce a display paged according to your screen size. Depressing "P" followed by will produce a printer listing. If you select the "File" output, you will be prompted to enter the name of the disk file to which you want the output written. Depressing by itself will also select the video display screen paged listing. A will abort the operation. Help Information This command provides eight screens of text which describe various functions of the DESCRIBE program. The help screens are useful once you become slightly familiar with the DESCRIBE facility by providing you with an abbreviated on-line user manual. Interchange Data This command allows you to load or save the directory data identified by the format specification from/to a data file. The file is structured in the Data Interchange Format (DIF). The load operation will extract the descriptor fields from the DIF file loaded and update the current set of descriptors when the file specification matches. The load operation requires that the following fields are present in the DIF file: $DES and $SPC or $DES and $NAM (or $NAX) and $EXT (or $EXX). An error will be generated if the required fields are not present. The save operation creates a DIF file in column format. A typical use for the generation of a DIF file would be to transfer the contents of the descriptor fields to a backup disk. A non-typical use would be to create a DIF file of directory information and load the data into a spreadsheet program -although it's quite possible. Modify Listing Format The MODIFY command allows you to alter the format specification to customize the file directory display listing. When you invoke "M", the current format will be displayed along with a listing of the keywords supported. This modifies the menu screen with an addition such as the following box. The format specification illustrated is the default format generated by DESCRIBE when a descriptor extension is first created. ATT DAT DES DEX DRV EOF ERN EXT EXX LRL NAM NAX PRO REC VID VNM VDT +$spc $att $pro $lrl $rec $eof $dat;$des;) to save edits, to abort edits The two rows of keywords are displayed as memory joggers. The keys should be quite descriptive for the values they stand for. The Format Table provides the keyword description and the title string generated when a title is requested -Within- the format, each keyword must be prefixed with a dollar sign. If the first character is set to a "+", the listing will include a title. The string must be terminated with a closing parenthesis. If you omit it, a closing parenthesis will automatically be applied when you save the format. The semicolon, ";", can be used to specify a logical carriage return. This should be used if your format contains a line which is going to exceed the screen width. The format string is edited with the same edit functions as the ALTER command. DESCRIBE provides a maximum of 64 characters for the format string. Format Table Key Definition Title String ATT File attributes; "+*SIPC" Attrib DAT Mod date; "dd-mmm-yy" Mod date DES Descriptor field File Description DEX Descriptor field to 63 chars File Description DRV Disk drive; ":d" D_ EOF End-of-file offset; "ddd" Eof ERN Ending record number; "ddddd" _Ern_ EXT File extension Ext EXX File extension to 3 chars Ext LRL Logical record length; "ddd" Lrl NAM File name Filename NAX File name to 8 chars Filename PRO Protection level; "prot" Prot REC Number of records by LRL; "ddddd" Nrec_ SPC File name and extension string to 12 Filespec____ chars VDT Volume date; MM/DD/YY Vol Date VID Volume name and date to 16 chars Disk Pack ID VNM Volume name to 8 chars Vol Name Remove Descriptors The REMOVE command allows you to delete the descriptors from the directory of the currently logged disk. This facility is the only way you can properly restore the directory to its standard size. You will be prompted to continue the removal operation prior to its execution. This is a safeguard so you don't inadvertently delete all of the descriptors that you so painstakingly edited. If you want to remove the descriptors but restore them at a later date, why not first prepare an interchange file with $SPC and $DES data so that the descriptor contents can be saved for the restoral? Search for a String The SEARCH command allows you to invoke a file directory listing which includes all files with a descriptor character string that matches your search string. Your search string can be up to 32 characters in length. The matching is performed without regard to UPPER/lower case (it is case insensitive). By using this command, you can obtain a directory display based on a file's description rather than on just its name.