Trailing-Edge
-
PDP-10 Archives
-
integ_tools_tops20_v7_30-apr-86_dumper
-
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).