| 1 | \section{General Requirements} |
| 2 | |
| 3 | \subsection{Must Criteria} |
| 4 | \begin{itemize} |
| 5 | \item The program shall run on any computer running GNU/Linux. |
| 6 | \item It has no graphical user interface but a help option and command line error reporting. |
| 7 | \item The program shall support and check all block types according to \cite{ser16:progref:bformats}. |
| 8 | \item The Program must be able to list a tape image's contents. |
| 9 | \item The program shall be capable of splitting tape images into single object files. |
| 10 | \item The program's structure must be modular and easily extendable. |
| 11 | \end{itemize} |
| 12 | |
| 13 | \subsection{Optional features} |
| 14 | \begin{itemize} |
| 15 | \item Possibility to split a tape image into single data block files. |
| 16 | \item Software handshake paper tape reader control:\\ |
| 17 | A paper paper tape reader connected to the computer's serial port could be motion-controlled |
| 18 | by use of XON and XOFF characters. This is useful when error breaks for tape inspection are |
| 19 | enabled and the paper tape device does not support RTS/CTS hardware handshake. |
| 20 | \item Full POSIX.1, 2004 edition, compliance.\\ |
| 21 | This enables the program to be usable under many different UNIX style operating |
| 22 | systems. |
| 23 | \end{itemize} |
| 24 | |
| 25 | \subsection{Further additions explicitely beyond the scope of this project} |
| 26 | \begin{itemize} |
| 27 | \item Detailed data block analysis: |
| 28 | \begin{itemize} |
| 29 | \item Linking objects into a virtual memory representation. |
| 30 | \item Generating disassembly listings of block contents |
| 31 | \end{itemize} |
| 32 | |
| 33 | \item Support for self loading system tapes generated by \emph{PAL-AP} (see \cite{ser16:opmanual}). |
| 34 | |
| 35 | \end{itemize} |
| 36 | |
| 37 | %******************************************************************************* |
| 38 | \newpage |
| 39 | \section{Detailed Functional Specification} |
| 40 | |
| 41 | %******************************************************************************* |
| 42 | \subsection{Data input processing} |
| 43 | |
| 44 | \rd{inp001}{Data source select}{ |
| 45 | The tape data in Honeywell silent 4/6/6 code |
| 46 | \cite{ser16:progref:bformats} shall be read in from standard input or |
| 47 | from an input file. |
| 48 | } |
| 49 | |
| 50 | %******************************************************************************* |
| 51 | \subsection{Data integrity checks} |
| 52 | |
| 53 | The tape data shall be checked against the Honeywell tape block specification |
| 54 | found in \cite{ser16:progref:bformats}. |
| 55 | |
| 56 | \rd{chk001}{Block integrity check}{ |
| 57 | Every data block's integrity shall be checked by the means of |
| 58 | detecting unexpected end of file while reading in the block. |
| 59 | } |
| 60 | |
| 61 | \rd{chk002}{Block checksum check}{ |
| 62 | Every data block's checksum shall be calculated and checked according |
| 63 | to \cite{ser16:progref:bformats}. |
| 64 | } |
| 65 | |
| 66 | \rd{chk003}{Block type check}{ |
| 67 | Every data block contains its blocktype encoded in a specified location. |
| 68 | It shall be checked that each data block's type field contains one of |
| 69 | the type codes described in \cite{ser16:progref:bformats}. |
| 70 | } |
| 71 | |
| 72 | \rd{chk004}{Object integrity check}{ |
| 73 | Every object on the tape (i.e. the output of one DAP-16 or FORTRAN IV |
| 74 | compiler run) consists of multiple data blocks. |
| 75 | According to \cite{ser16:progref:bformats}, the last block of each |
| 76 | object must be of one of the end block types.\\ |
| 77 | It shall be checked if the last data block read before end of input or |
| 78 | an end of tape mark is an appropriate end block. |
| 79 | } |
| 80 | |
| 81 | \rd{chk005}{Interactive checksum error handling}{ |
| 82 | The program shall be configurable to pause block processing on |
| 83 | detection of a checksum error (\req{chk002}) and resume processing after |
| 84 | user intervention.\\ |
| 85 | This feature is incompatible with data input from standard input. |
| 86 | } |
| 87 | |
| 88 | %******************************************************************************* |
| 89 | \subsection{Additional features} |
| 90 | |
| 91 | \rd{h001}{Print help message}{ |
| 92 | A help message is output to standard error. |
| 93 | } |
| 94 | |
| 95 | %******************************************************************************* |
| 96 | \newpage |
| 97 | \subsection{Data analysis} |
| 98 | |
| 99 | \rd{da001}{List tape contents}{ |
| 100 | Output a list containing a human-readable fixed-format description |
| 101 | of all blocks contained in the input data.\\ |
| 102 | The output line format shall be unified for all block types. |
| 103 | } |
| 104 | |
| 105 | \rd{da002}{List exported symbols}{ |
| 106 | Output a list of all exported symbols. |
| 107 | } |
| 108 | |
| 109 | \rd{da003}{List called symbols}{ |
| 110 | Output a list of all called symbols. |
| 111 | } |
| 112 | |
| 113 | \rd{da004}{List unsatisfied dependencies}{ |
| 114 | Output a list of all unsatisfied dependencies i.e. |
| 115 | all called symbols that appear in the output of \req{dp003} but |
| 116 | not in the output of \req{dp002}. |
| 117 | } |
| 118 | |
| 119 | \rd{da005}{Tape information output}{ |
| 120 | It shall be possible to output a line containing at least |
| 121 | the following information about a tape image: |
| 122 | \begin{itemize} |
| 123 | \item Number of bytes read from data source |
| 124 | \item Number of blocks read in |
| 125 | \end{itemize} |
| 126 | } |
| 127 | |
| 128 | \rd{da006}{Text output}{ |
| 129 | Text from \req{da001},\req{da002},\req{da003}, \req{da004}, |
| 130 | and \req{da005} is output to standard output or to a file. |
| 131 | } |
| 132 | |
| 133 | %******************************************************************************* |
| 134 | \newpage |
| 135 | \subsection{Data processing} |
| 136 | |
| 137 | \rd{dp001}{Split into object files}{ |
| 138 | The tape data shall be divided into self-contained object files.\\ |
| 139 | The generated file names are derived from the first symbol name |
| 140 | defined in the current object.\\ |
| 141 | Example: If an object exports the symbols SONNE, MOND |
| 142 | and STERNE, the resulting file name will be SONNE.\\ |
| 143 | EOT (end of tape) blocks shall not be output in this mode of operation. |
| 144 | } |
| 145 | |
| 146 | \rd{dp002}{Split into numbered object files}{ |
| 147 | Similar to \req{dp006}, but the object file names are prepended with |
| 148 | a zero-padded three digit number and EOT blocks are not suppressed. |
| 149 | } |
| 150 | |
| 151 | |
| 152 | %******************************************************************************* |
| 153 | \newpage |
| 154 | \subsection{Error handling} |
| 155 | |
| 156 | |
| 157 | \newcommand{\esup}{ |
| 158 | This error shall lead to an error message and immediate program |
| 159 | termination or a warning message and program continuation. |
| 160 | } |
| 161 | |
| 162 | \newcommand{\enosup}{ |
| 163 | This error shall always lead to an error message and immediate |
| 164 | program termination. |
| 165 | } |
| 166 | |
| 167 | \rd{err001}{Error types}{ |
| 168 | The following distinguished error types shall exist: |
| 169 | \begin{itemize} |
| 170 | \item Input/output error:\\ |
| 171 | Error occuring during reading from the input file descriptor |
| 172 | or during writing to an output file.\\ |
| 173 | \enosup |
| 174 | \item Block integrity error:\\ |
| 175 | Caused by failed check according to \req{chk001}.\\ |
| 176 | \esup |
| 177 | \item Checksum error:\\ |
| 178 | Caused by failed check according to \req{chk002}.\\ |
| 179 | \esup |
| 180 | \item Unknown block type error:\\ |
| 181 | Caused by failed check according to \req{chk003}.\\ |
| 182 | \esup |
| 183 | \item Object integrity error:\\ |
| 184 | Caused by failed check according to \req{chk004}.\\ |
| 185 | \esup |
| 186 | \item Usage error:\\ |
| 187 | Error caused by errors in the program configuration i.e. wrong |
| 188 | parameters or impossible combinations of parameters.\\ |
| 189 | \enosup \\ |
| 190 | Additionally, the help (\req{h001}) message is output. |
| 191 | \item Internal program error:\\ |
| 192 | Error caused by internal program problems.\\ |
| 193 | This error should never occur.\\ |
| 194 | \enosup |
| 195 | \end{itemize} |
| 196 | } |
| 197 | |
| 198 | \rd{err002}{Program exit codes}{ |
| 199 | \begin{table}[H] |
| 200 | \begin{center} |
| 201 | \begin{tabular}{|r|c|} |
| 202 | \hline |
| 203 | \multicolumn{1}{|c|}{\bf Exit condition} & \bf Return code\\ |
| 204 | \hline |
| 205 | Successfull program completion & 0 \\ |
| 206 | File open error & 1\\ |
| 207 | Input/output error & 2\\ |
| 208 | Block integrity error & 3\\ |
| 209 | Checksum error & 4\\ |
| 210 | Unknown block type error & 5\\ |
| 211 | Object integrity error & 6\\ |
| 212 | Usage error & 7\\ |
| 213 | Internal program error & 100 \\ |
| 214 | \hline |
| 215 | \end{tabular} |
| 216 | \caption[Program Exit codes]{Exit codes} |
| 217 | \end{center} |
| 218 | \end{table} |
| 219 | } |
| 220 | |
| 221 | \rd{err003}{Error and warning messages}{ |
| 222 | Error messages shall consinst of ''Error:'' and the error reason.\\ |
| 223 | Warning messages shall consist of ''Warning:'' and a descriptive |
| 224 | text.\\ |
| 225 | The following texts shall be used to form error and warning messages: |
| 226 | \begin{table}[H] |
| 227 | \begin{center} |
| 228 | \begin{tabular}{|l|l|} |
| 229 | \hline |
| 230 | \bf Error condition & \bf Descriptive text\\ \hline |
| 231 | File open error & Could not open $<$filename$>$ for reading/writing!\\ |
| 232 | Input error & Could not read from $<$filename$>$!\\ |
| 233 | Output error & Could not write to $<$filename$>$!\\ |
| 234 | Block integrity error & Block integrity check failed!\\ |
| 235 | Checksum error & Block checksum wrong!\\ |
| 236 | Unknown block type & Unknown block type!\\ |
| 237 | Object integrity & Object integrity check failed!\\ |
| 238 | Usage error & $<$Specific message describing the problem$>$\\ |
| 239 | \hline |
| 240 | \end{tabular} |
| 241 | \end{center} |
| 242 | \caption[Error and warning messages]{Messages} |
| 243 | \end{table} |
| 244 | } |
| 245 | |
| 246 | \rd{err004}{Error message output}{ |
| 247 | Any error messages shall be output to standard error.\\ |
| 248 | There shall be no way to suppress error messages. |
| 249 | } |
| 250 | |
| 251 | \rd{err005}{Warning message output}{ |
| 252 | Any warning messages shall be output to standard error.\\ |
| 253 | There shall be a possibility to suppress warning messages. |
| 254 | } |
| 255 | |
| 256 | %******************************************************************************* |
| 257 | \newpage |
| 258 | \subsection{Program configuration} |
| 259 | |
| 260 | \rd{cfg001}{Configuration process}{ |
| 261 | The following sequence shall be used to acquire the working |
| 262 | configuration: |
| 263 | \begin{enumerate} |
| 264 | \item Configuration file according to environment variable:\\ |
| 265 | If the environment variable LDC\_CONFIG is set, that |
| 266 | file shall be parsed. |
| 267 | \item Configuration file according to command line parameter:\\ |
| 268 | If the command line parameter specifying a configuration |
| 269 | file is found, |
| 270 | the specified configuration file is parsed.\\ |
| 271 | Any values in this configuration file |
| 272 | override values found in the previously read |
| 273 | configuration file. |
| 274 | \item Configuration parameters passed via the command line:\\ |
| 275 | Parameters passed on the command line will override |
| 276 | values from previously read configuration files. If the command line |
| 277 | mentiones a configuration file to read, this file is processed before |
| 278 | the other parameters supplied on the command line. |
| 279 | \end{enumerate} |
| 280 | } |
| 281 | |
| 282 | \rd{cfg002}{Parameter types}{ |
| 283 | The program shall accept two types of parameters: |
| 284 | \begin{itemize} |
| 285 | \item Switches:\\ |
| 286 | A switch is a binary value which can have the value true or |
| 287 | false. |
| 288 | \item Strings:\\ |
| 289 | A string parameter is a parameter requiring a string value.\\ |
| 290 | A typical use would be a file name for input or output. |
| 291 | \end{itemize} |
| 292 | } |
| 293 | |
| 294 | \newpage |
| 295 | \rd{cfg003}{Switch parameters}{ |
| 296 | The following switch parameters shall be accepted: |
| 297 | \begin{table}[H]\begin{center} |
| 298 | \begin{tabular}{|r|p{2.5em}|p{23em}|} |
| 299 | \hline |
| 300 | \bf Long Form & \bf Short form & \bf Description\\ |
| 301 | \hline |
| 302 | help & h & Show help message (\req{h001})\\ |
| 303 | output\_info & a & Output data info (\req{da005}) .\\ |
| 304 | output\_called & c & Output a list of called symbols |
| 305 | (\req{da003}).\\ |
| 306 | output\_exported & e & Output a list of exported symbols |
| 307 | (\req{da002}).\\ |
| 308 | output\_unsatisfied & u & Output a list of unsatisfied |
| 309 | dependencies (\req{da004}).\\ |
| 310 | split\_objects & s & Split into object files |
| 311 | (\req{dp001}).\\ |
| 312 | split\_objects\_numbered & S & Split into numbered object files |
| 313 | (\req{dp002}).\\ |
| 314 | ignore\_block\_errors & b & Ignore block integrity errors |
| 315 | (\req{err001},\req{chk001}).\\ |
| 316 | ignore\_checksum\_errors & k & Ignore Checksum errors |
| 317 | (\req{err001}\req{chk002}).\\ |
| 318 | pause\_on\_checksum\_error & p & Wait for user input on checksum error |
| 319 | (\req{chk005}).\\ |
| 320 | ignore\_unknown\_block\_errors & n & Ignore errors causes by |
| 321 | datablocks of unknown type |
| 322 | (\req{err001}\req{chk003}).\\ |
| 323 | ignore\_object\_integrity\_errors & g & Ignore errors caused by objects |
| 324 | without proper end block |
| 325 | (\req{err001}\req{chk004}).\\ |
| 326 | \hline |
| 327 | \end{tabular}\end{center} |
| 328 | \caption{Configuration switches} |
| 329 | \end{table} |
| 330 | } |
| 331 | |
| 332 | \rd{cfg004}{String parameters}{ |
| 333 | The following string parameters shall be accepted: |
| 334 | \begin{table}[H]\begin{center} |
| 335 | \begin{tabular}{|r|p{2.5em}|l|} |
| 336 | \hline |
| 337 | \bf Long Form & \bf Short form & \bf Description\\ |
| 338 | \hline |
| 339 | in\_file & i & Set input file (\req{inp001}). \\ |
| 340 | out\_file & o & Set output file for text output(\req{dp008}).\\ |
| 341 | \hline |
| 342 | \end{tabular}\end{center} |
| 343 | \caption{Configuration strings} |
| 344 | \end{table} |
| 345 | |
| 346 | } |
| 347 | \newpage |
| 348 | \rd{cfg005}{Configuration file syntax}{ |
| 349 | The configuration file must comply two the following grammar, given in EBNF: |
| 350 | } |
| 351 | \begin{verbatim} |
| 352 | ConfigurationFile = { ConfigurationLine "<EOL>" } ; |
| 353 | ConfigurationLine = SwitchLine | StringLine | CommentLine ; |
| 354 | SwitchLine = WSpace SwLong WSpace "=" BoolValue ; |
| 355 | StringLine = WSpace StrLong WSpace "=" String ; |
| 356 | CommentLine = WSpace [ "#" String ] ; |
| 357 | WSpace = { " " } ; |
| 358 | SwLong = "output_info" | "ouput_called" | "output_exported" |
| 359 | | "output_unsatisfied" | "split_objects" [ _"numbered" ] |
| 360 | | "ignore_block_errors" | "ignore_checksum_errors |
| 361 | | "pause_on_checksum_error" |
| 362 | | "ignore_unknown_block_errors" |
| 363 | | "ignore_object_integrity" ; |
| 364 | StrLong = "out_file" | "in_file" ; |
| 365 | BoolValue = TrueStr | FalseStr ; |
| 366 | String = { ? Every character except newline ?} ; |
| 367 | TrueStr = "yes" | "1" | "true" ; |
| 368 | FalseStr = | "no" | "0" | "false" ; |
| 369 | \end{verbatim} |
| 370 | |
| 371 | \rd{cfg006}{Command Line syntax}{ |
| 372 | The command line must comply to the following grammar, given in EBNF: |
| 373 | } |
| 374 | \begin{verbatim} |
| 375 | CommandLine = ProgramName Arguments ; |
| 376 | ProgramName = String ; |
| 377 | Arguments = { " " } { " " Argument } [ " " InfileName ] ; |
| 378 | Argument = { Switch | Parameter } |
| 379 | InfileName = String ; |
| 380 | Switch = ShortSwitch | LongSwitch ; |
| 381 | Parameter = ShortParam | LongParam ; |
| 382 | String = { ? Every character except newline ? } ; |
| 383 | ShortSwitch = "-" SwShort ; |
| 384 | LongSwitch = "--" SwLong [ "=" BoolValue ] ; |
| 385 | ShortParam = "-" StrShort String ; |
| 386 | LongParam = "--" StrLong "=" String ; |
| 387 | SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" |
| 388 | | "b" | "k" | "p" | "n" | "g" ; |
| 389 | SwLong = "help" |
| 390 | | "output_info" | "ouput_called" | "output_exported" |
| 391 | | "output_unsatisfied" | "split_objects" [ _"numbered" ] |
| 392 | | "ignore_block_errors" | "ignore_checksum_errors" |
| 393 | | "pause_on_checksum_error" |
| 394 | | "ignore_unknown_block_errors" |
| 395 | | "ignore_object_integrity" ; |
| 396 | StrShort = "o" ; |
| 397 | StrLong = "out_file" ; |
| 398 | \end{verbatim} |
| 399 | |
| 400 | \newpage |
| 401 | \rd{cfg007}{Configuration implications}{ |
| 402 | \begin{itemize} |
| 403 | \item \emph{pause\_on\_checksum\_errors} implies \emph{ignore\_checksum\_errors}. |
| 404 | \item \emph{pause\_on\_checksum\_errors} is completely ignored when input |
| 405 | is read from standard input. |
| 406 | \item \emph{output\_*} inhibits tape information output (\req{da001}). |
| 407 | \item \emph{help} inhibits all other actions. |
| 408 | \end{itemize} |
| 409 | } |
| 410 | |
| 411 | \rd{cfg008}{Default behaviour}{ |
| 412 | \begin{itemize} |
| 413 | \item Data is read from standard input. |
| 414 | \item All error conditions result in immediate program termination |
| 415 | and an error message. |
| 416 | \item Tape information according to \req{da001} is output. |
| 417 | \item Normal Text is output to standard output. |
| 418 | \item Error messages are output to standard error. |
| 419 | \end{itemize} |
| 420 | } |