--------------------------------------------------------------------------------
--                                                                            --
--  FLABEL -- A program to print file label information from an HP 3000       --
--            STORE SIMH magnetic tape image.                                 --
--                                                                            --
--------------------------------------------------------------------------------
--                                                                            --
--  Copyright  2012 Palomar Corporation.  All rights reserved.               --
--                                                                            --
--------------------------------------------------------------------------------
--
-- Change Log:
--
--   2020-04-06 [1.03] -- Changed File_Type to Device_File to reflect updated
--                        Device_IO library.
--
--   2012-08-29 [1.02] -- Modified Device_IO calling sequences for "in out" file
--                        parameters.
--
--   2012-08-15 [1.01] -- Moved gnat_argc and gnat_argv declarations into
--                        Parse_Options where they are used.
--
--   2012-06-20 [1.00] -- Initial version.
--
--------------------------------------------------------------------------------
--
-- Invocation:
--
--   flabel [OPTIONS]... INPUT-FILE
--
-- Options:
--
--   General options:
--
--     -h or --help
--        Print the help text and exit.
--
--     -V or --version
--        Print the version number and exit.
--
--   Print Options:
--
--     -f or --file-list
--        Print the complete sorted file list.
--
--     -d or --directory
--        Print the complete tape directory.
--
--     -p or --print=OPTION
--        Select optional information to print.
--
--     -w or --warnings
--        Print warnings in addition to errors..
--
-- Available print options for file labels:
--
--   file
--     Print the tape file number.
--
--   record
--     Print the record number of the EOF, the number of records allowed, the
--     the block size, and the blocking factor.
--
--   disc
--     Print the number of extents used and allowed, the size in sectors of the
--     intervening and last extents, the number of user labels used and allowed,
--     the sector offset to the data area, and the allocation device.
--
--   security
--     Print the file lockword, creator name, and security access matrix.
--
--   time
--     Print the creation, last access, last modification, and initial
--     allocation dates and times.
--
--   all
--     Print all of the optional information.
--
-- The basic file label information (file name, group name, account name, file
-- code, record size, file type, and file size in sectors) is always printed.
-- If the optional full time stamps are not printed, the last modified date of
-- each file is included.
--
--------------------------------------------------------------------------------
--
-- This program lists the contents of an HP 3000 STORE/RESTORE tape image.
-- Information is obtained from the tape directory and the file labels
-- preceding each stored file.  In addition to the basic file statistics,
-- several optional sets of label data may be included in the list.  The list
-- is written to the standard output.
--
-- In addition, a number of sanity checks are performed while reading the tape.
-- Detected errors are printed unconditionally, while warnings are optional.
--
-- These errors are fatal and will abort the program:
--
--   ERROR: the input file is not a valid STORE tape.
--
--     The file supplied is not formatted correctly for a STORE tape, is not a
--     SIMH magnetic tape image, or is incomplete.
--
--   ERROR: the tape header version "<ver>" is not supported by this program.
--
--     The program only supports STORE tapes that report version ID "VIIB" in
--     the header.
--
--   ERROR: the directory record length <x> is not a multiple of the directory
--          entry length <y>.
--
--     A tape directory record does not contain an integral number of directory
--     entries.
--
-- These errors indicate problems with the tape and may cause problems when the
-- tape is restored but do not abort the program:
--
--   ERROR: the header checksum <x> does not match the tape checksum <y>.
--
--     The calculated checksum of the tape header does not agree with the
--     checksum value stored in the header.
--
--   ERROR: the tape is missing the required two leading tape marks.
--
--     The header of the first volume of a STORE tape was found in the first
--     file on tape rather than in the third file as expected.  The tape image
--     may have been transcribed incorrectly; some transcription programs assume
--     that two tape marks in succession indicate the logical end of the tape.
--
--   ERROR: the file label filename does not match the directory entry filename
--          <file.grp.acct>.
--
--     The filename in the tape label is not identical to the filename in the
--     corresponding tape directory entry.  Data files on the tape must appear
--     in the same order as they appear in the directory.
--
--   ERROR: the file label sector count <x> does not match the tape sector count
--          <y>.
--
--     The number of file sectors that should be on the tape as calculated from
--     the file label data does not match the number of file sectors actually
--     on the tape.  The RESTORE program will be unable to copy the file.
--
--   ERROR: the file label checksum <x> does not match the tape checksum <y>.
--
--     The calculated checksum of the file label does not agree with the
--     checksum value stored in the label.
--
-- These warnings indicate possible problems with the tape and may cause
-- problems when the tape is restored:
--
--   WARNING: the file label extent size <x> does not match the calculated
--            extent size <y>.
--
--   WARNING: the file label last extent size <x> does not match the calculated
--            last extent size <y>.
--
--     The main and last extent size values in the file label do not match the
--     sizes calculated from the file label data (number of extents, file size
--     in blocks, sectors per block, etc.).
--
--------------------------------------------------------------------------------
--
-- References:
--
--   MPE File System Reference Manual
--     30000-90236, February 1982
--
--   MPE V Intrinsics Reference Manual
--     32033-90007, October 1989
--
--   MPE V Tables Manual, MPE V/E (VUF G.08.00), MPE V Release 23
--     32033-90147, October 1991
--
--   Communicator 3000 MPE V Release 30 (Version G.30.00)
--     32033-90281, December 1992
--
--------------------------------------------------------------------------------
