Google
 

Trailing-Edge - PDP-10 Archives - QT020_T20_4.1_6.1_SWSKIT_851021 - swskit-tools/ds.mem
There are 6 other files named ds.mem in the archive. Click here to see a list.


                          USING THE DS PROGRAM




     This document discusses version 4 of the DS program.

     The program DS  (Disk  Stuff)  is  a  utility  program  to  provide
information  about  TOPS-20 disks, both as structures, and as individual
units or packs.   As  such  it  can  be  a  big  aid  in  any  attempted
reconstruction  of a trashed pack, or recovery of damaged files.  In its
current incarnation, this program does not do any writing to  the  units
about  which  it  gathers  information,  which  means  that  the  actual
bit-flipping for any repairs must be  done  via  other  means,  such  as
FILDDT.   This also means that there should be no fear of running DS and
accidentally making things worse or trashing yet another disk.

     To provide much of its information, the DS program requires special
process  capabilities.   The  program  will  enable  these  itself.  The
program is oriented to the level of the user  who  possesses  sufficient
understanding  to  interpret the information provided, and possibly take
corrective action.

     DS does not make the attempt to be all-inclusive.  Other  available
programs  such  as  CHECKD, FILDDT, DIRTST, and DIRPNT provide functions
which DS does not  attempt  to  duplicate,  at  least  currently.   Some
reference to these programs will be made later on in this document.



1.0  THE INFORMATION COMMAND

     This command produces yet another variant of the UNITS display  for
the  disk  drives  available to the system.  The standard channel, unit,
controller, alias, structure ID, logical pack number,  drive  type,  and
drive  status are provided.  The major purpose is to provide the channel
and unit numbers of a pack for physical unit addressing, but display may
provide  some  useful  information  on  a suspicious pack.  The possible
values in the Status column are:

     Off-line - unit is off-line currently.

     Mounted - unit is part of a mounted structure.

     Diagnostic - unit is allegedly being used by an on-line diagnostic.

     Errors - unit has an error that was detected during reading.

     BadBAT - unit has a bad BAT block.  Other information may be wrong.

     BadHOM - unit has a bad HOME block.

     Write-locked - unit is write-locked.
USING THE DS PROGRAM                                              Page 2


1.1  EXAMPLE:

@DS
DS Disk Utility Program %4(142)

DS>? one of the following:
 CHECK         COPY           DEFINE         DIRECTORY      DRIVE
 DUMP          EXIT           FILDDT         HELP           INFORMATION
 OUTPUT        PUSH           SEARCH         STRUCTURE      TAKE
 VERIFY        WATCH
DS>INFORMATION (ABOUT DISK UNITS) 

Channel Unit Controller Alias  Str-ID  Pack Type  Disk Status

     0    2      --                         RP04  Off-line
     0    3      --     TSG    TSG     1/1  RP04  Mounted 
     0    6      --                         RP06  Off-line
     0    7      --     CRAP   CRAP    1/1  RP06  Mounted 
     1    0      --     PS     PS      1/2  RP06  Mounted 
     1    1      --     SNARK  SNARK   1/2  RP06  Mounted 
     1    2      --     FARK   FARK    1/1  RP06  Mounted 
     2    3      --     NET    NET     1/1  RP06  Mounted 
     2    4      --     PS     PS      2/2  RP06  Mounted 
     2    5      --     SNARK  SNARK   2/2  RP06  Mounted 

DS>



2.0  THE STRUCTURE COMMAND

     The STRUCTURE command is used to specify that I/O is to be directed
at  the  given  structure.   This  implies  that  the given structure is
already mounted by the system and accessible to the user.   The  implied
command  structure of DS is such that the structure or unit to which I/O
is to be directed  must  be  specified  before  commands  attempting  to
reference  that  structure or unit.  The alternative would be to specify
the structure or unit with each command, which was deemed less desirable
for the environment where one is predominantly interested in examining a
single structure or unit, and continually having to  give  its  identity
would  be an irritant.  The DRIVE command or the DEFINE command are used
to specify particular units for I/O.



2.1  EXAMPLE:

DS>STRUCTURE (TO USE) PS: 
DS>
USING THE DS PROGRAM                                              Page 3


3.0  THE DRIVE COMMAND

     The DRIVE command is provided  to  allow  the  specification  of  a
particular  drive  unit  to  direct  I/O  to,  by  giving  the  channel,
controller (RP20 disks), and unit specification  for  the  drive.   This
information,  if  not  known  a  priori,  might  be  obtained  from  the
INFORMATION command, depending  on  the  condition  of  the  unit.   The
STRUCTURE  command  is  used  to specify a mounted structure.  The DRIVE
command may refer to an unmounted pack, or a pack which  is  part  of  a
mounted  structure.   If  the  specified  unit  is  part  of  a  mounted
structure, a warning  message  to  that  effect  will  be  printed.   An
off-line  or  otherwise  inaccessible  unit  will not be accepted as the
argument for the DRIVE command.



3.1  EXAMPLE:

DS>DRIVE (TO USE IS ON CHANNEL) 1 (CONTROLLER) -1 (UNIT) 2
% Unit is part of a mounted Structure
DS>



4.0  THE DEFINE COMMAND

     The DEFINE  command  is  used  to  specify  a  possibly  multi-pack
physical  addressing  structure.   In this it is a superset of the DRIVE
command.  Giving the DEFINE command puts you  into  subcommand  mode  to
specify  the  channel,  controller (RP20 disks), and unit using the UNIT
subcommand for each logical unit of the "structure" in order.  The  UNIT
subcommand  may refer to an unmounted pack, or a pack which is part of a
mounted  structure.   If  the  specified  unit  is  part  of  a  mounted
structure,  a  warning  message  to  that  effect  will  be printed.  An
off-line or otherwise inaccessible unit will  not  be  accepted  as  the
argument  to  the  UNIT  subcommand.   The DONE subcommand completes the
definition, and leaves subcommand mode;   the  ABORT  subcommand  leaves
subcommand  mode  without  establishing  the definition.  All units of a
physical addressing structure must  be  of  the  same  type,  just  like
regular  TOPS-20  structures.   The  DEFINE  command  is very useful for
referencing broken disk  structures  which  consist  of  more  than  one
logical unit, and cannot be mounted by TOPS-20.  The INFORMATION command
can provide the arguments for the location of the desired packs.



4.1  EXAMPLE:

DS>DEFINE (PHYSICAL ADDRESSING STRUCTURE) 
DS-DEFINE>>? one of the following:
 ABORT   DONE     UNIT
DS-DEFINE>>UNIT (TO USE IS ON CHANNEL) 1 (CONTROLLER) -1 (UNIT) 1
% Unit is part of a mounted Structure
DS-DEFINE>>UNIT (TO USE IS ON CHANNEL) 2 (CONTROLLER) -1 (UNIT) 5
% Unit is part of a mounted Structure
USING THE DS PROGRAM                                              Page 4


DS-DEFINE>>DONE (WITH DEFINITION) 
DS>



5.0  THE CHECK COMMANDS

     The CHECK commands are designed to read the  specified  object  and
report  on  its condition.  Some of the information provided can help to
repair that condition.



5.1  CHECK PAGE

     The CHECK PAGE command desires the disk address of a  page  on  the
selected  unit  or  structure.   In  addition,  a  repeat  count  may be
specified, or UNTIL-STOPPED may be used.  A  Control-E  will  abort  the
repeat  operations.   The  page  is  read  using DSKOP and its condition
reported.  The responses should be one of the following:

     [ n errors counted in m tries ] - error summary for the operation.

     No problems encountered reading page - page read correctly  on  the
first try.

     % Transient read errors encountered reading page -  more  than  one
try was required to read the page, but ECC was not needed.

     % ECC is required to read page - the  page  was  able  to  be  read
correctly by applying error correction to the data.

     % Page is completely unreadable - ECC was not  sufficient  to  read
the  the  page.   The  contents  might still be recovered if more heroic
measures are taken, such as many repetitions,  or  moving  the  pack  to
another drive.  The system will probably always report this page dead in
this configuration.  Possibly only one sector of the  page  is  damaged,
however,  and this could be determined by selecting addresses to exclude
various  sectors,  or   by   using   a   program   which   attempted   a
sector-by-sector  recovery  of  the  page.  The DUMP PAGE command can be
useful in this regard, in that it will attempt output even if  the  read
was deemed unsuccessful.



5.1.1  EXAMPLE: -

DS>CHECK ? one of the following:
 FILE-READABILITY   INDEX-BLOCK         PAGE
DS>CHECK PAGE (AT DISK ADDRESS) 1234 (NUMBER OF TIMES) UNTIL-STOPPED 
% Check Page function aborted
[ 0. errors counted in 448. trials ]
DS>
USING THE DS PROGRAM                                              Page 5


5.2  CHECK INDEX-BLOCK

     The CHECK INDEX-BLOCK command desires the disk address of the  page
containing  the  index  block.  That page is then read using DSKOP as in
the CHECK PAGE command, and the same messages reported.  If the page  is
found  to  be  readable, further checks are made, and one or more of the
following messages issued:

     Contents of Index Block appear to be consistent - no other problems
detected with the index block page.

     % BAT Bit is set for Index Block - the  bit  indicating  that  this
index  block  contains  the  address of a page in the BAT Blocks is set.
For various reasons, this does not always indicate  an  unreadable  page
addressed  by  this index block, but if the block is otherwise valid, it
indicates that the system did have I/O problems with one of the pages at
some time.

     % Non-address bits in Index Block are  non-zero  -  this  indicates
that in at least some of the words of the index block, there is non-zero
data in the high-order nine bits of the word.  Except for the first four
words, containing the checksum, these bits should all be zero.

     % Checksum for Index Block is incorrect, should be <number> -  this
indicates that the page does not have the correct checksum to be a valid
index block.  The monitor will not use such an index block, and generate
an error.  The "correct" checksum for the page is given for the purposes
of comparison, and as an aid to those cases where you may be building an
index block up by hand, or repairing or modifying it to point to another
set of pages.  This calculation of the checksum will allow you to  avoid
doing  it  by  hand, and validate the constructed index block to be sure
you have the overhead and consistency information right.



5.2.1  EXAMPLE: -

DS>CHECK INDEX-BLOCK (AT DISK ADDRESS) 5740 

No problems encountered reading page    5740
Contents of Index Block appear to be consistent
DS>CHECK INDEX-BLOCK (AT DISK ADDRESS) 1124

No problems encountered reading page    1124
% Checksum for Index Block is incorrect, should be 35,,556134
% Non-address bits in Index Block are non-zero
DS>
USING THE DS PROGRAM                                              Page 6


5.3  CHECK FILE-READABILITY

     The CHECK FILE-READABILITY command desires  a  possibly  wild  file
specification  for  the  files  it  is  to check for "readability".  The
function performed is more or less identical to the program  READ.   All
pages of the files specified are read-tested.  The data pages are tested
as in CHECK PAGE, and the index blocks and super index block are  tested
as  in  CHECK INDEX.  The error messages which may result are similar to
the preceding commands.  This command may be aborted with  a  Control-E,
at  which time the error total line is printed.  Each filename is listed
as the command begins to  process  the  file.   This  command  does  not
require a prior DRIVE or STRUCTURE command to have been given.

     The disk address of any page of the file with problems is  included
with  the  error  messages for that page.  The address can allow further
followup with some of the other commands, such as CHECK  PAGE  or  CHECK
INDEX.



5.3.1  EXAMPLE: -

DS>CHECK FILE-READABILITY (OF FILES) DS.*.* 

[Attempting to read file DS.EXE.30]
[Attempting to read file DS.HLP.4]
[Attempting to read file DS.LOG.1]
[Attempting to read file DS.MAC.48]
[Attempting to read file DS.MEM.6]
[Attempting to read file DS.REL.32]
[Attempting to read file DS.RNO.7]
[ Total problems noted:  0.]
DS>



6.0  THE DIRECTORY COMMAND

     The purpose of the directory command is basically to give the index
or  super index block disk address value for a given file or files.  The
long file indication, offline indication, and FDB page  count  are  also
given.  The file index block address is often a very useful quantity for
other commands.



6.1  EXAMPLE:


DS>DIRECTORY (OF INDEX BLOCK ADDRESSES FOR) SNARK:<TCO>*.*.* 

Index Block Long   Page    Filename
  Address   File?  Count
         0            0.   SNARK:<TCO>1B-TCO-RECORD.BIN.1;OFFLINE
         0            0.   SNARK:<TCO>2-TCO-RECORD.BIN.1;OFFLINE
USING THE DS PROGRAM                                              Page 7


  12074734   Yes    183.   SNARK:<TCO>3-TCO-RECORD.BIN.1
         0            0.   SNARK:<TCO>3A-TCO-RECORD.BIN.1;OFFLINE
  10776444   Yes    192.   SNARK:<TCO>4-TCO-RECORD.BIN.1
  11000474           41.   SNARK:<TCO>4.1-TCO-RECORD.BIN.1
  11065610          144.   SNARK:<TCO>5-TCO-RECORD.BIN.6
  10525164            6.   SNARK:<TCO>5-TCO-RECORD.INTERIM.1
  11742120            3.   SNARK:<TCO>5.1-TCO-RECORD.BIN.1
  12142544           11.   SNARK:<TCO>6-TCO-RECORD.BIN.1
  10700624            2.   SNARK:<TCO>T5-1298.DIF.1

DS>



7.0  THE COPY COMMANDS

     The purpose of the COPY command is the recovery of data.  That data
might be a simple page of disk data, or the contents of a file or a long
file or a directory file.  In order to recover the data, the appropriate
disk address must be given.  Obviously, this command is oriented towards
disks where the pack is bad enough off to not be mountable, perhaps  too
hard  to  repair  in place, but there is a limited number of files which
must be recovered.

     This command also has uses in the attempt  to  repair  a  structure
toward  mountability.   For instance, it is extremely useful to use this
command to copy out the root-directory for the structure during a repair
operation.   That  way,  one  can  run  DIRTST  and  DIRPNT  on the file
containing the copy of the directory and both check its consistency  and
get  a  listing of disk addresses to follow the tree down to the desired
files.

     The same could be done with other directory files.  Even  in  cases
where  the ultimate desire is to delete a sick directory, and make a new
one without performing repairs;  the COPY command might be used to  copy
out  the  sick  directory  into  a  data  file which might then be later
analyzed for clues as to the cause of the corruption.

     All of the COPY commands set the byte size of the file  created  to
36  bits and the end-of-file pointer to the byte beyond the last page of
the file copied out.  All reads from the selected unit are diagnosed for
errors,  and  any index blocks involved are checked over also.  Messages
concerning any problems with any of the pages will appear on the  output
device.   The  destination  file  specification must be on a disk device
since PMAP I/O is done to create the output file;   or  it  must  be  to
device TTY:.  A Control-E will abort the command.



7.1  COPY PAGE

     The COPY PAGE command accepts a disk address  and  an  output  file
specification,  and  copies  the page at that disk address to the output
file from the specified structure or unit to the specified page  in  the
output file.
USING THE DS PROGRAM                                              Page 8


7.1.1  EXAMPLE: -

DS>COPY ? one of the following:
 DIRECTORY   FILE         LONG-FILE    PAGE
DS>COPY PAGE (AT ADDRESS) 5740 (TO) FOO.OUT.1 !New file! 

[COPY completed]
DS>COPY PAGE (AT ADDRESS) 5740 (TO) FOO.BAR.2 !Old generation! (PAGE) 6

[COPY completed]
DS>



7.2  COPY FILE

     The COPY FILE command accepts a disk address on the  selected  unit
or  structure,  which  is used as the address of the index block for the
file copied out to the output file specification.



7.2.1  EXAMPLE: -

DS>COPY FILE (WITH INDEX BLOCK ADDRESS) 5740 (TO) FOO.OUT
% Problems noted with index block 0 disk address 5740
% Index block has BAT bit set
[COPY completed]
DS>



7.3  COPY LONG-FILE

     The COPY LONG-FILE command accepts a disk address on  the  selected
unit or structure, which is used as the address of the super-index block
of the file copied out to the output file specification.



7.3.1  EXAMPLE: -

DS>COPY LONG-FILE (WITH INDEX BLOCK ADDRESS) 10065754 (TO) FOO.OUT

[COPY completed]
DS>



7.4  COPY DIRECTORY

     The COPY DIRECTORY command  accepts  an  unbracketed  string  of  a
directory  name,  and  a disk resident output file, and attempts to find
all pages of the named directory on  the  selected  unit/structure,  and
copy  them  to the output file.  In general, it is necessary to scan the
USING THE DS PROGRAM                                              Page 9


entire disk to find these pages the first time, though a table  is  kept
to speed subsequent accesses.  Each directory page is announced as it is
copied, and the  disk  addresses  of  any  "duplicate"  pages  are  also
reported  (One  expects  this  for  some directories like ROOT-DIRECTORY
because of the backup copy).

     This command is useful if you cannot find the index block  for  the
directory,  or  don't  want  to  bother  looking  for it.  The extracted
directory file can then be run through DIRPNT and DIRTST to check it and
to  dump  the  contents,  particularly the index blocks which then allow
using the COPY FILE and COPY LONG-FILE commands  to  recover  individual
files.



7.4.1  EXAMPLE: -

DS>COPY DIRECTORY (WITH NAME) ZIMA.MEMOS (TO) FOO.DIR.1 !New file! 

[Beginning mapping scan for directory pages]
 Directory page 0. found at disk address 350304
 Directory page 1. found at disk address 350564
 Directory page 2. found at disk address 350570
 Directory page 3. found at disk address 350574
 Directory page 4. found at disk address 350600
 Directory page 5. found at disk address 350604
 Directory page 6. found at disk address 350610

[COPY DIRECTORY completed]
DS>

WARNING:

     Unfortunately, the directory structure of TOPS-20 is such that  the
COPY  DIRECTORY command may not work for all directories without help by
hand.  This is because the monitor wants to treat the symbol  table  for
the  directory as a contiguous array, and so pages containing the symbol
table for the directory may or may not have the identifying header  code
in  the  first  two  words  of the page.  DS will announce any directory
symbol table page it finds, but there may be pages it cannot find.   One
may  need  to  find those pages by heuristic means, looking for an index
block with the other addresses (SEARCH command), or looking  around  the
related  disk  addresses.  The symbol table is not a necessary construct
for the rest of the file information, so this restriction may not be too
onerous in a recovery situation.



8.0  THE DUMP COMMANDS

     The  DUMP  commands  provide  interpreted  dumps  of  various  disk
structures,  as  described below.  Other programs such as DIRPNT provide
additional disk structure information that DS does not.  The dump output
can  be redirected from the terminal to another file by using the OUTPUT
command, in case the output is to be saved, or a hard-copy produced, for
USING THE DS PROGRAM                                             Page 10


instance.



8.1  DUMP PAGE

     The simplest DUMP command  is  DUMP  PAGE.   It  accepts  the  disk
address  of a page on the selected drive or structure, and dumps out the
contents of that page to the selected  output  file  in  octal,  SIXBIT,
left-  and  right-justified  ASCII, and PDP-11 format ASCII, preceded by
the page offset of the word.  Multiple zero  words  are  suppressed  and
denoted by a blank line.  This command may be aborted with Control-E.



8.1.1  EXAMPLE: -

DS>DUMP PAGE (AT DISK ADDRESS) 1 

Address        Octal   SIXBIT      L-ASCII      R-ASCII   11-ASCII

  0/    505755000000   HOM       Q > h^@^@    " } P^@^@    m^K^@^@

  3/    464162530000   FARK      M^G^U 0^@   ^Z^N * `^@    r h^@ 0
  4/         1000000     !      ^@^@^H^@^@   ^@^@^P^@^@   ^A^@^@^@
  5/         1000012     !  *   ^@^@^H^@^E   ^@^@^P^@^J   ^A^@^J^@
  6/               0            ^@^@^@^@^@   ^@^@^@^@^@   ^@^@^@^@
  7/             620       &0   ^@^@^@^A H   ^@^@^@^C^P   ^@^@^P^A
 10/        10005740     ( O@   ^@^@ @^K p   ^@^A^@^W `   ^H^@ `^K
 11/        10013700     (!?    ^@^@ @^W `   ^@^A^@ / @   ^H^@ @^W
 12/               0            ^@^@^@^@^@   ^@^@^@^@^@   ^@^@^@^@
 13/         1121600     !*.    ^@^@^I # @   ^@^@^R G^@   ^A^@^@ #
 14/            1440       ,@   ^@^@^@^C^P   ^@^@^@^F     ^@^@  ^C
 15/    126536563654   *U>N>L   ^U U u g V    + + k O ,    ^ - , g

101/    100000000574   (   %\   ^P^@^@^A >     ^@^@^B |   ^@^@ |^A
102/             400       $    ^@^@^@^A^@   ^@^@^@^B^@   ^@^@^@^A

165/     40506045522   $%&$M2   ^H^T 0 K )   ^P ( a^V R    F A R K

170/     44532040515   $E:$%-   ^I^U P A &   ^R + !^B M    Z I M A

173/     20040047524   " @$]4   ^D^B^@ O *   ^H^D^A^^ T        T O
174/     51520031055   %-0#(M   ^J 5^@ 2^V   ^T j^@ d -    P S - 2
175/     20060020040   " P" @   ^D^C^@  ^P   ^H^F^@ @      0      
176/          707070      XXX   ^@^@^G^N^\   ^@^@^N^\ 8   ^@^@ 8^N
177/               1        !   ^@^@^@^@^@   ^@^@^@^@^A   ^@^@^A^@
200/    424164000000   BAT       E^G  ^@^@   ^J^N @^@^@    t (^@^@
201/    777606000004   _^&  $      x 0^@^B      p `^@^D   ^F  ^D^@
202/               0            ^@^@^@^@^@   ^@^@^@^@^@   ^@^@^@^@
203/               1        !   ^@^@^@^@^@   ^@^@^@^@^A   ^@^@^A^@
204/      3004144066    8$,@V   ^@ ` ! H^[   ^A @ C^P 6   ^D^F 6 H
205/          227464      2\T   ^@^@^B /^Z   ^@^@^D ^ 4   ^@^@ 4 /

376/          606060      PPP   ^@^@^F^L^X   ^@^@^L^X 0   ^@^@ 0^L
USING THE DS PROGRAM                                             Page 11


377/               2        "   ^@^@^@^@^A   ^@^@^@^@^B   ^@^@^B^@
400/    726666666676   ZVVVV^    u [ 6 m _    k 6 m [ >    6 - > m
401/    555555555753   MMMMOK    [ 6 m [ u    6 m [ 7 k    m [ k [
402/    333333337266   ;;;;ZV    6 m [ > [    m [ 6 } 6    [ 6 6 >
% Page Dump aborted
DS>



8.2  DUMP INDEX-BLOCKS

     The  DUMP  INDEX-BLOCKS  command  takes  a   possibly   wild   file
specification,  and  for  each  file  in  the  specification, produces a
listing of the disk addresses for the data pages of the file, along with
the  disk  address of any index or super-index blocks.  Any disk reading
problems encountered while obtaining this information are printed.  This
command may be aborted with Control-E.



8.2.1  EXAMPLE: -

DS>DUMP INDEX-BLOCKS (OF FILE) DS.EXE

        Disk Addresses for File DS.EXE.30

Contents of Index Block for Section 0, Disk Address 10017454

  0/    10017544    10017460    10017464    10017470
  4/    10017474    10017500    10017504    10017510
 10/    10017514    10017520    10017524    10017530
 14/    10017534    10017540       --          --   

Pages in use by this Index Block:  14. 

DS>DUMP INDEX-BLOCKS (OF FILE) FOO.BAR

        Disk Addresses for File FOO.BAR.3

Contents of Super Index Block, Disk Address 10065754

  0/    10065740    10065760       --          --   

Pages in use by this Index Block:   2.

Contents of Index Block for Section 0, Disk Address 10065740

  0/    10065744       --          --          --   
  4/       --          --       10065750       --   

Pages in use by this Index Block:   2.

Contents of Index Block for Section 1, Disk Address 10065760

  0/    10065764       --          --          --   
USING THE DS PROGRAM                                             Page 12



Pages in use by this Index Block:   1.

DS>



8.3  DUMP INDEX-TABLE

     The  DUMP  INDEX-TABLE  command  produces  a  listing,  taking  the
specified  file,  and  interpreting it in the form of an INDEX-TABLE.BIN
file.  The  directory  number,  directory  number  of  this  directory's
superior,  offset into the directory of the FDB, and the disk address of
the index block of the directory are given, along with the  TOPS-10  PPN
set  for  the  directory,  if present.  This command may be aborted with
Control-E.



8.3.1  EXAMPLE: -

DS>DU INDEX-TABLE (FROM FILE) PS:<ROOT-DIRECTORY>INDEX-TABLE.BIN.1 

Directory  Superior      FDB    Disk Address of   PPN of
 Number    Directory    Offset   Directory XB    Directory

     1         1          112      10005740
     2         1          243      11607000
     3         1          310      11607010
     5         1          422      11607030
     6         1          467      11607044
    10         1          602      11607064
    11         1          650      11607074
    20         1        23050      10434774
    21       273         2267      10452510
    23         1        23407      10437670
    24        77         2661      12173600
    25         1        10633
% Directory index table dump aborted
DS>



8.4  DUMP BIT-TABLE

     The DUMP BIT-TABLE command interprets the specified file as  if  it
was  a  DSKBTTBL file, and produces a listing of the free blocks and bit
map for each cylinder in the file.  The number of units, and drive  type
must  be  given  in  the  command, as the bittable is not self-defining.
This command may be aborted with Control-E.
USING THE DS PROGRAM                                             Page 13


8.4.1  EXAMPLE: -

DS>DU BIT-TABLE (FOR) 1 (PACK) RP06 (FROM FILE) <ROOT-DIRECTORY>DSKBTTBL..1 

Cylinder Free Pages                   Map
-------- ----------                   ---
     0.      92.    077777777777 777777777777 777777760000 
     1.       0.    000000000000 000000000000 000000000000 
     2.      15.    000000000000 000000001176 000076620000 
     3.       0.    000000000000 000000000000 000000000000 
     4.      15.    000000000000 000000000030 001776360000 
     5.      15.    000000000000 034200000374 004006600000 
     6.      15.    076000000000 000000000000 300601760000 
     7.      15.    000000000000 000000000015 700443760000 
     8.      14.    000231400000 000000000000 000207760000 
     9.      15.    000000000001 770000000077 600000000000 
    10.      15.    000001400313 760540000000 000000000000 
    11.       0.    000000000000 000000000000 000000000000 
    12.      15.    000000000000 000000440000 007777400000 
    13.       0.    0000000
% Bit table dump aborted
DS>



8.5  DUMP HOME-BLOCKS

     The DUMP HOME-BLOCKS command produces a listing of the HOME  blocks
for  the selected unit or structure, along with consistency information.
The HOME blocks are read and checked and the results  printed.   One  or
more of the following will appear:

     Primary HOME Block is unreadable - the primary HOME block could not
be read by the program.

     Read of Primary HOME Block encountered errors - the HOME block  was
able to be read by mutilple tries or ECC.

     Secondary HOME Block is unreadable - as for primary.

     Read of Secondary HOME Block encountered errors - as for primary.

     Primary HOME Block is bad - the primary HOME block failed  to  pass
the  consistency  tests  required for a HOME block.  See the interpreted
dump for more information on what is wrong.

     Secondary HOME Block is bad - as for primary.

     HOME Blocks are inconsistent - the HOME blocks do  not  agree  with
one another.  See the difference listing for which words disagree.

     HOME Blocks appear to be ok - no problems noticed.
USING THE DS PROGRAM                                             Page 14


     Next appears the interpreted listing of the contents  of  the  HOME
blocks.  The format is word offset in the block, mnemonic, "explanation"
of the usual contents, and then the contents of the word printed in  the
appropriate units.

     After that is a listing of  differences  between  the  primary  and
secondary HOME blocks as an aid in diagnosing error conditions.



8.5.1  EXAMPLE: -

DS>STRUCTURE (TO USE) SNARK:
DS>DUMP HOME-BLOCKS (FOR STRUCTURE) 


HOME Blocks for Logical Unit  0:
HOME Blocks appear to be ok

  0   HOMNAM   SIXBIT/HOM/:  HOM   
  3   HOMSNM   SIXBIT/Structure Name/:  SNARK 
  4   HOMLUN   # of Packs in STR,,Logical Unit in STR:  2,,0
  5   HOMHOM   Sector Number of This HOME Block,,Sector # of Other:  1,,12
  6   HOMP4S   Number of Pages for Swapping on this Unit:  5035.
  7   HOMFST   First Swapping Cylinder on Unit:  565
 10   HOMRXB   Address of ROOT-DIRECTORY Index Block:  10005740
 11   HOMBXB   Address for BACKUP-COPY-OF-ROOT-DIRECTORY:  10013700
 12   HOMFLG   Flags:  No Flags Set, Unlimited Directories
 13   HOMSIZ   Number of Sectors in this Unit:  304000.
 14   HOMBTB   Number of Cylinders in Structure:  1600.
 15   HOMMID   Pack Unique Code:  126601011626
 61   HOMFE0   Front End File System Starting Sector:  100000014474
 62   HOMFE1   Front End File System Size in Sectors:  12160.
101   HOMFE2   BOOTSTRAP.BIN Starting Sector:  100000000574
102   HOMFE3   BOOTSTRAP.BIN Size in Sectors:  256.
164   HOMSER   APR serial number for BOOT:  0.
165   HOMUID   -11 Format Unit I.D. (12 Characters):   S N A R K^@^@^@^@^@^@^@
170   HOMOID   -11 Format Owner I.D. (12 Characters):   O P E R A T O R^@^@^@^@
173   HOMFSN   -11 Format File System Name:       T O P S - 2 0      
176   HOMCOD   Unique Code 707070:  707070
177   HOMSLF   Sector Number of this Block:  1

HOME Blocks for Logical Unit  1:
HOME Blocks appear to be ok

  0   HOMNAM   SIXBIT/HOM/:  HOM   
  3   HOMSNM   SIXBIT/Structure Name/:  SNARK 
  4   HOMLUN   # of Packs in STR,,Logical Unit in STR:  2,,1
  5   HOMHOM   Sector Number of This HOME Block,,Sector # of Other:  1,,12
  6   HOMP4S   Number of Pages for Swapping on this Unit:  5035.
  7   HOMFST   First Swapping Cylinder on Unit:  565
 10   HOMRXB   Address of ROOT-DIRECTORY Index Block:  10005740
 11   HOMBXB   Address for BACKUP-COPY-OF-ROOT-DIRECTORY:  10013700
 12   HOMFLG   Flags:  No Flags Set, Unlimited Directories
 13   HOMSIZ   Number of Sectors in this Unit:  304000.
USING THE DS PROGRAM                                             Page 15


 14   HOMBTB   Number of Cylinders in Structure:  1600.
 15   HOMMID   Pack Unique Code:  126601011626
 61   HOMFE0   Front End File System Starting Sector:  0
 62   HOMFE1   Front End File System Size in Sectors:  0.
101   HOMFE2   BOOTSTRAP.BIN Starting Sector:  0
102   HOMFE3   BOOTSTRAP.BIN Size in Sectors:  0.
164   HOMSER   APR serial number for BOOT:  0.
165   HOMUID   -11 Format Unit I.D. (12 Characters):   S N A R K^@^@^@^@^@^@^@
170   HOMOID   -11 Format Owner I.D. (12 Characters):   O P E R A T O R^@^@^@^@
173   HOMFSN   -11 Format File System Name:       T O P S - 2 0      
176   HOMCOD   Unique Code 707070:  707070
177   HOMSLF   Sector Number of this Block:  1
DS>



8.6  DUMP BAT-BLOCKS

     The DUMP BAT-BLOCKS command produces a listing of  the  BAT  blocks
for  the selected unit or structure, along with consistency information.
The BAT blocks are read and checked and the  results  printed.   One  or
more of the following will appear:

     Primary BAT Block is unreadable - the primary BAT block  could  not
be read by the program.

     Read of Primary BAT Block encountered errors - the  BAT  block  was
able to be read only by multiple tries or ECC.

     Secondary BAT Block is unreadable - as for primary.

     Read of Secondary BAT Block encountered errors - as for primary.

     Primary BAT Block is bad - the primary BAT block failed to pass the
consistency  tests  required  for a BAT block.  See the interpreted dump
for more information on what might be wrong.

     Secondary BAT Block is bad - as for primary.

     BAT Blocks are inconsistent - the BAT blocks do not agree with  one
another.  See the difference listing for which words disagree.

     BAT Blocks appear ok - no problems noticed.

     Next the count of BAT block  pairs  added  by  the  MAPPER  program
(DDRPI)  is  displayed, and the count of entries written by the monitor,
and the total.

     After that, if there are  any  entries  in  the  blocks,  they  are
displayed,  broken  down  into  the  disk  address  on  the  unit of the
beginning of the bad region, the size of the bad region in sectors,  the
APR  serial  number  of the processor writing the entry, and the channel
and unit number of the drive that the  pack  was  mounted  on  when  the
region was first noted bad.
USING THE DS PROGRAM                                             Page 16


     Finally, a listing of  the  differences  between  the  primary  and
secondary BAT blocks is done as an aid in diagnosing error conditions.

     Note that the CHECKD SCAN command may be used to find the  location
(file  page,  swapping  space,  etc.)  of the pages in the BAT blocks if
CHECKD "likes" the pack enough to use it.



8.6.1  EXAMPLE: -

DS>DUMP BAT-BLOCKS (FOR STRUCTURE) 


BAT Blocks for Logical Unit  0:
BAT Blocks appear ok
Mapper added count:   0.  MONITOR added count:   0.  Total:   0.

BAT Blocks for Logical Unit  1:
BAT Blocks appear ok
Mapper added count:   0.  MONITOR added count:   1.  Total:   1.
Unit-Address    Size(Sectors)   APR number      Channel Unit
    500750        4.              2102.            2      5
DS>



8.7  DUMP MICROPROCESSOR-FILE-SYSTEM-DIRECTORY

     The DUMP MICROPROCESSOR-FILE-SYSTEM-DIRECTORY command is just about
the  only  method  existing  to peek into the internals of the front-end
file system for the  2020  processor-based  systems.   It  will  provide
information on the contents and location of the files in the region used
by the microprocessor front-end by interpreting the pointer locations in
the HOME blocks and the word pairs in the file-system directory.

     First the HOME block information is printed, in the same format  as
the  DUMP  HOME-BLOCKS  command  uses.   Then follows the directory page
information.  The pre-defined files  are  named,  and  the  others,  the
so-called  "indirect  files"  are numbered.  Then there is a header line
and a line of interpreted directory information, consisting of the  page
offset within the microprocessor file system of the starting page of the
file region, the corresponding disk address, the  microprocessor  format
cylinder,  track  and sector of that address, and the length in pages of
the file region.  There are consistency checks done on the page  offset,
file  length,  and  unused bit fields of the cylinder/track/sector word,
which may generate warning messages.

     Diagnostic read messages may appear if there is trouble in  reading
the  directory page of the file system or the HOME blocks.  This command
may be aborted with Control-E.
USING THE DS PROGRAM                                             Page 17


8.7.1  EXAMPLE: -

DS>DUMP MICROPROCESSOR-FILE-SYSTEM-DIRECTORY (FOR UNIT) 

HOME Block Information:

101   HOMFE2   Microprocessor File System Starting Sector: 100000000224
102   HOMFE3   Microprocessor File System Size in Sectors: 256.
103   HOMFE4   Microprocessor Format Cylinder/Track/Sector: 1/0/0

Directory Page Information:

Free Space Region
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
           32.                424       1/  4/ 10          32.

Microcode File
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
            1.                230       1/  0/  4          12.

Monitor Pre-BOOT File
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
           13.                310       1/  1/ 26           1.

Diagnostic Pre-BOOT File
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
           14.                314       1/  1/ 32           1.

BOOTCHECK 2 File
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
           15.                320       1/  2/  0          12.

Monitor BOOT File
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
           27.                400       1/  3/ 22           1.

Diagnostic BOOT File
Starting Page Offset   Disk Address   CYL/TRK/SEC   Length in Pages
           28.                404       1/  3/ 26           4.

DS>



9.0  THE SEARCH COMMAND

     The SEARCH command accepts arguments of  an  octal  pattern,  octal
mask,  and  begin  and  end  disk  addresses  for searching the selected
unit/structure.  The disk is then scanned and each word in the  selected
region is checked for the desired pattern.  Any occurances are reported,
listing disk address of the page, offset of the word in  the  page,  and
contents  of  the word in octal.  The Control-A character may be used to
get a status line of where the search is, and  the  Control-E  character
may be used to abort the operation.
USING THE DS PROGRAM                                             Page 18


     This command is somtimes useful as a brute force method of  finding
files,  directory  pointers, disk addresses in index blocks and whatever
when other methods are more painful.



9.1  EXAMPLE:

DS>SEARCH (FOR PATTERN) 707070 (WITH MASK) -1 (STARTING AT) 0 (ENDING AT) 1000
Disk address:        0, Offset: 376, Contents:       707070
Disk address:       10, Offset: 576, Contents:       707070
DS>



10.0  THE WATCH COMMAND

     The WATCH command allows monitoring the contents of a word  on  the
disk  by  providing  the  disk address, word offset, and check interval.
This command is sometimes useful to see if a disk  address  is  actually
being  written,  or  if  writes  correspond  to the desired events - for
example, if a page marked in the BAT  blocks  is  actually  still  being
used.  The data is typed in octal.



10.1  EXAMPLE:

DS>WATCH (WORD OFFSET) 0 (IN PAGE AT DISK ADDRESS) 1 (WITH INTERVAL OF) 2 (MS) 
[Type ^E to terminate]
0/      505755000000
% WATCH aborted
DS>



11.0  THE VERIFY COMMAND

     The VERIFY command performs a  function  similar  to  that  of  the
VERIFY  function  of  the FORMAT program.  It accepts arguments of begin
and end disk addresses, or SWAPPING-SPACE.  The default  is  the  entire
unit/structure.   It reads the specified unit or structure using DSKOPs,
page by page, sequentially,  and  will  report  any  errors  encountered
reading  any  page.   Pages which turn out to be unreadable will thereby
become logged in the BAT blocks for the appropriate unit.  At the end, a
summary  line  of  the number of errors encountered, and the approximate
rate in pages/second of the verify is printed.

     Clearly, this particular function is of the most use just after the
structure  has  been  created;   however,  the  location  of pages which
recover after a few tries or which  recover  after  ECC  is  applied  is
sometimes  useful.   For  instance,  elimination  of such pages from the
swapping space by putting them in the BAT blocks  is  generally  a  good
idea.   The  CHECKD  SCAN  command  can  tell  you where (what file) the
reported troublesome pages live on the structure.
USING THE DS PROGRAM                                             Page 19


     The VERIFY command may be aborted by using Control-E.  The  summary
line  will  be  printed.   The  Control-A character may be used during a
VERIFY to obtain a status line of the current disk address being  worked
on,  the  percentage of the structure or unit completed, and the current
error count.



11.1  EXAMPLE:


DS>VERIFY (BEGINNING AT) ? disk address
  or SWAPPING-SPACE
DS>VERIFY (BEGINNING AT) 0 (AND ENDING AT) 10000
[ Working on pack on Channel 2, Controller -1, Unit 5 ]

[ Total problems noted: 0., Pages/Second = 170. ]
DS>
DS>VERIFY (BEGINNING AT) 0 (AND ENDING AT) -1 
[ Working on pack on Channel 2, Controller -1, Unit 5 ]
Working on disk address 33614 (4.%), error count is 0.
Working on disk address 52434 (7.%), error count is 0.
% Verification pass aborted at disk address 55514
[ Total problems noted: 0., Pages/Second = 177. ]
DS>



12.0  THE OUTPUT COMMAND

     The OUTPUT command is provided to  allow  specifying  an  alternate
file specification for the output produced by the program (primarily the
DUMP commands).  The default is the terminal.  The output can be changed
with  another  OUTPUT command, which closes the current file.  Any error
which results in a question-mark error message will also do an  implicit
close  on  the  output  file  so  that  the  data  is not lost.  In this
situation, the output has been redirected back to the terminal.



12.1  EXAMPLE:

DS>OUTPUT (INFORMATION TO FILE) FOO.OUT
DS>



13.0  THE PUSH COMMAND

     The PUSH command is the way provided to transfer to a new  EXEC  in
an  inferior process without leaving DS and being able to POP back to it
after completing whatever you needed to PUSH for.
USING THE DS PROGRAM                                             Page 20


13.1  EXAMPLE:

DS>PUSH (COMMAND LEVEL) 

 TOPS-20 Command processor 5(606)
@POP
DS>



14.0  THE FILDDT COMMAND

     The FILDDT  command  will  attempt  to  run  SYS:FILDDT.EXE  in  an
inferior  process.   The physical addressing features of FILDDT provided
for Release 4 of TOPS-20 provide access to the disk in ways that DS does
not.   For instance, FILDDT will allow writes to the disk if patching is
enabled, whereas DS makes no changes on the  disk.   In  a  disk  repair
operation,  information  might be provided by DS, and the actual changes
made by FILDDT in order to correct the disk data.  EXITing  from  FILDDT
will return to DS command level.



14.1  EXAMPLE:

DS>FILDDT (IN AN INFERIOR FORK) 
FILDDT>EXIT
DS>



15.0  THE EXIT COMMAND

     The EXIT command leaves DS.  If a CONTINUE is  attempted  after  an
EXIT, it is as if START had been typed.



15.1  EXAMPLE:

DS>EXIT
@CONTINUE
DS Disk Utility Program %3(125)

DS>



16.0  THE HELP COMMAND

     The HELP command tries to copy the file HLP:DS.HLP to the  terminal
to provide help with the commands.
USING THE DS PROGRAM                                             Page 21


16.1  EXAMPLE:

DS>HELP (WITH COMMANDS) 
DS>help
     DS is a program which is designed to provide information and certain
software diagnostic help concerning the disk file system.  Most functions
require privileges for operation.    The intent is not to take corrective
action with this program, but to provide information allowing such action
to be taken.  The commands are:

CHECK           Check and report the results on one of the following:

                FILE-READABILITY Check files specified by possibly wild
                                file specification for readability by
                                using DSKOPs and report any errors that
                                are encountered.  Control-E will abort.
                INDEX-BLOCK     Check specified disk address for a
                                valid index block including BAT bit,
                                checksum, and non-address bits.
                PAGE            Check page at specified disk address
                                report any problems reading page.
COPY            FILE            Copy out a regular or long file to a
                LONG-FILE       destination file by providing the disk
                PAGE            address of the index block or super index
                                block; or copy out the addressed page.
                                Control-E will abort.
                DIRECTORY       Attempt to copy out the pages of the
                                named directory to a file.  May need
                                to do a full scan of the disk.  Control-E
                                will abort, Control-A will provide status.
                                All COPY output must be to disk.
DEFINE          Specify a set of physical drives to serve as a structure
                for addressing purposes by providing channel, controller,
                and unit for each drive.
DIRECTORY       Give a directory listing including (super) index block
                disk address for the specified files.
DRIVE           Specify a specific channel, controller and unit to access.
DUMP            Output an interpretive listing of one of:

                BAT-BLOCKS      Descriptive list of BAT block contents.
                BIT-TABLE       List the contents of the specified file
                                interpreted as a disk bittable.
                                Control-E will abort.
                HOME-BLOCKS     Descriptive list of HOME block contents.
                INDEX-BLOCKS    List of disk addresses in index block(s)
                                for the specified file.
                                Control-E will abort.
                INDEX-TABLE     List the contents of the specified file
                                interpreted as a disk index-table.
                                Control-E will abort.
                MICROPROCESSOR-FILE-SYSTEM-DIRECTORY
                                Descriptive list of directory page for
                                microprocessor file system for the KS
                                processor (2020).  Control-E will abort.
                PAGE            List contents of page at specified disk
USING THE DS PROGRAM                                             Page 22


                                address in Octal and SIXBIT and ASCII.
                                Control-E will abort.
EXIT            Exit from the program.
FILDDT          Transfer control to SYS:FILDDT in an inferior process.
HELP            Type this text.
INFORMATION     Displays the status of the disk drives on the system.
OUTPUT          Specify output file used for some of the commands.
PUSH            Transfer control to an EXEC in an inferior process.
SEARCH          Scan the structure or unit for a given octal pattern
                with an octal mask over a specified range of addresses.
                Reports all occurances.  Control-E to abort, and Control-A
                for a status line.
STRUCTURE       Specify a disk structure to use in subsequent commands.
TAKE            Read subsequent commands from the specified file.
VERIFY          Read-check the selected structure or unit using DSKOPs.
                A begin and end address or "SWAPPING-SPACE" may be given.
                Output any errors encountered.  Interruptible by using
                Control-E to abort, and Control-A will output a status
                line of the current disk address and cumulative error
                total.
WATCH           Periodically monitor a word offset into a disk page to
                detect and display changes.  Aborted by Control-E.

See DS.MEM for more detailed information.

[End of DS.HLP]
DS>



17.0  THE TAKE COMMAND

     The TAKE command accepts the file specification for a command file.
TAKEs  may  not be nested, and an error will abort the TAKE file.  Since
DS will be mainly used in an information-gathering capacity  when  there
is  an  unknown  disk error condition, use of standard TAKE files is not
expected as a normal situation.



17.1  EXAMPLE:

DS>TAKE (COMMANDS FROM FILE) FOO.CMD.1 ! FOO contains INFORMATION

Channel Unit Controller Alias  Str-ID  Pack Type  Disk Status

     0    2      --                         RP04  Off-line
     0    3      --     TSG    TSG     1/1  RP04  Mounted 
     0    6      --                         RP06  Off-line
     0    7      --     CRAP   CRAP    1/1  RP06  Mounted 
     1    0      --     PS     PS      1/2  RP06  Mounted 
     1    1      --     SNARK  SNARK   1/2  RP06  Mounted 
     1    2      --     FARK   FARK    1/1  RP06  Mounted 
     2    3      --     NET    NET     1/1  RP06  Mounted 
     2    4      --     PS     PS      2/2  RP06  Mounted 
USING THE DS PROGRAM                                             Page 23


     2    5      --     SNARK  SNARK   2/2  RP06  Mounted 


[Command file completed]
DS>

[End of DS.MEM]