Google
 

Trailing-Edge - PDP-10 Archives - LCG_Integration_Tools_Clearinghouse_T20_v7_30Apr86 - tools/si_dumper011/dumper_func_spec.mem
There are 2 other files named dumper_func_spec.mem in the archive. Click here to see a list.



                           DUMPER-32 Function Description


                                      Draft #2


                                   28-August-1985



                          Stevens Institute of Technology

                                  Computer Center
   DUMPER-32 Function Specificaiton                                Page 2
   Introduction                                           27 January 1986


                                      CONTENTS

           1       Introduction . . . . . . . . . . . . . . . . . . . . 6
           2       Related Documents  . . . . . . . . . . . . . . . . . 6
           3       Document Revision History  . . . . . . . . . . . . . 6
           4       Modules  . . . . . . . . . . . . . . . . . . . . . . 6
           5       Command Interface  . . . . . . . . . . . . . . . . . 8
           5.1       Input-specification  . . . . . . . . . . . . . . . 8
           5.2       Output-specification . . . . . . . . . . . . . . . 8
           5.3       Qualifiers . . . . . . . . . . . . . . . . . . . . 8
           5.3.1     BLOCKING_FACTOR=number . . . . . . . . . . . . . . 8
           5.3.2     CREATEDIRECTORY  . . . . . . . . . . . . . . . . . 9
           5.3.3     FORMAT[=Keyword] . . . . . . . . . . . . . . . . . 9
           5.3.3.1   INTERCHANGE  . . . . . . . . . . . . . . . . . . . 9
           5.3.3.2   BACKUP . . . . . . . . . . . . . . . . . . . . . . 9
           5.3.3.3   DUMPER . . . . . . . . . . . . . . . . . . . . . . 9
           5.3.4     LIST[=Output-file] . . . . . . . . . . . . . . . . 9
           5.3.5     LOG[=Keyword]  . . . . . . . . . . . . . . . . . . 9
           5.3.5.1   FILES  . . . . . . . . . . . . . . . . . . . . .  10
           5.3.5.2   ALL  . . . . . . . . . . . . . . . . . . . . . .  10
           5.3.5.3   DIRECTORIES  . . . . . . . . . . . . . . . . . .  10
           5.3.6     REWIND . . . . . . . . . . . . . . . . . . . . .  10
           5.3.7     SELECT[=Tape-specifications] . . . . . . . . . .  10
           5.3.8     SKIP[=Number]  . . . . . . . . . . . . . . . . .  10
           5.3.9     SSNAME[=Save-set-name] . . . . . . . . . . . . .  10
           5.4       Examples . . . . . . . . . . . . . . . . . . . .  11
           5.4.1     Getting a listing of a tape  . . . . . . . . . .  11
           5.4.2     Restoring selected files . . . . . . . . . . . .  11
           5.4.3     Restoring a complete tape creating directories .  11
           6       Functional description . . . . . . . . . . . . . .  11
           6.1       Overview . . . . . . . . . . . . . . . . . . . .  12
           6.2       Converting file formats  . . . . . . . . . . . .  12
           6.2.1     BACKUP-10 tapes  . . . . . . . . . . . . . . . .  12
           6.2.2     DUMPER-20 tapes  . . . . . . . . . . . . . . . .  13
           6.2.3     Non-7, 8, or 36-bit bytes  . . . . . . . . . . .  13
           6.3       Known Problems/Restrictions  . . . . . . . . . .  14
           6.4       Libraries and Required files . . . . . . . . . .  14
           6.4.1     CHARACTER_DEFINITIONS.REQ  . . . . . . . . . . .  14
           6.4.2     DUMPER_SYMBOLS.REQ . . . . . . . . . . . . . . .  14
           6.4.2.1   $BYTE, $WORD, $LONGWORD  . . . . . . . . . . . .  14
           6.4.2.2   $DESCRIPTOR_DECL and $DESCRIPTOR_INIT  . . . . .  14
           6.4.2.3   $IOSB_DECL . . . . . . . . . . . . . . . . . . .  15
           6.4.3     TAPE_FORMAT.REQ  . . . . . . . . . . . . . . . .  15
           6.5       Routines . . . . . . . . . . . . . . . . . . . .  16
           6.5.1     DUMPER.BLI . . . . . . . . . . . . . . . . . . .  16
           6.5.1.1   DUMPER_MAIN  . . . . . . . . . . . . . . . . . .  16
           6.5.1.2   MATCH_FILESPEC (FILE_SPEC) . . . . . . . . . . .  16
           6.5.1.3   EXTRACT_FIELDS (STRING_DESC, RESULT) . . . . . .  16
           6.5.1.4   MATCH_SINGLE_FILE (FILE_SPEC, TEMPLATE_SPEC) . .  16
           6.5.1.5   MATCH_STRING (STRING_LENGTH, STRING_POINTER, 
                     PATTERN_LENGTH, PATTERN_POINTER) . . . . . . . .  16
           6.5.2     DUMPER_DRIVER.BLI  . . . . . . . . . . . . . . .  17
           6.5.2.1   DRIVER_PROCESS_COMMAND . . . . . . . . . . . . .  17
           6.5.2.2   CHECK_SAVE_SET_RECORD  . . . . . . . . . . . . .  17
   DUMPER-32 Function Specificaiton                                Page 3
   Introduction                                           27 January 1986


           6.5.2.3   RESTORE_SAVE_SET . . . . . . . . . . . . . . . .  17
           6.5.2.4   RESTORE_FILE   . . . . . . . . . . . . . . . . .  17
           6.5.2.5   LIST_SAVE_SET  . . . . . . . . . . . . . . . . .  17
           6.5.3     DUMPER_CVT.BLI . . . . . . . . . . . . . . . . .  18
           6.5.3.1   CVT_INITIALIZE . . . . . . . . . . . . . . . . .  18
           6.5.3.2   CVT_CONVERT_RECORD (CONVERSION_TABLE, 
                     RECORD_36BIT, INITIAL_WORD_INDEX)  . . . . . . .  18
           6.5.3.3   CVT_SIXBIT_2_ASCID (WORD_36BIT, BYTE_SIZE, 
                     BYTE_POSITION, STORAGE, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  18
           6.5.3.4   CVT_FETCH_7BIT_CHARACTER (ASCII_STRING, 
                     CHARACTER_OFFSET, LSN_FLAG)  . . . . . . . . . .  18
           6.5.3.5   CVT_WORD_2_LONGWORD (WORD_36BIT, BYTE_SIZE, 
                     BYTE_POSITION, LONG_WORD, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  18
           6.5.3.6   CVT_ASCIZ_2_ASCID (ASCIZ_STRING, BYTE_SIZE, 
                     BYTE_POSITION, ASCID_STRING, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  18
           6.5.3.7   CVT_FIELD (WORD_36BIT, BYTE_SIZE, BYTE_POSITION, 
                     STORAGE, STORAGE_SIZE, RECORD_BUFFER)  . . . . .  19
           6.5.3.8   CVT_BPT_2_ASCID (WORD_36BIT, BYTE_SIZE, 
                     BYTE_POSITION, STORAGE, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  19
           6.5.3.9   CVT_UDT_2_DATE_TIME (UDT_ADDRESS, BYTE_SIZE, 
                     BYTE_POSITION, STORAGE, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  19
           6.5.3.10  CVT_NEG_FIELD (WORD_36BIT, BYTE_SIZE, 
                     BYTE_POSITION, STORAGE, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  19
           6.5.4     DUMPER_BACKUP_TAPE.BLI . . . . . . . . . . . . .  19
           6.5.4.1   BACKUP_INITIALIZATION  . . . . . . . . . . . . .  19
           6.5.4.2   BACKUP_READ_AND_DECODE_RECORD 
                     (BLOCKING_AND_DIR_FLAG, RECORD_ADDRESS)  . . . .  19
           6.5.4.3   BACKUP_CHECK_SAVE_SET_RECORD (RECORD_ADDRESS)  .  20
           6.5.4.4   BACKUP_PROCESS_FILE (RECORD_ADDRESS) . . . . . .  20
           6.5.4.5   BACKUP_PROCESS_DATA (RECORD_ADDRESS) . . . . . .  20
           6.5.4.6   BACKUP_SKIP_SAVE_SET (NUMBER_TO_SKIP, 
                     RECORD_ADDRESS)  . . . . . . . . . . . . . . . .  20
           6.5.4.7   BACKUP_LIST_RECORD (RECORD_ADDRESS)  . . . . . .  20
           6.5.4.8   CVT_F_PTH_2_ASCID (WORD_36BIT, BYTE_SIZE, 
                     BYTE_POSITION, STORAGE, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  20
           6.5.4.9   CVT_PATH_2_ASCID (WORD_36BIT, BYTE_SIZE, 
                     BYTE_POSITION, STORAGE, STORAGE_SIZE, 
                     RECORD_BUFFER) . . . . . . . . . . . . . . . . .  21
           6.5.4.10  CVT_PATH_OR_F_PTH_2_ASCID (RECORD_BUFFER, 
                     BYTE_SIZE, STORAGE, STORAGE_SIZE, GET_TYPE_RTN)   21
           6.5.4.11  CVT_BACKUP_FILE_TYPE . . . . . . . . . . . . . .  21
           6.5.4.12  CVT_PROT (PROT_FIELD)  . . . . . . . . . . . . .  21
           6.5.4.13  CVT_PROT_2_ASCIC (PROT_STRING, PROT_BINARY)  . .  21
           6.5.5     DUMPER_DUMPER_TAPE.BLI . . . . . . . . . . . . .  21
           6.5.5.1   DUMPER_INITIALIZATION  . . . . . . . . . . . . .  22
           6.5.5.2   DUMPER_READ_AND_DECODE_RECORD 
                     (BLOCKING_AND_DIR_FLAG, RECORD_ADDRESS)  . . . .  22
   DUMPER-32 Function Specificaiton                                Page 4
   Introduction                                           27 January 1986


           6.5.5.3   DUMPER_CHECK_SAVE_SET_RECORD (RECORD_ADDRESS)  .  22
           6.5.5.4   DUMPER_PROCESS_FILE (RECORD_ADDRESS) . . . . . .  22
           6.5.5.5   DUMPER_PROCESS_DATA (RECORD_ADDRESS) . . . . . .  22
           6.5.5.6   DUMPER_SKIP_SAVE_SET (NUMBER_TO_SKIP, 
                     RECORD_ADDRESS)  . . . . . . . . . . . . . . . .  22
           6.5.5.7   DUMPER_LIST_RECORD (RECORD_ADDRESS)  . . . . . .  22
           6.5.5.8   CVT_DUMPER_FILE_TYPE . . . . . . . . . . . . . .  23
           6.5.6     DUMPER_TAPE_IO.BLI . . . . . . . . . . . . . . .  23
           6.5.6.1   TAPE_ACCESS  . . . . . . . . . . . . . . . . . .  23
           6.5.6.2   TAPE_DEACCESS  . . . . . . . . . . . . . . . . .  23
           6.5.6.3   TAPE_REWIND  . . . . . . . . . . . . . . . . . .  23
           6.5.6.4   READ_TAPE_BLOCK (TAPE_BUFFER_INDEX)  . . . . . .  23
           6.5.6.5   READ_TAPE_BLOCK_BACKWARDS (TAPE_BUFFER_INDEX)  .  23
           6.5.6.6   DEALLOCATE_BUFFERS . . . . . . . . . . . . . . .  24
           6.5.6.7   TAPE_IO_OPEN (DEVICE_DESCRIPTOR, BLOCKING_FACTOR, 
                     BLOCK_SIZE)  . . . . . . . . . . . . . . . . . .  24
           6.5.6.7.1 OPEN_TAPE_DRIVE (DEVICE_NAME)  . . . . . . . . .  24
           6.5.6.7.2 ALLOCATE_BUFFERS (SIZE_TO_ALLOCATE)  . . . . . .  24
           6.5.6.8   TAPE_IO_CLOSE (DEVICE_DESCRIPTOR)  . . . . . . .  24
           6.5.6.9   TAPE_IO_PEEK_RECORD (RECORD_ADDRESS) . . . . . .  24
           6.5.6.10  TAPE_IO_READ_BACKWARDS_RECORD 
                     (FORCE_RECORD_ZERO_FLAG, RECORD_ADDRESS) . . . .  24
           6.5.6.11  TAPE_IO_READ_RECORD (FORCE_RECORD_ZERO_FLAG, 
                     RECORD_ADDRESS)  . . . . . . . . . . . . . . . .  25
           6.5.6.12  TAPE_IO_UNLOAD . . . . . . . . . . . . . . . . .  25
           6.5.6.13  TAPE_IO_NEXT_VOLUME  . . . . . . . . . . . . . .  25
           6.5.6.13.1 NEXT_TAPE_FOREIGN . . . . . . . . . . . . . . .  25
           6.5.6.13.1.1 NEXT_TAPE_COMMAND_OPER  . . . . . . . . . . .  25
           6.5.6.13.2 NEXT_TAPE_LABELED . . . . . . . . . . . . . . .  25
           6.5.6.14  TAPE_IO_SKIP_FILE (FILES_TO_SKIP)  . . . . . . .  26
           6.5.6.14.1 SKIP_FILES_FOREIGN (NUMBER_OF_FILES_TO_SKIP)  .  26
           6.5.6.14.2 SKIP_FILES_LABELED (NUMBER_OF_FILES_TO_SKIP)  .  26
           6.5.7     DUMPER_FILE.BLI  . . . . . . . . . . . . . . . .  26
           6.5.7.1   FILE_INITIALIZE  . . . . . . . . . . . . . . . .  26
           6.5.7.2   FILE_CREATE_DIRECTORY (DIRECTORY_DESCRIPTOR) . .  26
           6.5.7.3   FILE_INITIALIZE_OUTPUT . . . . . . . . . . . . .  26
           6.5.7.4   FILE_ATTRIB_BLOCK_SIZE (BLOCK_SIZE)  . . . . . .  26
           6.5.7.5   FILE_ATTRIB_BYTE_SIZE (BYTE_SIZE)  . . . . . . .  27
           6.5.7.6   FILE_ATTRIB_FRAME_SIZE (FRAME_SIZE)  . . . . . .  27
           6.5.7.7   FILE_ATTRIB_FIRST_FREE_BYTE (FIRST_FREE_BYTE)  .  27
           6.5.7.8   FILE_ATTRIB_FIXED_HEADER_SIZE (FIXED_HEADER_SIZE) 27
           6.5.7.9   FILE_ATTRIB_RECORD_ATTRIB (RECORD_ATTRIBUTES)  .  27
           6.5.7.10  FILE_ATTRIB_RECORD_FORMAT (RECORD_FORMAT)  . . .  27
           6.5.7.11  FILE_ATTRIB_RECORD_SIZE (RECORD_SIZE)  . . . . .  27
           6.5.7.12  FILE_ATTRIB_FILE_TYPE (FILE_TYPE_TO_WRITE) . . .  27
           6.5.7.13  FILE_ATTRIB_CREATION_DTM (CREATION_DATE_TIME)  .  28
           6.5.7.14  FILE_ATTRIB_ACCESS_DTM (ACCESS_DATE_TIME)  . . .  28
           6.5.7.15  FILE_ATTRIB_GENERATION (FILE_GENERATION) . . . .  28
           6.5.7.16  FILE_ATTRIB_PROTECTION (OWNER_PROTECTION, 
                     GROUP_PROTECTION, SYSTEM_PROTECTION, 
                     WORLD_PROTECTION)  . . . . . . . . . . . . . . .  28
           6.5.7.17  FILE_ATTRIB_UIC (UIC)  . . . . . . . . . . . . .  28
           6.5.7.18  FILE_ATTRIB_NAME (FILE_DESCRIPTOR) . . . . . . .  28
           6.5.7.19  FILE_CREATE  . . . . . . . . . . . . . . . . . .  28
   DUMPER-32 Function Specificaiton                                Page 5
   Introduction                                           27 January 1986


           6.5.7.19.1 ALLOCATE_RECORD_BUFFER  . . . . . . . . . . . .  28
           6.5.7.19.2 SET_UP_FILE_NAME  . . . . . . . . . . . . . . .  29
           6.5.7.20  DUMP_BUFFER  . . . . . . . . . . . . . . . . . .  29
           6.5.7.21  FILE_WRITE_CHARACTER (CHARACTER) . . . . . . . .  29
           6.5.7.21.1 EXPAND_BUFFER . . . . . . . . . . . . . . . . .  29
           6.5.7.22  FILE_DATA_FILL (NUMBER_OF_FILL_CHARACTERS) . . .  29
           6.5.7.23  CVT_FILE_DATA (WORD_36BITS, DATA_COUNT, 
                     BYTE_FLAG) . . . . . . . . . . . . . . . . . . .  29
           6.5.7.24  FILE_CLOSE . . . . . . . . . . . . . . . . . . .  29
           6.5.7.25  INITIALIZE_XAB_LIST  . . . . . . . . . . . . . .  29
           6.5.7.26  LINK_XAB_BLOCK_IN (XAB_TO_LINK_IN) . . . . . . .  30
           6.5.8     DUMPER_LIST.BLI  . . . . . . . . . . . . . . . .  30
           6.5.8.1   LIST_INITIALIZE  . . . . . . . . . . . . . . . .  30
           6.5.8.2   LIST_OPEN  . . . . . . . . . . . . . . . . . . .  30
           6.5.8.3   LIST_CLOSE . . . . . . . . . . . . . . . . . . .  30
           6.5.8.4   LIST_LINE (LINE_DESC)  . . . . . . . . . . . . .  30
           6.5.8.5   LIST_FAO (CTRSTR)  . . . . . . . . . . . . . . .  30
           6.5.8.6   LIST_BLANK (LINE_COUNT)  . . . . . . . . . . . .  31
           6.5.8.7   LIST_36_BIT_VERSION (VER_MAJOR, VER_MINOR, 
                     VER_EDIT, VER_WHO, VER_DESC, VER_LENGTH) . . . .  31
   DUMPER-32 Function Specificaiton                                Page 6
   Introduction                                           27 January 1986


   1  Introduction

   This utility will provide  a  means  of  reading  magnetic  tapes  written  by
   DUMPER-20  and BACKUP-10 on a VAX/VMS system.  The utility is invoked by a DCL
   command line.



   2  Related Documents

   The following are various documents  that  related  to  the  support  of  this
   utility.

        1.  Command parser function specification.

        2.  Dumper and Backup Tape Formats specification.




   3  Document Revision History

   The following is the revision history of this document.

        1.  Draft 1 - Create this document.
|  
|       2.  Draft 2 - First inhouse review.




   4  Modules

   The utility is comprised of various BLISS-32 modules and a .MSG  file.   These
   modules are linked together to provide the single utility.
|  
|       1.  DUMPER.BLI -  Main  routine.   Contains  the  calls  to  the  command
|           processing, and some general subroutines.

        2.  DUMPER.CLD - Command line definition file.  This is the file that  is
            used with the DCL command SET COMMAND to define the command to invoke
            this utility.

        3.  DUMPER_DRIVER.BLI - Main restore and list driver routines.

        4.  DUMPER_CVT.BLI - Main data type conversion routines.  Converts  36bit
            text, numbers, bytes, etc into text descriptors, characters and valid
|           32bit data.

        5.  DUMPER_LIST.BLI - Main listing routines.

        6.  DUMPER_TAPE_IO.BLI - Tape I/O processing  routines.   These  are  the
            routines that will read the data from the tape.
   DUMPER-32 Function Specificaiton                                Page 7
   Modules                                                27 January 1986


        7.  DUMPER_FILE.BLI - File output routines.  These routines  provide  for
            setting of the various file attributes, creating the file and writing
            the data into the file.

        8.  DUMPER_BACKUP_TAPE.BLI - This module provides the basic  support  for
            reading a BACKUP-10 written tape.

        9.  DUMPER_DUMPER_TAPE.BLI - This module provides the basic  support  for
            reading a DUMPER-20 written tape.

       10.  CHARACTER_DEFINITIONS.REQ   -   Symbol   definitions   for    control
            characters.

       11.  DUMPER_SYMBOLS.REQ - Macro and symbol definitions used in all of  the
            various modules found in the utility.

       12.  TAPE_FORMAT.REQ - Macros and symbols that  define  the  format  of  a
            tape.

       13.  DUMPER_ERROR.MSG - Message file  that  contains  all  of  the  DUMPER
            specific messages that are signalled.


   Each of the BLISS-32 modules is compiled via the BLISS  DCL  command  and  the
   message  file  is  compiled  via the MESSAGE DCL command.  The following is an
   example of how to compile the various modules.

   $ !
   $ ! Command file to build the DUMPER-32 program
   $ !
   $ MESSAGE DUMPER_ERROR.MSG
   $ BLISS DUMPER.BLI
   $ BLISS DUMPER_DRIVER.BLI
   $ BLISS DUMPER_BACKUP_TAPE.BLI
   $ BLISS DUMPER_DUMPER_TAPE.BLI
   $ BLISS DUMPER_FILE.BLI
   $ BLISS DUMPER_CVT.BLI
   $ BLISS DUMPER_TAPE_IO.BLI

   Once the modules have been compiled, they can  be  linked  together  with  the
   following command line.

   $ LINK DUMPER, DUMPER_DRIVER, DUMPER_BACKUP_TAPE, DUMPER_DUMPER_TAPE, -
    DUMPER_FILE, DUMPER_CVT, DUMPER_TAPE_IO, PARSER, PARERR, DUMPER_ERROR


                                   Command Parser

           The modules PARSER and PARERR are part of the  command  parser
           and  are  discussed in detail in the Command Parser Functional
           Specification.
   DUMPER-32 Function Specificaiton                                Page 8
   Command Interface                                      27 January 1986


   5  Command Interface

   This utility is invoked via a DCL command.  The DCL command is defined by  the
   module  DUMPER.CLD.   The  DCL command defined by the .CLD file is DUMPER.  To
   define the command the following DCL command is used.

       $ SET COMMAND DUMPER /OUTPUT

   Once that is done, the syntax of the command to restore files is:

       $ DUMPER /Qualifiers Input-specification Output-specification

   The command syntax to get a listing of the BACKUP-10/DUMPER-20 tape is:

       $ DUMPER /Qualifiers Input-specification



   5.1  Input-specification

   The "input-specification" specifies the tape device to  use  for  reading  the
   BACKUP-10/DUMPER-20  tape.   This would normally be a standard VMS tape device
   (eg.  MFA0:).



   5.2  Output-specification

   The "output-specification" along with the file  specification  from  the  tape
   will  be  used to produce the file specifications used for restoring the files
   from tape.  The output-specification  will  override  any  of  the  tape  file
   specifications.

   If the user wanted to restore  a  file  from  a  tape  keeping  the  name  and
   extension  from  the  tape, the output specification should just be the device
   and the directory of where to store the file.  For example if the file on  the
   tape  was  PS:<DOCUMENTATION>RFC940.TXT.1 and the user wanted to restore it as
   DISK$DOC:[RFC]RFC940.TXT;1  the  output  specification  would  just   be   the
   DISK$DOC:[RFC].



   5.3  Qualifiers

   The following are the legal qualifiers for the DUMPER command.



   5.3.1  BLOCKING_FACTOR=number

   This qualifiers specifies the number of logical blocks that were  written  per
   physical  tape  block.  Some versions of BACKUP-10 and DUMPER-20 allow for the
   writing of more than one logical block per physical tape block  for  increased
   performance.  The default for this qualifier is a blocking factor of 1.
   DUMPER-32 Function Specificaiton                                Page 9
   Command Interface                                      27 January 1986


   5.3.2  CREATEDIRECTORY

   This qualifier will flag that directories are to be created when the files are
   restored.  This will allow for the restoring of a DECsystem-10 or DECSYSTEM-20
   tape with the same directory structure to a VAX/VMS system.  Directories  will
   not be created by default.



   5.3.3  FORMAT[=Keyword]

   This qualifier will specify the type of tape that is being read.  The  default
   for this qualifier is INTERCHANGE.



   5.3.3.1  INTERCHANGE

   The format of  the  tape  is  either  BACKUP  INTERCHANGE  mode  or  DUMPER-20
   INTERCHANGE mode.



   5.3.3.2  BACKUP

   The format of the tape is BACKUP-10 format.



   5.3.3.3  DUMPER

   The format of the tape is DUMPER-20 format.



   5.3.4  LIST[=Output-file]

   This will specify that  a  listing  of  the  tape  is  to  be  made.   If  the
   "Output-file"  is  not  specified then the listing of the tape will be done to
   the user's terminal.



   5.3.5  LOG[=Keyword]

   The LOG qualifier will cause events to be logged to the  user  terminal.   The
   events  that  are  logged  are  the creation of files.  The default keyword is
   FILES.
   DUMPER-32 Function Specificaiton                               Page 10
   Command Interface                                      27 January 1986


   5.3.5.1  FILES

   All files that are restored are logged to the user's terminal.  The  tape  and
   disk file specifications will be output.



   5.3.5.2  ALL

   All events will be logged to the  user  terminal.   This  includes  both  file
   restoration and directory creation.



   5.3.5.3  DIRECTORIES

   Any directories that are created will be logged to the user's terminal.



   5.3.6  REWIND

   When the REWIND qualifier is present, the tape will rewind  before  attempting
   to read the information from the tape.



   5.3.7  SELECT[=Tape-specifications]

   This option specifies which files on  the  tape  are  to  be  restored.   This
   qualifier  is  similar  to  the  VMS BACKUP qualifier with the same name.  The
   default tape specification is "*.*.*".



   5.3.8  SKIP[=Number]

|  The default if the qualifier is given without an argument is to  skip  1  save
|  set.
|  
|  
|  
|  5.3.9  SSNAME[=Save-set-name]
|  
   This qualifier will specify the save set name  that  the  file(s)  are  to  be
|  restored  from.   The default save set name is "ALL" if the qualifier is given
|  without an argument of if the /LIST qualifier is given.  If the  qualifier  is
|  not given, then the files will be restored from the next save set.
   DUMPER-32 Function Specificaiton                               Page 11
   Command Interface                                      27 January 1986


   5.4  Examples

   The following are examples of using the various qualifiers.



   5.4.1  Getting a listing of a tape

   The following command will request that the utility produce a listing  of  the
   information on the tape and store the output into the file BACKUP_TAPE.LIS.

       $ DUMPER /LIST=BACKUPTAPE.LIS MFA0:

   If a listing on the terminal is required then the file  specification  can  be
   left off of the command line.

       $ DUMPER /LIST MTA0:



   5.4.2  Restoring selected files

   The following example show how to select specific files from the tape  and  to
   restore them to your area.

       $ DUMPER MRA0:/SELECT=(*.INI) SYS$CC:[RMCQUEEN]




   5.4.3  Restoring a complete tape creating directories

   The following can be used to restore a complete tape,  creating  the  complete
   directory structure that was saved on the tape.

       $ DUMPER MRA0:  DISK$USER0:/CREATE

   If a specific disk structure is to be restored from the tape, then it  can  be
   selected.   The  following example show the restoring of the structure PS:  to
   the disk structure DISK$USER1:.

       $ DUMPER MFA0:/SELECT=(PS:[*]) DISK$USER1:/CREATE



   6  Functional description

   This section will give an overview of how the utility works, the major  macros
   that  are used in the utility and the routines found in the different modules.
   It is expected that the reader  is  familiar  with  either  the  BACKUP-10  or
   DUMPER-20 utilities.
   DUMPER-32 Function Specificaiton                               Page 12
   Functional description                                 27 January 1986


   6.1  Overview

   The main logic in DUMPER is a two step processes.  The first step is  to  call
   the  command  processor  to get the command and then to call the DUMPER_DRIVER
|  module to process the command.  The command processing is handled by a general
|  command processor used by both the ALTER utility and the DUMPER utility.

   The driver module proceeds in a tape independent manner, since both the BACKUP
   and DUMPER tape formats are structured in a similar manner.  The tape specific
   routines are called via a dispatch  table  for  the  specific  routines.   The
   current  dispatch vector is stored in OWN storage and is called PROCESS_VECTOR
   with a FIELD definition of ROUTINE_DISPATCH.

   The driver module will  first  call  the  proper  tape  format  initialization
   routine  and  then  set  up  the  defaults  for the save set name and blocking
   factor.  If there are any save sets to skip, the low  level  tape  routine  is
   called to skip the save sets.  Once all of that is accomplished, the main loop
   is entered to find the correct save set and  process  it.   The  save  set  is
   processed by calling the routine to restore it or to list it.

   Once a save set to restore  is  found,  the  save  set  will  be  searched  to
   determine  if  any  of  the  files  in  the  save set match the selection file
   specifications.  If  a  tape  file  specification  matches  a  selection  file
   specification, then the file is restored.
|  
|  A save set is listed by calling the format dependent routines to list  a  tape
   record.  Once a record is listed, the next record is read and listed until the
   end of the tape or a fatal error occurs.
|  
|  
|  
|  6.2  Converting file formats
|  
|  This utility will attempt to make a proper "guess" at how  a  file  from  tape
|  should  be  written  on a VAX/VMS system.  The next two sections will describe
|  the methods of making the "guess" for a file.
|  
|  
|  
|  6.2.1  BACKUP-10 tapes
|  
|  As of version 5 of BACKUP-10 and version 7.03 of TOPS-10, there may be  enough
|  real  information  on  file format to properly restore a file on a VMS system.
|  The new information in the file's RIB that BACKUP-10 saves and DUMPER-32  uses
|  is:   Carriage  Control  (RB.DCC field in .RBTYP word), logical data byte size
|  (RB.BSZ in .RBBSZ), physical data frame size (RB.FSZ in .RBBSZ), fixed  header
|  size (RB.HSZ in .RBBSZ), record format (RB.RFM in .RBBSZ), record organization
|  (RB.RFO in .RBBSZ), record size (RB.RSZ in .RBRSZ) and block size  (RB.BLS  in
|  .RBRSZ).   If  this  information  is  not  present in the file's RIB, then the
|  pre-7.02 method of determining the file characteristics is used.
|  
|  Previous to version  5  of  BACKUP  and  version  7.03  of  TOPS-10  the  only
|  information  available  to  determine the type of a file was the mode that the
|  file was written in (RB.MOD field in the .RBPRV word of the RIB).
   DUMPER-32 Function Specificaiton                               Page 13
   Functional description                                 27 January 1986


|  If the file byte size is 7 bit bytes, then it is assumed that the byte size is
|  7, frame size is 7, no record size, no fixed header size, the record format is
|  variable and the record attribute is set to implied carriage returns.
|  
|  If the file byte size is 8 bit bytes, then it is assumed that the byte size is
|  8,  frame size is 8.  The record size is set to 510 byte records.  There is no
|  fixed header size.  The record format is variable and with no attributes.
|  
|  If the file byte size is 36 bit bytes, then it is assumed that the  byte  size
|  is  36,  frame  size  is 36.  There is no fixed record size, and there are not
|  fixed headers on the records.  The record format is variable (FAB$C_VAR)  with
|  no  record attributes.  The 36 bit data frames are stored into the output file
|  as 4 7-bit bytes followed by a single 8-bit byte.  This is the same as if  the
|  file were an ASCII file, except that the last byte will get bit 35 as the high
|  order bit in the output byte.
|  
|  If the byte size is not 7, 8 or 36 then the byte size and frame size  will  be
|  set  to  what is in the FDB.  There will be no record size set or fixed record
|  header.  The record format will be variable length and the  record  attributes
|  will not be given.
|  
|  
|  
|  6.2.2  DUMPER-20 tapes
|  
|  The format of DUMPER-20 files is determined from the byte size stored  in  the
|  file's  FDB.   If  the  file byte size is 0 or 7 bit bytes, then it is assumed
|  that the byte size is 7, frame size is 7.  There would be no record  size,  or
|  fixed  header  for  the  file.  The record format will variable and the record
|  attribute is set to implied carriage returns.
|  
|  If the file byte size is 8 bit bytes, then it is assumed that the byte size is
|  8,  frame  size  is 8.  The record size will be 510 byte records with no fixed
|  headers.  The record format would be variable with no record attributes.
|  
|  If the file byte size is 36 bit bytes, then it is assumed that the  byte  size
|  is  36, frame size is 36, record size is 0, there is no fixed header size, the
|  record format is variable and has no  record  attributes.   The  36  bit  data
|  frames  are  stored into the output file as 4 7-bit bytes followed by a single
|  8-bit byte.  This is the same as if the file were an ASCII file,  except  that
|  the last byte will get bit 35 as the high order bit in the output byte.
|  
|  If the byte size is not 0, 7, 8 or 36 then the byte size and frame  size  will
|  be  set  to  what  is  in  the FDB.  There will be no record size set or fixed
|  record header.  The record format will  be  variable  length  and  the  record
|  attributes will not be given.
|  
|  
|  
|  6.2.3  Non-7, 8, or 36-bit bytes
|  
|  When the BACKUP/DUMPER tape contains a file that indicates the data is not  in
|  7-bit,  8-bit  or  36-bit  bytes  the  output  data will be stored in the next
|  highest VAX storage unit that will accomidate it.  This means sizes 1 to 6 are
   DUMPER-32 Function Specificaiton                               Page 14
   Functional description                                 27 January 1986


|  stored  in a byte (8-bits, 9 to 16 are stored in a word (16 bits) and 17 to 32
|  are stored in a long word (32 bits), and 33 to 35 are treated as if they  were
|  36 bit frames.



   6.3  Known Problems/Restrictions

   The following are the known problems and  restrictions  for  the  DUMPER  tape
   utility.

        1.  Files that are written as 36bit frames will be restored  without  any
            record attributes.




   6.4  Libraries and Required files

   The source modules use the standard VMS libraries (STARLET)  and  three  local
   require  files.  The local libraries provide local definitions and macros used
   in the utility



   6.4.1  CHARACTER_DEFINITIONS.REQ

   This require file provides standard names for the various  control  characters
   that can be encountered in the processing of tape files.



   6.4.2  DUMPER_SYMBOLS.REQ

   This file provides macro definitions  and  symbols  for  use  in  all  of  the
   modules.   The  module defines fields for the representation of 36-bit data in
   the 32-bit words and vectors, fields for the frames from the tape, fields  for
   calling  the  BACKUP/DUMPER  specific  routines  and  others.   The  following
   describe some of the macros found in this module.



   6.4.2.1  $BYTE, $WORD, $LONGWORD

   This macros are single entry vectors.  They are useful for using as  REF's  to
   longwords, words and bytes.



   6.4.2.2  $DESCRIPTOR_DECL and $DESCRIPTOR_INIT

   These macros are used to define and initialize a string descriptor.
   DUMPER-32 Function Specificaiton                               Page 15
   Functional description                                 27 January 1986


   6.4.2.3  $IOSB_DECL

   This macro is used to define an IO  status  block  as  used  with  QIO  system
   service  calls.   It  will  declare the block and associate with the block the
   proper fields for fetching information from the block.  The  fields  that  are
   defined are:  IOSB_START, IOSB_STATUS, IOSB_COUNT and IOSB_DEVDEPEND.



   6.4.3  TAPE_FORMAT.REQ

   This module contains the macro definitions that describe  the  format  of  the
   various  tape  blocks.   It provides the record formats and symbol definitions
   for the values found in various tape files.

|  Each entry in the macros has a standard format.   The  format  for  entry  is:
|  Field  name,  word  offset, field offset, field size, storage address, storage
   size in bytes, conversion routine and any flags associated  with  this  entry.
   The following is a brief list of some of the macros found in the module.

        1.  BACKUP_STANDARD_RECORD_HEADER

        2.  BACKUP_T_LBL_RECORD

        3.  BACKUP_T_BEG_RECORD

        4.  BACKUP_T_UFD_RECORD

        5.  BACKUP_T_FIL_RECORD

        6.  BACKUP_NON_DATA_BLOCK_HEADER

        7.  BACKUP_NAME_BLOCK

        8.  BACKUP_FILE_BLOCK

        9.  BACKUP_DIRECTORY_BLOCK

       10.  BACKUP_SYSTEM_NAME

       11.  BACKUP_SAVE_SET_NAME

       12.  DUMPER_STANDARD_RECORD_HEADER

       13.  DUMPER_SAVESET_HEADER_RECORD

       14.  DUMPER_SAVESET_BUFFER

       15.  DUMPER_FILE_HEADER_RECORD

       16.  DUMPER_FDB
   DUMPER-32 Function Specificaiton                               Page 16
   Functional description                                 27 January 1986


   6.5  Routines

   6.5.1  DUMPER.BLI

   DUMPER-32 is a program to read BACKUP-10  tapes  from  the  DECsystem-10s  and
   DUMPER-20 tapes from the DECSYSTEM-20s.  This program will read tapes only and
   restore the information to disk.  It will not  write  BACKUP-10  or  DUMPER-20
   tapes.

   This module contains the command tables to call  the  parser  with,  the  main
   routine that calls all of the other routines.



   6.5.1.1  DUMPER_MAIN

   This is the main routine for DUMPER-32.  It will cause the various modules  to
   be initialized and then call the correct routine to process a command.



   6.5.1.2  MATCH_FILESPEC (FILE_SPEC)

   This routine is called to determine if a file should be restored  or  skipped.
   It  will  match  the  file  specification  from the tape against the (possibly
   wildcarded) file specifications from the user's  /SELECT  qualifier.   If  the
   file spec matches, it will return true, otherwise it will return false.



   6.5.1.3  EXTRACT_FIELDS (STRING_DESC, RESULT)

   This  routine  will  return  pointers  to  the  various  part  of   the   file
   specification.



   6.5.1.4  MATCH_SINGLE_FILE (FILE_SPEC, TEMPLATE_SPEC)

   This  routine  is  called  from  MATCH_FILESPEC  to  determine  if  the   file
   specification  matches  the  template  specification.   It  will  handle  full
   wildcarded templates using both "*" and "%".



   6.5.1.5  MATCH_STRING    (STRING_LENGTH,    STRING_POINTER,    PATTERN_LENGTH,
            PATTERN_POINTER)

   This routine is called to match a field of a file spec against  the  wild-card
   pattern  for  that field.  It the field fits the pattern, it will return true,
   otherwise it returns false.  It handles both "*" as zero  or  more  characters
   and "%" as any single character.
   DUMPER-32 Function Specificaiton                               Page 17
   Functional description                                 27 January 1986


   6.5.2  DUMPER_DRIVER.BLI

   This module contains the high-level driver  for  listing  and  restoring  both
   BACKUP-10 and DUMPER-20 tapes.  It does the processing which is common to both
   formats of tape.



   6.5.2.1  DRIVER_PROCESS_COMMAND

   This routine is called by the command parser to process the  command  received
   from  the  user.   When  this  routine is called, all parameters and qualifier
   values have already been stored in their permanent  storage  locations.   This
   routine  will perform the requested action (either listing the contents of the
   tape or restoring the files), and return when the action is finished.



   6.5.2.2  CHECK_SAVE_SET_RECORD

   This routine is called to check if a save set starting at the  current  record
   should  be  restored.   The current record has already been read into the tape
   buffer.  It will call the proper low  level  routine  to  perform  the  record
   decoding  and  format specific checks, and will then decide whether to restore
   the record.



   6.5.2.3  RESTORE_SAVE_SET

   This routine is called when it  is  determined  that  a  save  set  should  be
   restored.   It  will process the entire save set, restoring all desired files.
   When this routine is called, the save set header should be in the tape buffer.



   6.5.2.4  RESTORE_FILE

   This routine is called to restore a single file.  It will call the the  proper
   low  level routines (format specific) to process the data from the file.  When
   this routine is called, the file header data must have already been  processed
   by calling the PROCESS_FILE entry and the file header record must still be the
   current tape buffer.



   6.5.2.5  LIST_SAVE_SET

   This routine is called to list a single save set.
   DUMPER-32 Function Specificaiton                               Page 18
   Functional description                                 27 January 1986


   6.5.3  DUMPER_CVT.BLI

   This module will provide the data conversion routines required to convert  the
   36 bit into something that this small machine can deal with.



   6.5.3.1  CVT_INITIALIZE

   This routine will initialize the data conversion routines.



   6.5.3.2  CVT_CONVERT_RECORD          (CONVERSION_TABLE,          RECORD_36BIT,
            INITIAL_WORD_INDEX)

   This routine is called to process a record according to the conversion  table.
   It  will  process  all  the  fields in the table, storing the results into the
   specified storage locations.



   6.5.3.3  CVT_SIXBIT_2_ASCID (WORD_36BIT,  BYTE_SIZE,  BYTE_POSITION,  STORAGE,
            STORAGE_SIZE, RECORD_BUFFER)

   This routine will convert a SIXBIT word into an ASCID string.  It will  return
   the updated descriptor.



   6.5.3.4  CVT_FETCH_7BIT_CHARACTER (ASCII_STRING, CHARACTER_OFFSET, LSN_FLAG)

   This routine will return a  character  from  the  string  pointed  to  by  the
   ASCII_STRING argument.  It will use the CHARACTER_OFFSET to determine which of
   the characters to return to the caller.



   6.5.3.5  CVT_WORD_2_LONGWORD (WORD_36BIT, BYTE_SIZE, BYTE_POSITION, LONG_WORD,
            STORAGE_SIZE, RECORD_BUFFER)

   This routine will attempt to convert a word (36-bit) into a VAX long word data
   item.   It will return an error status if the high order four bits of the word
   is non-zero.



   6.5.3.6  CVT_ASCIZ_2_ASCID    (ASCIZ_STRING,     BYTE_SIZE,     BYTE_POSITION,
            ASCID_STRING, STORAGE_SIZE, RECORD_BUFFER)

   This routine will take  the  address  of  an  ASCIZ  string  and  convert  the
   information into the ASCID descriptor that was given.
   DUMPER-32 Function Specificaiton                               Page 19
   Functional description                                 27 January 1986


   6.5.3.7  CVT_FIELD    (WORD_36BIT,    BYTE_SIZE,    BYTE_POSITION,    STORAGE,
            STORAGE_SIZE, RECORD_BUFFER)

   This routine will fetch an arbitrary data item and convert it to  a  VAX  data
   item.  This routine will only handle data that is 36bits long or 32 and less.



   6.5.3.8  CVT_BPT_2_ASCID  (WORD_36BIT,  BYTE_SIZE,   BYTE_POSITION,   STORAGE,
            STORAGE_SIZE, RECORD_BUFFER)

   This routine will convert a relative byte pointer to an ASCIZ  string  in  the
   current  tape  record  to  an  ASCID  string.  If all fields are zero, it will
   assume no string.



   6.5.3.9  CVT_UDT_2_DATE_TIME (UDT_ADDRESS, BYTE_SIZE, BYTE_POSITION,  STORAGE,
            STORAGE_SIZE, RECORD_BUFFER)

   This routine will convert a universal date/time (TOPS-10/20 format) to the VAX
   format for Date/Time.



   6.5.3.10  CVT_NEG_FIELD  (WORD_36BIT,   BYTE_SIZE,   BYTE_POSITION,   STORAGE,
             STORAGE_SIZE, RECORD_BUFFER)

   This routine will convert a negative number (36 bit) into a single long value.



   6.5.4  DUMPER_BACKUP_TAPE.BLI

   This module implements the reading of BACKUP-10 format  tapes  under  VAX/VMS.
   This  module  also contains the BACKUP-10 specific conversion routines such as
   O$NAME conversion.



   6.5.4.1  BACKUP_INITIALIZATION

   This routine will initialize the BACKUP tape processing.



   6.5.4.2  BACKUP_READ_AND_DECODE_RECORD (BLOCKING_AND_DIR_FLAG, RECORD_ADDRESS)

   This routine is called when a record has been read from a BACKUP tape.  It  is
   expected  to  perform  whatever  decoding is necessary for every record on the
   tape.  It will also return an indication  of  whether  the  record  should  be
   processed or ignored.
   DUMPER-32 Function Specificaiton                               Page 20
   Functional description                                 27 January 1986


   6.5.4.3  BACKUP_CHECK_SAVE_SET_RECORD (RECORD_ADDRESS)

   This routine is called when processing a BACKUP tape to check if  the  current
   record  is  a  save  set  header,  and if so, if the save set name matches the
   desired save set(s).



   6.5.4.4  BACKUP_PROCESS_FILE (RECORD_ADDRESS)

|  This routine is called to process a record from a BACKUP save set when  it  is
   expected  to be the first record of a file ("file header").  It will determine
   if the record is one, and if so, convert the data into more useful form.



   6.5.4.5  BACKUP_PROCESS_DATA (RECORD_ADDRESS)

   This routine is called to process a record when it is expected to  be  a  data
   record.   It  will  correctly  set  up  pointers to the actual data within the
   record.



   6.5.4.6  BACKUP_SKIP_SAVE_SET (NUMBER_TO_SKIP, RECORD_ADDRESS)

   This routine is called to skip one save set.  This  is  done  differently  for
   tapes which were written by BACKUP and those written by DUMPER.  BACKUP always
   writes tape marks  between  save  sets,  so  that  we  can  use  file  spacing
   operations to move the tape.  DUMPER does not write the tape marks, so that we
   actually have to read the tape to find the save set header records!



   6.5.4.7  BACKUP_LIST_RECORD (RECORD_ADDRESS)

   This routine will list a single BACKUP format record.  It is called  once  for
   each  record  in  a  save set.  When the end of a save set is reached, it will
   return an indication that the record was the last in the save set.



   6.5.4.8  CVT_F_PTH_2_ASCID  (WORD_36BIT,  BYTE_SIZE,  BYTE_POSITION,  STORAGE,
            STORAGE_SIZE, RECORD_BUFFER)

   This routine will convert the path in the T$FIL block  on  the  tape  into  an
   ASCID  string.   This routine will use the CVT_FETCH_7BIT_CHARACTER routine to
   read the actual information from the block.
   DUMPER-32 Function Specificaiton                               Page 21
   Functional description                                 27 January 1986


   6.5.4.9  CVT_PATH_2_ASCID  (WORD_36BIT,  BYTE_SIZE,  BYTE_POSITION,   STORAGE,
            STORAGE_SIZE, RECORD_BUFFER)

|  This routine will convert a path from an O$NAME block to an ASCID string.



   6.5.4.10  CVT_PATH_OR_F_PTH_2_ASCID   (RECORD_BUFFER,   BYTE_SIZE,    STORAGE,
             STORAGE_SIZE, GET_TYPE_RTN)

   This routine is called  by  both  CVT_F_PTH_2_ASCID  and  CVT_PATH_2_ASCID  to
   convert  a backup style path specification to an ASCII string descriptor.  The
   caller supplies the routine which picks up the item type, length and  position
   of first character.



   6.5.4.11  CVT_BACKUP_FILE_TYPE

   This routine is called to determine the file  type  that  should  be  used  in
   writing  the  current file from the tape.  It will determine this based on the
   information stored in the file attributes block (O$FILE).  The best choice for
   the  file  type  will be based on the file byte size stored in the A$FBSZ byte
   size field.  Since this field is new with version 7.03 of TOPS-10 and  version
   5  of BACKUP, we cannot count on using it.  If the byte size field is zero and
   the file data type field is also zero, we must base the file  type  on  A$BSIZ
   and/or  A$MODE.   Since this has never been a reliable way of determining what
   type of data is in the file, we may need to provide a  way  for  the  user  to
   either override our default action or ask him for each file.



   6.5.4.12  CVT_PROT (PROT_FIELD)

   This routine will convert one field of  a  file  protection  to  the  bit  map
   required by VMS.



   6.5.4.13  CVT_PROT_2_ASCIC (PROT_STRING, PROT_BINARY)

   This routine is called to return the string which corresponds  to  the  BACKUP
   format binary protection.



   6.5.5  DUMPER_DUMPER_TAPE.BLI

   This module implements the reading of DUMPER-20 format tapes under VAX/VMS.
   DUMPER-32 Function Specificaiton                               Page 22
   Functional description                                 27 January 1986


   6.5.5.1  DUMPER_INITIALIZATION

   This routine will initialize the DUMPER tape processing.



   6.5.5.2  DUMPER_READ_AND_DECODE_RECORD (BLOCKING_AND_DIR_FLAG, RECORD_ADDRESS)

   This routine is called when a record has been read from a DUMPER tape.  It  is
   expected  to  perform  whatever  decoding is necessary for every record on the
   tape.  It will also return an indication  of  whether  the  record  should  be
   processed or ignored.



   6.5.5.3  DUMPER_CHECK_SAVE_SET_RECORD (RECORD_ADDRESS)

   This routine is called when processing a DUMPER tape to check if  the  current
   record  is  a  save  set  header,  and if so, if the save set name matches the
   desired save set(s).



   6.5.5.4  DUMPER_PROCESS_FILE (RECORD_ADDRESS)

|  This routine is called to process a record from a DUMPER save set when  it  is
   expected  to be the first record of a file ("file header").  It will determine
   if the record is one, and if so, convert the data into more useful form.



   6.5.5.5  DUMPER_PROCESS_DATA (RECORD_ADDRESS)

   This routine is called to process a record when it is expected to  be  a  data
   record.   It  will  correctly  set  up  pointers to the actual data within the
   record.



   6.5.5.6  DUMPER_SKIP_SAVE_SET (NUMBER_TO_SKIP, RECORD_ADDRESS)

   This routine is called to skip a number of save sets.  It will read  the  tape
   in the correct direction looking for save set header records.



   6.5.5.7  DUMPER_LIST_RECORD (RECORD_ADDRESS)

   This routine is called to list a single DUMPER format record.   It  is  called
   once  for each record in a save set.  When the end of the save set is reached,
   it will return an indication that the record was the last one in the save set.
   DUMPER-32 Function Specificaiton                               Page 23
   Functional description                                 27 January 1986


   6.5.5.8  CVT_DUMPER_FILE_TYPE

   This routine is called to determine the file  type  that  should  be  used  in
   writing  the  current file from the tape.  It will determine this based on the
   information stored in the file attributes block.



   6.5.6  DUMPER_TAPE_IO.BLI

|  This module implements the tape I/O processing for reading  the  DUMPER-20  or
|  BACKUP-10 tapes.  This module is the only module that does tape I/O.



   6.5.6.1  TAPE_ACCESS

   This routine will request access to a tape drive file from the  magnetic  tape
   ACP.  It assumes that the tape drive channel has already be assigned.



   6.5.6.2  TAPE_DEACCESS

   This routine will deaccess a tape file.  It will  return  the  system  service
   completion  code  to  the  caller.   It assumes that the tape drive channel is
   open.



   6.5.6.3  TAPE_REWIND

   This routine will position the tape to the beginning of the volume set.



   6.5.6.4  READ_TAPE_BLOCK (TAPE_BUFFER_INDEX)

   This routine will force the next tape block to be read.  The routine will wait
   until  the  QIO  finishes  before returning to the caller.  The buffer used is
   specified by the argument TAPE_BUFFER_INDEX which is an offset into the buffer
   table.



   6.5.6.5  READ_TAPE_BLOCK_BACKWARDS (TAPE_BUFFER_INDEX)

   This routine will force the previous tape block to be read.  The routine  will
   wait  until  the QIO finishes before returning to the caller.  The buffer used
   is specified by the argument TAPE_BUFFER_INDEX which is  an  offset  into  the
   vector of buffer addresses.
   DUMPER-32 Function Specificaiton                               Page 24
   Functional description                                 27 January 1986


   6.5.6.6  DEALLOCATE_BUFFERS

   This routine will deallocate the buffers for  the  tape  I/O.   It  will  loop
   through the vector BUFFER_ADDRESS and return any buffers that are allocated.



   6.5.6.7  TAPE_IO_OPEN (DEVICE_DESCRIPTOR, BLOCKING_FACTOR, BLOCK_SIZE)

   This routine will open the tape device.  The routine will  first  insure  that
   the  device  specified  is really a tape drive, then open a channel to it.  It
   will optionally call the TAPE_ACCESS routine if the tape  is  labeled,  rewind
   the tape if requested and then allocate the buffers for the tape.



   6.5.6.7.1  OPEN_TAPE_DRIVE (DEVICE_NAME)

   This routine will open the tape drive  for  processing.   It  will  store  the
   channel into the OWN storage TAPE_CHANNEL.



   6.5.6.7.2  ALLOCATE_BUFFERS (SIZE_TO_ALLOCATE)

   This  routine  will  allocate  all  of  the  buffers  required  for  the  tape
   processing.   The  address of the buffers will be stored in the BUFFER_ADDRESS
   vector and mark that the buffers do not contain valid data  (BUFFER_VALID  set
   to false).



   6.5.6.8  TAPE_IO_CLOSE (DEVICE_DESCRIPTOR)

   This routine will release any buffers that were  assigned  by  TAPE_OPEN,  and
   deassign  the tape channel.  If the tape is labeled it will call TAPE_DEACCESS
   to first deaccess the file on the tape before closing the channel.



   6.5.6.9  TAPE_IO_PEEK_RECORD (RECORD_ADDRESS)

   This routine will peek ahead at the next tape  record.   It  will  return  the
   address  of  the  record  to the caller.  It will read the buffer and mark the
   buffer as being valid in the BUFFER_VALID vector.  The address of  the  buffer
   read will be returned to the caller.



   6.5.6.10  TAPE_IO_READ_BACKWARDS_RECORD               (FORCE_RECORD_ZERO_FLAG,
             RECORD_ADDRESS)

   This routine will cause a tape record to be read backwards.  It will flush any
   records    that    have   been   peeked   and   read   the   tape   backwards.
   DUMPER-32 Function Specificaiton                               Page 25
   Functional description                                 27 January 1986


   FORCE_RECORD_ZERO_FLAG is a flag to determine if the  record  to  be  returned
   should be record 0 or not.  If true will return the next logical record 0 in a
   blocked tape.  RECORD_ADDRESS is the address  of  the  buffer  that  was  read
   (Returned to caller).



   6.5.6.11  TAPE_IO_READ_RECORD (FORCE_RECORD_ZERO_FLAG, RECORD_ADDRESS)

   This routine will return the address of the next tape record.  It will  handle
   the  blocked  tapes,  by  advancing  with  in a physical block if required and
   skipping to the next physical block when all the records  are  read  from  the
   physical  block.   FORCE_RECORD_ZERO_FLAG is a flag to determine if the record
   to be returned should be record 0 or  not.   If  true  will  return  the  next
   logical  record  0  in  a  blocked tape.  RECORD_ADDRESS is the address of the
   record of data we just read.



   6.5.6.12  TAPE_IO_UNLOAD

   This routine will cause the tape to be  unloaded  from  the  tape  drive.   It
   assumes that the drive is mounted foreign.  If the tape is not mounted foreign
   the routine will just return SS$_NORMAL and do nothing.



   6.5.6.13  TAPE_IO_NEXT_VOLUME

   This routine will force the tape being processed to skip to the next volume in
   the volume set.  It assumes that the tape is already opened and accessed.



   6.5.6.13.1  NEXT_TAPE_FOREIGN

   This routine will request that the next volume for a tape mounted  foreign  be
   mounted.



   6.5.6.13.1.1  NEXT_TAPE_COMMAND_OPER - This routine will ask the  operator  to
   mount  the  take  tape on the tape drive.  It will first open a mailbox to get
   the response from the operator, then do a $SNDOPR system  service  to  request
   the processing and then read the command that we got.



   6.5.6.13.2  NEXT_TAPE_LABELED

   This routine will request that the next volume in the volume set  be  mounted.
   This routine is called for labeled tapes only.
   DUMPER-32 Function Specificaiton                               Page 26
   Functional description                                 27 January 1986


   6.5.6.14  TAPE_IO_SKIP_FILE (FILES_TO_SKIP)

   This routine will be called to skip N files on the tape.  For tapes  that  are
   mounted  foreign,  we  will  just  use the system service to do the work.  For
   labeled tapes we will first determine the file number we are currently at  and
   add  the number of files to skip to the file number and then attempt to access
   that file.



   6.5.6.14.1  SKIP_FILES_FOREIGN (NUMBER_OF_FILES_TO_SKIP)

   This routine will skip N files on a tape that is mounted foreign.  It will use
   the system QIO function IO$_SKIPFILE to accomplish this.



   6.5.6.14.2  SKIP_FILES_LABELED (NUMBER_OF_FILES_TO_SKIP)

   This routine will  skip  files  on  a  labeled  tape.   It  will  do  this  by
   determining the current file number and then deaccessing the tape.  After that
   is done, it will access the new  file  by  calculating  the  new  file  number
   (old_file_number + number_files_to_skip).



   6.5.7  DUMPER_FILE.BLI

   6.5.7.1  FILE_INITIALIZE

   This routine will initialize the file processing module for DUMPER-32.



   6.5.7.2  FILE_CREATE_DIRECTORY (DIRECTORY_DESCRIPTOR)

   This routine will create the directories that are required in order to restore
   the file we are currently processing.



   6.5.7.3  FILE_INITIALIZE_OUTPUT

   This routine will initialize the per file output.  It will reset  the  various
   RMS  blocks  in  the low segment and will reset any and all variables used for
   File output.



   6.5.7.4  FILE_ATTRIB_BLOCK_SIZE (BLOCK_SIZE)

   This routine will set the logical block size for the file that we are about to
   restore to the user's disk area.
   DUMPER-32 Function Specificaiton                               Page 27
   Functional description                                 27 January 1986


   6.5.7.5  FILE_ATTRIB_BYTE_SIZE (BYTE_SIZE)

   This routine is called to set the byte size for the next file.  The byte  size
   is  the actual number of data bits used in each frame in the file.  It must be
   less than or equal to the frame size.



   6.5.7.6  FILE_ATTRIB_FRAME_SIZE (FRAME_SIZE)

   This routine is called to set the size (in bits) of the frames in  which  data
   bytes are stored.



   6.5.7.7  FILE_ATTRIB_FIRST_FREE_BYTE (FIRST_FREE_BYTE)

   This routine will set the first free byte available  in  the  file.   It  will
   store the information that was found in the BACKUP tape file information.



   6.5.7.8  FILE_ATTRIB_FIXED_HEADER_SIZE (FIXED_HEADER_SIZE)

   This routine will set the size of the fixed header.  The size is the number of
   bytes in the header.



   6.5.7.9  FILE_ATTRIB_RECORD_ATTRIB (RECORD_ATTRIBUTES)

   This routine will set the  record  attributes  in  the  RMS  block.   It  will
   overwrite the default value that is stored in the block.



   6.5.7.10  FILE_ATTRIB_RECORD_FORMAT (RECORD_FORMAT)

   This routine will set the RMS record format to use writing the data  into  the
   file.



   6.5.7.11  FILE_ATTRIB_RECORD_SIZE (RECORD_SIZE)

   This routine will set the record size into the RMS blocks from the information
   supplied on the BACKUP tape.



   6.5.7.12  FILE_ATTRIB_FILE_TYPE (FILE_TYPE_TO_WRITE)

   This routine will set the type of file to create.  It will be called with  the
   FILE_TYPE_xxxx  symbols  as  the argument.  See DUMPER_SYMBOLS for the various
   DUMPER-32 Function Specificaiton                               Page 28
   Functional description                                 27 January 1986


   file types.



   6.5.7.13  FILE_ATTRIB_CREATION_DTM (CREATION_DATE_TIME)

   This routine will set the creation date/time attribute for the  file  that  is
   being created.



   6.5.7.14  FILE_ATTRIB_ACCESS_DTM (ACCESS_DATE_TIME)

   This routine will store the last access date/time in the  RMS  block  for  the
   $CREATE call.



   6.5.7.15  FILE_ATTRIB_GENERATION (FILE_GENERATION)

   This routine will set the file generation for the file about to be created.



   6.5.7.16  FILE_ATTRIB_PROTECTION     (OWNER_PROTECTION,      GROUP_PROTECTION,
             SYSTEM_PROTECTION, WORLD_PROTECTION)

   This routine will set the output file protection.



   6.5.7.17  FILE_ATTRIB_UIC (UIC)

   This routine will set the owner UIC for the file that is being created.



   6.5.7.18  FILE_ATTRIB_NAME (FILE_DESCRIPTOR)

   This routine will set the file name to use for the creation of the file.



   6.5.7.19  FILE_CREATE

   This routine will create the output  file.   This  routine  assumes  that  the
   FILE_ATTRIB_xxx routines have already been called.



   6.5.7.19.1  ALLOCATE_RECORD_BUFFER

   This routine will allocate the buffer for the user's record.  It will use  the
   value from the tape (if there is one) or it will make a guess.
   DUMPER-32 Function Specificaiton                               Page 29
   Functional description                                 27 January 1986


   6.5.7.19.2  SET_UP_FILE_NAME

   This routine  will  set  up  for  the  file  creation.   It  will  create  any
   directories  that  need  creating,  beat the file specification into something
   that VMS will approve of, etc.



   6.5.7.20  DUMP_BUFFER

   This routine will dump the current record to disk.  It doesn't care what  type
   of file you are writing, unlike FILE_DUMP.



   6.5.7.21  FILE_WRITE_CHARACTER (CHARACTER)

   This routine will store a character into the  buffer  to  be  written  to  the
   output file.



   6.5.7.21.1  EXPAND_BUFFER

   This routine will expand  the  ASCII  character  buffer.   It  will  move  the
   characters from the current buffer to the next buffer.



   6.5.7.22  FILE_DATA_FILL (NUMBER_OF_FILL_CHARACTERS)

   This routine will write fill characters to the output file.  It will be called
   with the number of characters to write into the file.



   6.5.7.23  CVT_FILE_DATA (WORD_36BITS, DATA_COUNT, BYTE_FLAG)

   This routine will take the data from the tape buffer and  write  it  into  the
   file.  This routine will do the three different file data conversions.



   6.5.7.24  FILE_CLOSE

   This routine will close the file that we have created.



   6.5.7.25  INITIALIZE_XAB_LIST

   This routine is called to initialize the XAB list.  It will clear the pointers
   in the XAB blocks.
   DUMPER-32 Function Specificaiton                               Page 30
   Functional description                                 27 January 1986


   6.5.7.26  LINK_XAB_BLOCK_IN (XAB_TO_LINK_IN)

   This routine will link in a new XAB block into the XAB chain.  The  new  block
   to link in will be the XAB_TO_LINK_IN argument.



   6.5.8  DUMPER_LIST.BLI

   This module implements the tape listing routines.



   6.5.8.1  LIST_INITIALIZE

   This routine will initialize the listing processing for DUMPER-32.



   6.5.8.2  LIST_OPEN

   This routine is called to open the listing file requested by the user.  If  no
   /LIST  switch was given, it will just return, otherwise it will open the given
   file (using a default of SYS$OUTPUT).



   6.5.8.3  LIST_CLOSE

   This routine is called to close the file being used for /LIST  (if  any).   It
   will just call RMS to close the file.



   6.5.8.4  LIST_LINE (LINE_DESC)

   This routine will write a single line (record) to the  listing  file.   It  is
   called with the descriptor for the line to be written.  If the listing file is
   not open, it will output  it  to  SYS$OUTPUT  by  use  of  the  LIB$PUT_OUTPUT
   routine.



   6.5.8.5  LIST_FAO (CTRSTR)

   This routine is called to output a string to the listing file.  The string may
   be  a  standard FAO format string with any number of arguments.  The string is
   output as a single record into  the  listing  file,  therefore,  in  order  to
   provide for easily read (and edited) listing files, each string should only be
   one line - no CR's, LF's, etc.
   DUMPER-32 Function Specificaiton                               Page 31
   Functional description                                 27 January 1986


   6.5.8.6  LIST_BLANK (LINE_COUNT)

   This routine will list some number of blank lines (empty records).



   6.5.8.7  LIST_36_BIT_VERSION   (VER_MAJOR,   VER_MINOR,   VER_EDIT,   VER_WHO,
            VER_DESC, VER_LENGTH)

   This routine is called to convert the fields of a standard TOPS style  version
   number into the standard text format (nnnxx(eeee)-w).