[h316.git] / pc-tools / ldc2 / doc / req_spec.tex

\section{Requirements Specification}

%*******************************************************************************
\subsection{Data input processing}

\rd{inp001}{Data source select}{
        The tape data in Honeywell silent 4/6/6 code 
        \cite{ser16:progref:bformats} shall be read in from standard input or 
        from an input file.
}

%*******************************************************************************
\subsection{Data integrity checks}

The tape data shall be checked against the Honeywell tape block specification
found in \cite{ser16:progref:bformats}.
 
\rd{chk001}{Block completeness check}{
        Every data block's completeness shall be checked by the means of 
        detecting unexpected end of file while reading in the block.
}

\rd{chk002}{Block checksum check}{
        Every data block's checksum shall be calculated and checked according
        to \cite{ser16:progref:bformats}.
}

\rd{chk003}{Block type check}{
        Every data block contains its blocktype encoded in a specified location.
        It shall be checked that each data block's type field contains one of
        the type codes described in \cite{ser16:progref:bformats}.
}

\rd{chk004}{Object integrity check}{
        Every object on the tape (i.e. the output of one DAP-16 or FORTRAN IV 
        compiler run) consists of multiple data blocks.
        According to \cite{ser16:progref:bformats}, the last block of each
        object must be of one of the end block types.\\
        It shall be checked if the last data block read before end of input or 
        an end of tape mark is an appropriate end block.
}

\rd{chk005}{Interactive checksum error handling}{
        The program shall be configurable to pause block processing on
        detection of a checksum error (\req{chk002}) and resume processing after
        user intervention.\\
        This feature is incompatible with data input from standard input.
}

%*******************************************************************************
\subsection{Data analysis}

\rd{da001}{List tape contents}{
        Output a list containing a human-readable fixed-format description
        of all blocks contained in the input data.\\
        The output line format shall be unified for all block types.
}

\rd{da002}{List exported symbols}{
        Output a list of all exported symbols.
}

\rd{da003}{List called symbols}{
        Output a list of all called symbols.
}

\rd{da004}{List unsatisfied dependencies}{
        Output a list of all unsatisfied dependencies i.e.
        all called symbols that appear in the output of \req{dp003} but
        not in the output of \req{dp002}.
}

\rd{da005}{Tape information output}{
        It shall be possible to output a line containing at least
        the following information about a tape image:
        \begin{itemize}
        \item Number of bytes read from data source
        \item Number of blocks read in
        \end{itemize}
}

\rd{da006}{Text output}{
        Text from \req{da001},\req{da002},\req{da003}, \req{da004},
         and \req{da005} is output to standard output or to a file.
}

%*******************************************************************************
\subsection{Data processing}

\rd{dp001}{Split into object files}{
        The tape data shall be divided into self-contained object files.\\
        The generated file names are derived from the first symbol name
        defined in the current object.\\
        Example: If an object exports the symbols SONNE, MOND
        and STERNE, the resulting file name will be SONNE.\\
        EOT (end of tape) blocks shall not be output in this mode of operation.
}

\rd{dp002}{Split into numbered object files}{
        Similar to \req{dp006}, but the object file names are prepended with
        a zero-padded three digit number and EOT blocks are not suppressed.
}

%*******************************************************************************
\subsection{Additional features}

\rd{h001}{Print help message}{
        A help message shall be output to standard error.
}

%*******************************************************************************        
\subsection{Program configuration}

\rd{cfg001}{Configuration process}{
        The following sequence shall be used to acquire the working configuration:
        \begin{enumerate}
                \item Configuration file according to environment variable:\\
                        If the environment variable LDC\_CONFIG is set, that
                        file shall be parsed.
                \item Configuration file according to command line parameter:\\
                        If the command line parameter specifying a configuration
                        file is found,
                        the specified configuration file is parsed.\\
                        Any values in this configuration file
                        override values found in the previously read configuration 
                        file. 
                \item Configuration parameters passed via the command line:\\
                        Parameters passed on the command line will override
                        values from previously read configuration files.
        \end{enumerate}
}

\rd{cfg002}{Parameter types}{
        The program shall accept two types of parameters:
        \begin{itemize}
        \item Switches:\\
                A switch is a binary value which can have the value true or false.
        \item Strings:\\
                A string parameter is a parameter requiring a string value.\\
                A typical use would be a file name for input or output.
        \end{itemize}
}

\rd{cfg003}{Switch parameters}{
        The following switch parameters shall be accepted:
        \begin{table}[H]\begin{center}
        \begin{tabular}{|r|p{2.5em}|l|}
        \hline
        \bf Long Form & \bf Short form & \bf Description\\
        \hline
        help                       & h & Show help message (\req{h001})\\
        output\_info               & a & Output data info according to \req{da005}.\\
        output\_called             & c & Output a list of called symbols (\req{dp003}).\\ 
        output\_exported           & e & Output a list of exported symbols (\req{dp002}).\\
        output\_unsatisfied        & u & Output a list of unsatisfied dependencies (\req{dp004}).\\
        split\_objects             & s & Split into object files (\req{dp006}.\\
        split\_objects\_numbered   & S & Split into numbered object files (\req{dp007}).\\
        ignore\_block\_errors      & b & Ignore block integrity errors (\req{err001}).\\
        ignore\_checksum\_errors   & k & Ignore Checksum errors (\req{err001}).\\
        pause\_on\_checksum\_error & p & Wait for user input on checksum error (\req{err003}).\\
        ignore\_unknown\_block\_errors    & n  & Ignore errors causes by datablocks of 
                                                unknown type (\req{err001}).\\
        ignore\_object\_integrity\_errors & g & Ignore errors caused by objects without 
                                                proper end block (\req{err001}.)\\
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration switches}
        \end{table}     
}

\rd{cfg004}{String parameters}{
        The following string parameters shall be accepted:
        \begin{table}[H]\begin{center}
        \begin{tabular}{|r|p{2.5em}|l|}
        \hline
        \bf Long Form & \bf Short form & \bf Description\\
        \hline
        in\_file                   & i & Set input file (\req{inp001}) \\
        out\_file                  & o & Set output file for text output.(\req{dp008})\\
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration strings}
        \end{table}     

}

\rd{cfg005}{Configuration file syntax}{
        The configuration file must comply two the following grammar, given in EBNF:
}
        \begin{verbatim}
ConfigurationFile = { ConfigurationLine "<EOL>" } ;
ConfigurationLine = SwitchLine | StringLine | CommentLine ;
       SwitchLine = WSpace SwLong  WSpace "=" BoolValue ;
       StringLine = WSpace StrLong WSpace "=" String ;
      CommentLine = WSpace [ "#" String ] ;
           WSpace = { " " } ;
           SwLong = "output_info" | "ouput_called" | "output_exported"
                    | "output_unsatisfied" | "split_objects" [ _"numbered" ]
                    | "ignore_block_errors" | "ignore_checksum_errors
                    | "pause_on_checksum_error"
                    | "ignore_unknown_block_errors"
                    | "ignore_object_integrity" ;
          StrLong = "out_file" | "in_file" ;
        BoolValue = TrueStr | FalseStr ;
           String = { ? Every character except newline ?} ;
          TrueStr = "yes" | "1" | "true" ;
         FalseStr = | "no" | "0" | "false" ;
        \end{verbatim};

\rd{cfg006}{Commandline syntax}{
        The command line must comply to the following grammar, given in EBNF:   
}
\begin{verbatim}
CommandLine = ProgramName Arguments ;
ProgramName = String ;
  Arguments = { " " } { " " Argument } [ " " InfileName ] ;
   Argument = { Switch | Parameter } 
 InfileName = String ;
     Switch = ShortSwitch | LongSwitch ;
  Parameter = ShortParam | LongParam ;
     String = { ? Every character except newline ? } ;
ShortSwitch = "-" SwShort ;
 LongSwitch = "--" SwLong [ "=" BoolValue ] ;
 ShortParam = "-" StrShort String ;
  LongParam = "--" StrLong "=" String ;
    SwShort = "a" | "c" | "e" | "u" | "s" | "S"
              | "b" | "k" | "p" | "n" | "g" ;
     SwLong = "output_info" | "ouput_called" | "output_exported"
              | "output_unsatisfied" | "split_objects" [ _"numbered" ]
              | "ignore_block_errors" | "ignore_checksum_errors
              | "pause_on_checksum_error"
              | "ignore_unknown_block_errors"
              | "ignore_object_integrity" ;
   StrShort = "o";
    StrLong = "out_file" ;
\end{verbatim}

\rd{cfg007}{Configuration implications}{
        \begin{itemize}
        \item pause\_on\_checksum\_errors implies ignore\_checksum\_errors.
        \item pause\_on\_checksum\_errors is completely ignored when input 
        is read from standard input.
        \item output\_* inhibits tape information output (\req{da001}).
        \item help inhibits all other actions.
        \end{itemize}
}

\rd{cfg008}{Default behaviour}{
        \begin{itemize}
        \item Data is read from standard input.
        \item All error conditions result in immediate program termination
                and an error message.
        \item Tape information according to \req{da001} is output.
        \item Text is output to standard output.
        \end{itemize}
}

%*******************************************************************************
\subsection{Error handling}


\newcommand{\esup}{
        This error shall lead to an error message and immediate program
        termination or a warning message and program continuation.
}

\newcommand{\enosup}{
        This error shall always lead to an error message and immediate
        program termination.
}

\rd{err001}{Error types}{
        The following distinguished error types shall exist:
        \begin{itemize}
        \item Input/output error:\\ 
                Error occuring during reading from the input file descriptor
                or during writing to an output file.\\
                \enosup
        \item Block integrity error:\\
                Caused by failed check according to \req{chk001}.\\
                \esup
        \item Checksum error:\\
                Caused by failed check according to \req{chk002}.\\
                \esup
        \item Unknown block type error:\\
                Caused by failed check according to \req{chk003}.\\
                \esup           
        \item Object integrity error:\\
                Caused by failed check according to \req{chk004}.\\
                \esup
        \item Usage error:\\
                Error caused by errors in the program configuration i.e.wrong 
                parameters or impossible combinations of parameters.\\
                \enosup \\
                Additionally, the help (\req{h001}) message is output.
        \item   Internal program error:\\
                Error caused by internal program problems.\\
                This error should never occur.\\
                \enosup
        \end{itemize}
}

\rd{err002}{Program exit codes}{
        \begin{table}[H]
        \begin{center}
        \begin{tabular}{|r|c|}
                \hline
                \multicolumn{1}{|c|}{\bf Exit condition} & \bf Return code\\
                \hline
                Successfull program completion & 0 \\
                File open error & 1\\
                Input/output error & 2\\
                Block integrity error & 3\\
                Checksum error & 4\\
                Unknown block type error & 5\\
                Object integrity error & 6\\
                Usage error & 7\\
                Internal program error & 100 \\
                \hline 
        \end{tabular}
        \caption[Program Exit codes]{Exit codes}
        \end{center}
        \end{table}
}

\rd{err003}{Error and warning messages}{
        Error messages shall consinst of ''Error:'' and the error reason.\\
        Warning messages shall consist of ''Warning:'' and a descriptive 
        text.\\
        The following texts shall be used to form error and warning messages:
        \begin{table}[H]
        \begin{center}
        \begin{tabular}{|l|l|}
        \hline
        \bf Error condition & \bf Descriptive text\\ \hline
        File open error & Could not open $<$filename$>$ for reading/writing!\\
        Input error     &     Could not read from $<$filename$>$!\\
        Output error    &    Could not write to $<$filename$>$!\\
        Block integrity error & Block integrity check failed!\\
        Checksum error        & Block checksum wrong!\\
        Unknown block type    & Unknown block type!\\
        Object integrity      & Object integrity check failed!\\
        Usage error           & $<$Error message describing the problem$>$\\
        \hline
        \end{tabular}
        \end{center}
        \caption[Program Exit codes]{Exit codes}
        \end{table}
}

\rd{err004}{Error message output}{
        Any error messages shall be output to standard error.\\
        There shall be no way to suppress error messages.
}

\rd{err005}{Warning message output}{
        Any warning messages shall be output to standard error.\\
        There shall be a possibility to suppress warning messages.
}