DDDD SSS K K L IIIII BBBB D D S S K K L I B B D D S K K L I B B D D SSS KK L I BBBB D D S K K L I B B D D S S K K L I B B DDDD SSS K K LLLLL IIIII BBBB DSKLIB (Disk Librarian) V02 January 6, 1982 NOTE: THIS PROGRAM IS SUBMITTED as is TO DECUS. WHILE I WOULD APPRECIATE HEARING ABOUT ANY PROBLEMS OR SUGGESTIONS, I CANNOT PROMISE TO RESPOND. Joel Berez Copyright (C) 1982 Berez Associates 64 Jacqueline Road Waltham, MA 02154 CHAPTER 1 Introduction to DSKLIB 1.1 Purpose of DSKLIB RT-11 includes facilities for creating and maintaining multiple files on a disk device through the use of a direc- tory. A utility is also provided for listing subsets of the directory in various formats. This utility (PIP or DIR) makes it easy to find a particular file as long as the file is currently on-line. In installations using low-capacity disks, however, there tend to be many more disks than drives. At any given time, most files will be off-line and inaccessible to the RT-11 directory programs. Finding a file may require exa- mining titles written on disks for a likely category, searching through previously printed directory listings, or mounting disks successively until the right one is found. It is of course correspondingly more difficult to find all copies of a particular file, all files of a given type, or even a good place to put a new file. The problem is com- pounded on systems using floppy disks or on development sys- tems, which both generally have large numbers of off-line disks. This is also true of systems using archives (pseudo-devices), which can have a large number of directo- ries that need to be searched, even though they may all be "on-line" at once. DSKLIB solves these problems by maintaining a single, compact directory of files from many disks. This master di- rectory may be kept on-line for easy searching and updating. Whenever files are added or removed from a disk, the master directory may be quickly updated. DSKLIB provides commands for utilizing this information to find files on any catal- oged disk. Introduction to DSKLIB PAGE 1-2 1.2 Configuration Supported 1.2.1 Software DSKLIB is intended to run under any of a family of sim- ilar monitors: RT-11, CTS-300, and HT-11. Specifically, DSKLIB has been tested and should properly operate under the following groups of monitors. In this document, "RT-11 V2" will be used to refer to RT-11 V2C, CTS-300 V3.5, or HT-11 V1. "RT-11 V3" will refer to RT-11 V03, RT-11 V3B, CTS-300 V4, or CTS-300 V5. "RT-11 V4" will refer to RT-11 V04.00 or CTS-300 V6. Although DSKLIB may also operate under other versions of these monitors or under other similar monitors, there is no guarantee that it will behave exactly as des- cribed herein. DSKLIB will also run with TSX under any of the above mentioned monitors that is also supported by TSX. However, due to certain peculiarities of TSX, the terminal handling characteristics of DSKLIB may not be identical under a given monitor with and without TSX. This document describes DSKLIB without TSX, but is generally also applicable to a TSX environment. DSKLIB will run in the background under any monitor. In addition, it may be run in the foreground under any of the RT-11 V3 or V4 monitors. 1.2.2 Hardware Since no special instructions are used, except option- ally EIS, all PDP-11 processors are supported. EIS hardware, if present, may be used to improve performance. DSKLIB will run comfortably in 8K words of memory, not counting the monitor. More memory may be dynamically used, if available, but is generally not necessary. At least two disk drives are necessary for DSKLIB to be useful. Up to 10 drives are supported, which may be of any type handled by the monitor, and need not all be of the same type. Any type of terminal may be used, and DSKLIB distin- guishes between printing and display terminals when char- acters are deleted. Most output can also be directed to a Introduction to DSKLIB PAGE 1-3 printer. 1.3 Terminology 1. DRIVE Digit (0 to 9) identifying one of the predefined disk drives or an explicitly entered device or ar- chive name. May be any device that is RT-11 direc- tory structured, including DECTAPE. 2. ARCHIVE A file that may be accessed by the archive handler as a pseudo-device (see Section 1.4.3). 3. DISK The medium mounted on a drive. Also refers to the information stored in the catalog about a particu- lar disk, identified by the disk number. 4. VOLUME Used synonymously with DISK. 5. DIRECTORY The area on a disk from which DSKLIB extracts file information. Also, a listing of all disks current- ly cataloged. 6. ENTRY The block of information in a disk directory or a DSKLIB catalog identifying an RT-11 file or volume and various characteristics. 7. FILE Either an RT-11 file or an entry in the DSKLIB ca- talog. 8. CATALOG An RT-11 file created and used by DSKLIB to contain information about a set of disks and their files. 9. PRIMARY CATALOG The default catalog used by most DSKLIB commands. 10. SECONDARY CATALOG Another catalog that may be open at the same time as the primary. Some commands optionally use it, but its main purpose is for the MOVE command, which requires two catalogs. 11. VOLUME ID Introduction to DSKLIB PAGE 1-4 The twelve character identifier stored in the disk's header block by DSKLIB or DUP. DSKLIB de- codes it into disk number and name. Special file entries in the catalog contain volume information. 12. DISPLAY TERMINAL A terminal that supports a backspace-space-backspace combination to erase a character. 13. PRINTING TERMINAL Any terminal not fitting the display terminal de- finition. 14. PRINT COLUMNS The number of columns across a line in which file entries will be printed. 1.4 Installation 1.4.1 Generating and Customizing DSKLIB The distribution disk contains all files necessary for installation of DSKLIB for any of the RT-11 monitors sup- ported. The same version of DSKLIB will run under any moni- tor, but it may not be linked under RT-11 V2. Therefore, the following instructions, which allow more flexibility under RT-11 V3 or V4, refer to the monitor under which DSKLIB is generated, and not to the one under which it will ultimately be run. 1.4.1.1 RT-11 V3 and V4 - DLBOPT.MAC contains the options that may be set to cus- tomize DSKLIB. This file should be edited as desired. The following options exist: 1. DEVTAB Ten RAD50 words containing the device names of the drives known to DSKLIB, referenced in the program by digits 0-9. Physical names are recommended al- though logical names will also work. Introduction to DSKLIB PAGE 1-5 2. DPBLKS The number of blocks, one to four, that will be used in each catalog for pointers for disks catal- oged. Disks need not be numbered continuously from zero, but the highest number that may be used is equal to DPBLKS*256-3. Note that this option af- fects the generation of a catalog, which requires catalogs to be used only with a DSKLIB having the same DPBLKS specification. 3. PROMPT The character used at the top level of DSKLIB to prompt for a command. This might be changed to avoid confusion with another program using the same prompt character. 4. CATNAM The name of the catalog file that will be automati- cally opened when DSKLIB is first started. 5. PRTNAM The default file name that will be opened when out- put is directed to the printer. May be either a sequential or a file-structured device. 6. DEFORD File entries found in a catalog search are usually sorted before printing. The default order of the five sort keys, from major to minor, may be speci- fied here. When a particular key is selected by a user option, the other four will still follow the order given here. 7. TRMTYP When DSKLIB is first started, if it is unable to determine the terminal type, it will use the de- fault specified here. 8. TT0COL The default number of print columns for a type 0 (printing) terminal. 9. TT1COL The default number of print columns for a type 1 (display) terminal. 10. PRTCOL The default number of print columns for the printer. 11. PRTLNS The default number of lines per page for the printer. Specify zero here to disable paged mode. Introduction to DSKLIB PAGE 1-6 12. OWNER A twelve character ASCII string used to initialize a volume's owner field. After DLBOPT.MAC is edited, it should be assembled as follows (assuming all DSKLIB files are on the default dev- ice): .MACRO DLBOPT The correct version of DSKLIB must be selected for the hardware to be used. If EIS support is desired: .RENAME DSKLIB.EOB DSKLIB.OBJ If EIS hardware is not present, or is not to be used: .RENAME DSKLIB.NOB DSKLIB.OBJ Then DSKLIB must be linked using: .LINK DLBOPT,DSKLIB/EXE The result will be the utility program, DSKLIB.SAV, which will run in the background. It is also possible to link DSKLIB for foreground oper- ation: .LINK DLBOPT,DSKLIB/EXE/FORE To run DSKLIB in the foreground, it will be necessary to al- locate workspace: .FRUN DSKLIB/N:n The number n must be at least (DPBLKS+4)*1000 octal. Extra space may be allocated for large searches in multiples of 1000. 1.4.1.2 RT-11 V2 - Since DSKLIB may not be linked under RT-11 V2, two linked versions are provided, one with EIS support and one without it. To select EIS support: .R PIP *DSKLIB.SAV=DSKLIB.ESV/R *^C Introduction to DSKLIB PAGE 1-7 If EIS hardware is not present, or is not to be used: .R PIP *DSKLIB.SAV=DSKLIB.NSV/R *^C DSKLIB.SAV is now ready to use, with the options preset as shown in the distributed DLBOPT.MAC file. However, if desired, options 1, 4, 5, and 12 may be changed using PATCH: .R PATCH FILE NAME-- *DSKLIB *(loc)/ (old value) (new value) *E The following locations may be examined and/or modi- fied. Unless otherwise specified, all locations are RAD50. 1000/ (device name for drive 0) 1002/ (device name for drive 1) ... 1022/ (device name for drive 9) 1024/ (default catalog device) 1026/ (first half of default catalog name) 1030/ (last half of default catalog name) 1032/ (default catalog type) 1034/ (default printer device) 1036/ (first half of default printer file name) 1040/ (last half of default printer file name) 1042/ (default printer file type) 1044/ (first two characters of owner name in ASCII) 1046/ (third and fourth characters) ... 1056/ (eleventh and twelveth characters) 1.4.2 Auxiliary Programs Two small programs are included with DSKLIB in both .SAV and source form. These utilize a feature in DSKLIB that allows programs to chain to it and pass commands. UA causes DSKLIB to do an Update with the All option. It is useful for quickly updating the cataloged information for all disks currently on-line. DLBCOM takes a command line and passes the text to Introduction to DSKLIB PAGE 1-8 DSKLIB. It is intended for calling DSKLIB from command files (not available under RT-11 V2). The line may end with a "Q" to exit from DSKLIB and continue the command file. If DSKLIB runs out of text before exiting or if some error oc- curs, it will begin accepting input from the terminal. Both of these programs expect DSKLIB to be found as SY:DSKLIB.SAV. They may be reassembled to use a different name, if necessary. UA might also be changed to pass a dif- ferent line of text. 1.4.3 Archive Handler Also included with DSKLIB are files used to maintain archives: the archive handler, an archive definition pro- gram, and documentation describing their use. Archives are pseudo-devices which may be created as files on larger dev- ices and used to conveniently partition and organize files. They can be extremely useful by themselves and work particularly well when used in conjunction with DSKLIB. However, since the archive handler, which runs only under RT-11 V4, must perform certain operations that are beyond normal RT-11 support, it is not supported by Berez Associ- ates and must be used at your own risk. CHAPTER 2 DSKLIB Operation 2.1 Initialization The first thing required to use DSKLIB is the creation of a catalog, preferably the default catalog. If at all possible, the default catalog should reside, along with the DSKLIB program, on a permanently mounted disk, probably the system disk. All disks that are part of normal operations should be cataloged here. Where there are logically two or more groups of disks that are not normally used together, it may be desirable to have one catalog for each group. A group might consist, for example, of all disks owned by a particular department, per- son, or project; all MUBASIC-related disks; or a set of backup disks. In such cases, there is often a system disk for each group. The group catalog would then reside there. The Create command in DSKLIB is used to create a cata- log file. Each disk to be cataloged there must be given a suitable volume id containing a volume name and a unique (for that catalog) number. The Volume ID Change command may be used. Alternatively, DUP (INIT/VOL:ONLY) may be used. In the latter case, the format required is ###nnnnnnttt, where ### is the zero-filled disk number, nnnnnn is the vo- lume name, and ttt is the volume type. Once the disks are given numbers and names, they may all be cataloged using the Update command. This completes the initialization procedure. DSKLIB Operation PAGE 2-2 2.2 Catalog Maintenance Keeping the DSKLIB catalog up to date simply requires using the Update command for each disk whose directory has changed (files added, deleted, or replaced) since last ca- taloged. There are three commonly used methods for ensuring that the catalog remains current. Any of these, or some variation, may be used, depending upon individual require- ments. Each modified disk may be cataloged just before being dismounted. The disks remaining on-line could be cataloged, possibly using the All and/or Rchive options of Update (or the UA program), at the end of each day or work session. Alternatively, all disks used during some time period may be kept together. Then they could be cataloged in a batch before returning them to the main library. A third technique, where completely up to date informa- tion is not essential, is to simply recatalog all disks on a periodic basis or whenever appropriate. Occasionally it may be necessary to change the size of the catalog. If the catalog becomes full, an error message will be displayed. The catalog could also be needlessly large after a number of disks are Expunged. The Size com- mand may be used at any time to determine current catalog size and percentage utilization. The catalog may be expanded by extending the file with DUP (RT-11 V3 or V4) or PIP (RT-11 V2). It may be expanded or contracted in DSKLIB by creating a new catalog of the de- sired size and using Move with the All option to transfer the information from the old one to the new one. 2.3 Normal Usage Using DSKLIB to find files is quite easy. When the program is first started, it does a number of things auto- matically. Under RT-11 with multi-terminal support (not available under RT-11 V2), DSKLIB will determine the type of terminal in use from the monitor. It will also get the ter- minal width. In the absence of multi-terminal support, the defaults specified at DSKLIB generation time will be used. At this time DSKLIB will attempt to open the default catalog. If that catalog is not found, a message will be displayed. DSKLIB Operation PAGE 2-3 Once the program initialization is completed, DSKLIB will display the command prompt character and wait for a command. Commands are invoked by typing a single character. A question mark (?) may be typed to get a list of all com- mands. The Help command may be used for a concise descrip- tion of a command and its arguments. Anytime input is requested, a ^C may be typed to return to the command level. This is especially useful for exiting from a command inadvertantly entered. (Under RT-11 V2 it will also be necessary to REENTER DSKLIB.) During long com- mands, two ^Cs will cause a return to command level. (Under RT-11 V2, this must be followed by REENTER.) A few commands may be particularly useful when DSKLIB is first started. If the default catalog was not found or if a different one is desired, the Open Catalog command may be used to open the proper catalog file. The Terminal Type command may be used to change the current terminal type. The Width of Terminal command may be used to change the number of columns that will be used for printout. (This number may be overridden by a Find option.) The Printer File command may be used at any time to change the destination for printer output. The most powerful command and the one that will be most frequently used is Find. The Find command searches the ca- talog for files matching the given specification and prints those file entries in a specified format. Besides finding existing files or volumes, Find may also be used to find su- itable places to put files, or just to count files and total sizes. Although entries may be grouped in various numbers of columns and rows per page, the entries themselves are always printed in a standard format. For example: 35 LIBCAT.DLB 100 17-May-79 A file named LIBCAT.DLB (probably a catalog) exists on disk number 35. It is 100 blocks long and was created on May 17, 1979. If the file had been protected (under RT-11 V4), the entry would have been followed by a "P". A volume id entry looks like a file entry but is inter- preted differently. If the above example were a volume entry, it would represent disk number 35, named LIBCAT.DLB. The disk would have 100 free blocks remaining, and an Update would last have been done for it on May 17, 1979. The Directory and List commands are special forms of the Find command that find particular entries. DSKLIB Operation PAGE 2-4 Finally, the Quit command is used to exit neatly from DSKLIB. If a new catalog was created and is still open, the Abort command may be used to exit without making the file permanent. DSKLIB may be restarted after a Quit or an Abort using KMON's REENTER command. The last opened primary cata- log will be reopened and the terminal characteristics will remain unchanged. (Note that a ^C under RT-11 V2 acts like the Abort command, unless it is followed by the KMON CLOSE command. In the latter case, it is equivalent to the Quit command.) CHAPTER 3 DSKLIB Commands Each command will be described in the following sec- tions. The command format is shown first and then a deta- iled description is given. In the command format, text enclosed in angle brackets is typed by the user. Everything else is displayed by DSKLIB. Within the angle brackets, uppercase text is typed exactly as shown. Lowercase words represent parameters en- tered: 1. A positive integer, preceded by a number sign (#) or an equal sign (=) prompt, terminated by a car- riage return. 2. Standard RT-11 format file name (dev:name.typ), preceded by a "named:" prompt, terminated by a car- riage return (after any switches). A may be followed by one or more es. Note: the Find command has a special format. 3. An option name, which may be abbreviated to two or more characters. A slash (/) must be typed preced- ing the switch. Any may be followed by es. /HELP will always list the ones al- lowed for that command. 4. The first character of a command name, preceded by the command prompt (colon, unless changed by the generation option). 5. A number between zero and nine following a number sign (#) prompt. DSKLIB Commands PAGE 3-2 A colon following an argument in angle brackets shows the default value if no text is typed preceding the carriage return. A vertical bar represents a choice between two op- tions. Square brackets enclose optional arguments. 3.1 Abort :bort Are you sure? es|o Exits from DSKLIB like the Quit command. However, if a new catalog file had been created and not yet closed, that file will be purged. If it had the same name as another file, the original file will not be deleted. 3.2 Create Catalog :reate catalog named: ; size= Overwrite existing catalog? es|o Creates a new catalog file with the specified name and Opens it. Any RT-11 directory structured device may be used. The default file type is DLB. 3.2.1 Arguments The size given is the number of blocks in the new file and must be between DPBLKS+2 and 512, inclusive. On the average, the number of blocks required in a catalog file for F files on V volumes is [(F+V)/6+V/2]/8+DPBLKS+1. Extra blocks should also be allocated for expansion. The "overwrite existing catalog" message will be given if the new catalog replaces a file with the same name. A No response will abort the operation. A Yes will continue, but the old file will not actually be replaced until the new file is closed either by a Quit or an Open/Create for the same catalog type (primary or secondary). Whether the new catalog is overwriting an existing one or not, until the file is closed, the Create may be undone by the Abort command. DSKLIB Commands PAGE 3-3 3.2.2 Switches /SECONDARY catalog Opens the new file as the secondary catalog. This would be used when creating a new catalog to Move disks to. /HELP Lists switches allowed. 3.3 Directory of Disks :irectory of disks Displays the volume entries of all disks in the primary catalog, sorted by disk number. This is equivalent to ":Find file named: /VOLUME/DISK" except that the sorting is slightly different and it may be faster. 3.4 Expunge Disk :xpunge disk # Removes all of the entries associated with the speci- fied disk from the primary catalog. This might be done if a disk is being removed from the library, if the number has been changed, or if the disk has been Moved to another cata- log. 3.5 Find File :ind file named: [...] Finds files (entries) in the catalog and lists them on either the terminal or printer. The number of files found and their total sizes are displayed on the terminal at the end of the listing. DSKLIB Commands PAGE 3-4 3.5.1 File Name Format The file name format allowed is an extension of the format used by the file utilities (PIP, DIR) of RT-11 V3 and V4, which is itself an extension of the format used by RT-11 V2. The format is name.type, where "name" contains zero to six characters and "type" contains zero to three characters. The dot is required only if a type is given. The characters may be any allowed in a file name (A to Z, 0 to 9) and the special characters, asterisk (*) and per- cent (%). A percent will match any single character (in- cluding a space) in a file name. An asterisk will match any series of zero or more characters. Any arbitrarily hairy combination of these characters is allowed, as long as the length restrictions are not exceeded. For example: LIBCAT.DLB Finds files named LIBCAT.DLB. FILE%.DAT Matches names such as FILE1.DAT, FILED.DAT, or FILE.DAT. *.SAV .SAV *%*%*%.SAV These are all equivalent and will find all files whose type is SAV. (A missing name or type is equivalent to an aster- isk.) *A%B*.*C* Finds all files with an A and a B somewhere in the name, separated by one character, and a C anywhere in the type. 3.5.2 Find Switches Although a file name may always be followed by a switch, the switch is specifically shown in the Find command format to emphasize its importance. One or more switches are frequently used with Find to control the entry selection criteria and the output format. DSKLIB Commands PAGE 3-5 3.5.2.1 Switch Arguments - A number of switches for the Find command require an argument. Each switch requiring an argument must be fol- lowed by a single space before the argument, even if the ar- gument is not entered, but completely defaulted. The type of argument is specified in parentheses in the switch des- cription: 1. (number) A nonnegative decimal integer. If not entered, de- faults to zero. 2. (date) This is a superset of the standard RT-11 format date (dd-mmm-yy). This date is generalized to allow the three parts (day, month, and year) to be entered in any order prefered, as long as they are separated by dashes. Furthermore, any or all parts may be omitted and will default according to the following algorithm. Consider the date components ordered from lowest to highest importance (day, month, year). Unless all lower order components are missing, any missing component will default to the corresponding compo- nent of the current date. If all lower order com- ponents are missing, a component that is present will refer to all dates within that component. For example, if only "May" is specified, all days in May of this year will be used. Also, a completely missing date defaults to today's date. 3.5.2.2 Switches - /NAME sort Sorts entries by file name. This is the default, unless modified by the generation option. /TYPE sort Sorts entries by file type. /DATE sort Sorts entries by file date. /FILESIZE sort Sorts entries by file size. /DISK number sort Sorts entries by disk number. DSKLIB Commands PAGE 3-6 /REVERSE sort Sorts entries in reverse order. /VOLUME id entries Finds volume id entries instead of file entries. /LESS than (number) Only selects entries whose sizes are less than (number). May be used with /GREATER to select a range of sizes. /EQUAL to (number) Only selects entries whose sizes are equal to (number). /GREATER than (number) Only selects entries whose sizes are greater than (number). May be used with /LESS to select a range of sizes. /BEFORE (date) Only selects entries whose dates are earlier than (date). May be used with /SINCE or /DURING to se- lect a range of dates. /DURING (date) Only selects entries whose dates are equal to (date). Remember that (date) may specify an en- tire month or year. May be used with /BEFORE or /SINCE to select a range of dates. /SINCE (date) Only selects entries whose dates are later than or equal to (date). May be used with /BEFORE or /DURING to select a range of dates. /ONLY disk (number) Selects entries from the specified disk only. This more-or-less allows the functions of the DIR program (PIP, for RT-11 V2) to be duplicated with- out the need for the disk to be on-line. /PRINTER Sends output to the printer instead of the termi- nal. The output will automatically be formatted into pages. /LINES per page (number) If /PRINTER is also used, overrides default page length. Furthermore, if (number) is zero, paged mode will be disabled. Otherwise, forces paged mode for the terminal using the specified page length. (number) should not include lines skipped DSKLIB Commands PAGE 3-7 by the form-feed at the end of each page. /COLUMNS per line (number) Overrides line width default for terminal or printer. /QUIET Finds entries, but only displays totals. This is faster than typing a ^O to see just the totals. /SECONDARY catalog Finds entries from the secondary catalog, instead of the primary. /HELP Lists switches allowed. 3.5.2.3 Switch Examples - /DURING 77 Finds all files created during 1977. STOCK/DUR 77/SINCE JUL-77 Finds files named "STOCK" (any type) created during the last six months of 1977. /VOL/EQ 480 Assuming all disks are RX01 floppies, this will find all completely empty disks. /QUIET Shows total number of files and blocks used. /VO/QU Shows total number of disks cataloged and total number of free blocks available. TELNET.MAC/DATE/REV Used to find most recent version of specified file. .BAS/SINCE APR/GR 50 Might be used to find some BASIC program if the name has been forgotten, but it is known that the file is more than 50 blocks large and was created no earlier than April of DSKLIB Commands PAGE 3-8 this year. .SAV/PR List all SAV files on the printer. 3.6 Help :elp for command: Displays a brief description of the specified command along with the command and argument format, as shown here. 3.7 List Disk :ist disk # Lists cataloged entries for a disk. First the volume id entry is shown. Then the file entries are displayed, sorted according to the default sequence. This command is basically equivalent to "Find file named: /VOLUME/ONLY " followed by "Find file named: /ONLY ." 3.8 Move Disk :ove disk # For this command to operate, a catalog must have been previously Opened or Created with the /SECONDARY switch. (As for most commands, it is assumed that a primary catalog is open.) All entries for the specified disk will be copied from the primary catalog to the secondary. The entries moved will not be deleted from the primary catalog. If that is desired, Expunge should be used after Move. Typing a carriage return without a disk number will se- lect the All option. All disks in the primary catalog will be individually moved to the secondary. This option is use- ful for expanding or contracting a catalog. A new catalog should be created (with /SECONDARY) of the desired size and then all disks are Moved to it with this option. DSKLIB Commands PAGE 3-9 3.9 Open Catalog :pen catalog named: Opens an existing catalog as either the primary or sec- ondary. Closes any previously open catalog of the same type (primary or secondary). A previously Created catalog would become permanent at this point. 3.9.1 Switches /SECONDARY catalog Opens the new file as the secondary catalog. This would be used to Move disks to. /HELP Lists switches allowed. 3.10 Printer File :

rinter file named: Redirects printer output from the default file (or last one given with this command) to the new one. may be on a sequential or a file-structured device. In the latter case, each time Find is used with the Printer option, the file will be reopened and any previous file will be lost. 3.11 Quit :uit Exits from DSKLIB after closing any open catalogs. Closing a newly created catalog makes the file permanent and deletes any older file with the same name. If that is not desirable, use the Abort command. DSKLIB Commands PAGE 3-10 3.12 Size of Catalog :ize of catalog ... Lists information about the primary catalog, including its name, size in blocks, and percentage utilization. Note that a newly created catalog will be more than 0% full be- cause of the blocks used for header information (DPBLKS+1). The space used in a catalog is not necessarily contigu- ous. This has the effect that although a catalog may be ex- panded by extending the file, it may not be contracted by truncating blocks from the end, even though it may be only partially full. 3.13 Terminal Type :erminal type is printing|display Changes the terminal type and shows the new one. Since there are only two types, this command simply toggles to the other one each time it is used. It also sets the number of print columns to the default assciated with this terminal type (a generation option). DSKLIB handles the two terminal types differently only when characters typed are deleted. On a printing terminal, the deleted character is echoed. On a display terminal, it is erased. Typing a ^U is always equivalent to individually deleting all previously typed characters. 3.14 Update :pdate from drive #|ll|ile|chives Copies directory information from the specified drive into the primary catalog. The digit identifies a predefined disk drive. Typing an "A" instead of a digit invokes the All option, which does an Update for every drive in DSKLIB's list. The File option will give the standard "named:" prompt and may be used to specify either a device name or a com- plete file name. The former is used for specifying devices that were not predefined to DSKLIB. The latter may be used DSKLIB Commands PAGE 3-11 for archive files or for images of small devices that have been backed-up to a larger device (using COPY/DEVICE/FILES under RT-11 V4). The Rchives option does an Update for all archives cur- rently defined to the archive handler. It is also a nice way of simply determining which archives are defined. 3.15 Volume ID Change :olume id change for drive #|ile from #nnn; named: ffffff.ttt; owner: xxxxxxxxxxxx to #; named: Displays volume number, name, and owner for the disk on the specified drive and allows them to be changed. As with the Update command, a file name (or device) may be given instead of a drive number. "nnn" is the current volume number, "ffffff.ttt" is the volume name (in standard file name format), and the x's are the contents of the owner field. For convenience, if a new number is not entered, it will default to the old one, so that only the volume name will be changed. 3.15.1 Switches /OWNER field set Sets the volume owner field to the text specified during DSKLIB generation. This might be used the first time the volume name and number are set. /RT11A format Initializes volume header block in the format used by RT-11 V3 and V4. This can be done to V2-format disks to avoid the warning message that DSKLIB would otherwise display whenever the volume id was changed. /HELP Lists switches allowed. DSKLIB Commands PAGE 3-12 3.16 Width of Terminal :idth of terminal (in columns) # Changes the default number of columns for file name printing. This number is only relevant for the terminal. The default for the printer may only be set at DSKLIB gener- ation time. Either default may be overridden for the Find command through a switch. CHAPTER 4 DSKLIB Messages The messages displayed by DSKLIB in standard RT-11 for- mat indicate various operational problems. Generally the cause is clear and the solution is straightforward. Sometimes, however, the problem will not be obvious. Many of these messages can be caused by hardware errors or RT-11 bugs. If these are suspected, the standard tests should be run, including rebooting the system, running hardware diagnostics, etc. If the cause of the problem cannot be readily traced, and programs other than DSKLIB are not failing, there may be reason to suspect a DSKLIB bug. In this case, a description of the problem should be sent to Berez Associates, 64 Jac- queline Road, Waltham, MA 02154. A printed copy of DLBOPT.MAC as modified should be included. The version of DSKLIB in use should be specified, which can be obtained by running DSKLIB and typing a carriage return to its command prompt. It is desirable, particularly if the bug is catalog-related, to include a machine-readable copy of DSKLIB and the catalog in use, preferably on a floppy disk. 4.1 Informational Messages These messages do not require any particular action by the user, but are informative only. 4.1.1 Message Descriptions ?DSKLIB-I-Cannot attach console terminal Although an RT-11 monitor with multi-terminal support is being used, DSKLIB could not attach the console ter- DSKLIB Messages PAGE 4-2 minal to get its characteristics. It is in use by another job. DSKLIB will use its standard terminal de- faults. ?DSKLIB-I-Insufficient memory for all file entries There was not enough memory to hold all entries found by the Find command. (Each entry requires 6 words.) All entries found so far will be sorted and printed, and then the search will continue. See Section 4.3.2 for further details. ?DSKLIB-I-No disk mounted The Update command accessed a drive that had no disk mounted. For Update All, the drive will be skipped and the Updates will continue. ?DSKLIB-I-Skipping bad chain This message from the Move command indicates that bad data have been found in the catalog for the current disk. Although this disk cannot be moved, a Move All will continue with subsequent disks. For this reason, Move All is useful for recovering as much information as possible from a damaged catalog. 4.2 Warning Messages These messages warn of some adverse condition that has not yet caused a problem but may later if the condition is not corrected. 4.2.1 Message Descriptions ?DSKLIB-W-Disk not RT11A initialized This message from the Volume id change command warns that the target disk has not been initialized in the format used by RT-11 V3 and V4. If the command is al- lowed to continue, important information may be des- troyed. Unless the disk has been initialized by an RT-11 V2 monitor, which makes it downward compatible with the new format, the command should be aborted by typing ^C. Normally a V2-format disk should be com- pletely upgraded to the new format using the /RT11A switch. ?DSKLIB-W-No date set The system date has not been set. This date is used by Update and by the date switches of Find. Particularly DSKLIB Messages PAGE 4-3 if an Update will be done, Quit should be used to exit to KMON, the date should be set with the DATE command, and DSKLIB may be REENTERed. 4.3 Error Messages These messages describe fatal errors. Generally the particular command in use is aborted and control returns to DSKLIB command level. 4.3.1 Read/Write Failures A number of errors are caused by read or write failures from or to a disk. Such an error might be an indication of a hardware problem or an RT-11 software problem. It might also be simply that the disk is not properly mounted. A read failure might be caused by a bad block on the disk. A badly formatted disk could cause either a read or a write failure. A write failure could be caused by a write-protected disk or drive. If a DSKLIB bug is suspected, it should be reported to Berez Associates (see above). 4.3.2 Insufficient Memory A number of messages indicate the unavailability of sufficient main memory (or "core") to complete the command. The available memory depends upon the physical memory con- figured in the hardware and the amount used by the software. To free enough memory for a command, examine the cur- rent software configuration. Significant amounts of memory are used by setting the USR NOSWAP, by having a second job in the FB monitor, by using the FB monitor instead of SJ, and by LOADing device handlers. In DSKLIB, setting DPBLKS to 4, compared to 1, will use 3 more blocks of memory (and 3 more blocks in each catalog file). Accessing devices with non-resident handlers re- quires DSKLIB to load the handlers into dynamically acquired memory. DSKLIB Messages PAGE 4-4 4.3.3 Message Descriptions ?DSKLIB-F-Archive handler not available The Update Rchives command cannot be executed because either the system does not include an archive handler (AR:) or the handler has not been initialized. ?DSKLIB-F-Bad catalog The file Opened is not recognized as a DSKLIB catalog. Possibly it is a catalog created by an incompatible version of DSKLIB. ?DSKLIB-F-Bad date An improperly formatted date argument was given to a switch that required a date. ?DSKLIB-F-Bad device name The specified physical or logical device name is not recognized by RT-11. This may also come from a bad specification for one of the default file names. ?DSKLIB-F-Bad disk chain Bad data have been found in the catalog for the current disk. This indicates that some damage has occurred to the catalog file, which should normally never happen. To recover as much data as possible, a new catalog should be Created and a Move All from the old catalog should be done. If this problem then recurs and cannot be traced to hardware or system software failure, a bug report should be sent to Berez Associates (see above). ?DSKLIB-F-Bad disk number An Update could not be done because the mounted disk contained a bad disk number. After ensuring that the correct disk is mounted, Volume ID Change can be used to set the number. ?DSKLIB-F-Bad file name An improperly formatted file name was either typed or found on a disk by Update. In the case of the Update command, after ensuring that the correct disk is mount- ed, Volume ID Change can be used to set the volume name. ?DSKLIB-F-Bad number An improperly formatted number was typed. ?DSKLIB-F-Bad number of columns Entries can be printed in one to nine columns, inclu- sive. Any other number specified is illegal. DSKLIB Messages PAGE 4-5 ?DSKLIB-F-Catalog full There is not enough space left in the catalog to per- form the current operation. The catalog may be expand- ed as described in Section 2.2. ?DSKLIB-F-Catalog not found The specified catalog file was not found. This message can either come from the Open command or from the auto- matic Open when DSKLIB is started. ?DSKLIB-F-Catalog not open After certain errors, the primary catalog may be closed. This message for the secondary catalog may also indicate that a secondary catalog was never opened. The appropriate catalog should be Opened. ?DSKLIB-F-Catalog write failure An error occurred while trying to write data into the catalog file. See Section 4.3.1 for further details. ?DSKLIB-F-Device handler not found This indicates an RT-11 system failure. A good file name was specified, but RT-11 could not load the handler. ?DSKLIB-F-Disk directory read failure The Update command could not read the directory of the disk on the specified drive. See Section 4.3.1 for further details. ?DSKLIB-F-Disk number too high The specified disk number is higher than the highest disk number allowed for this version of DSKLIB. See the DPBLKS option in Section 1.4.1.1. ?DSKLIB-F-Disk read failure Some unspecified read failure occurred. See Section 4.3.1 for further details. ?DSKLIB-F-Disk write failure Some unspecified write failure occurred. See Section 4.3.1 for further details. ?DSKLIB-F-Drive access failure The Update command could not open a channel to the specified drive. This might indicate that the drive, as defined in DEVTAB at DSKLIB generation time, does not exist. It also might mean that the handler for this device is not installed in the current monitor. ?DSKLIB-F-File name missing A device name was given without a file name for a di- rectory structured device. DSKLIB Messages PAGE 4-6 ?DSKLIB-F-Illegal switch A switch was used that is not defined for this command. The /HELP switch lists all legal switches, if any. ?DSKLIB-F-Insufficient free core for move The Move command requires enough main memory to hold all entries for each disk that it moves (approximately 48 entries per block of memory). See Section 4.3.2 for further details. ?DSKLIB-F-Missing date argument No date was supplied to a switch that required one. To default the date to the current date, follow the switch by a single space. ?DSKLIB-F-Missing numeric argument No number was supplied to a switch that required one. To default the number to zero, follow the switch by a single space. ?DSKLIB-F-Nonexistent disk The specified disk is not defined in the catalog. Either it was never cataloged or it has been Expunged. ?DSKLIB-F-Not enough memory available When DSKLIB is started, it tries to obtain memory for buffer space (DPBLKS+4 blocks). If the memory is not available, DSKLIB cannot be executed and will return to KMON. See Section 4.3.2 for further details. ?DSKLIB-F-Not enough memory for device handler Not enough memory is available to load a required non-resident device handler. See Section 4.3.2 for further details. ?DSKLIB-F-Not enough room for file A catalog file could not be Created with the specified size due to lack of space on the disk. In may only be necessary to squeeze the disk to get enough contiguous space for the file. ?DSKLIB-F-Number too high A disk number larger than 999 was given to the Volume ID Change command. There is only room for three digits in the volume id format for DSKLIB. ?DSKLIB-F-Printer file open failure The printer file could not be opened. Check the name specified at generation time or with Printer File and ensure that this device is available for use. ?DSKLIB-F-Printer file write failure Output to the printer file failed. DSKLIB Messages PAGE 4-7 ?DSKLIB-F-Size too large for bit map For the Create command, the file size specified is larger than the maximum number of blocks that can be utilized by DSKLIB (currently, 512 blocks). ?DSKLIB-F-Size too small For the Create command, the file size specified is smaller than the minimum required, which is DPBLKS+2 blocks. ?DSKLIB-F-Undefined drive number No device name was given in DEVTAB at generation time for this drive number.