1 \section{General Requirements
}
3 \subsection{Must Criteria
}
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.
13 \subsection{Optional features
}
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
25 \subsection{Further additions explicitely beyond the scope of this project
}
27 \item Detailed data block analysis:
29 \item Linking objects into a virtual memory representation.
30 \item Generating disassembly listings of block contents
33 \item Support for self loading system tapes generated by
\emph{PAL-AP
} (see
\cite{ser16:opmanual
}).
37 %*******************************************************************************
39 \section{Detailed Functional Specification
}
41 %*******************************************************************************
42 \subsection{Data input processing
}
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
50 %*******************************************************************************
51 \subsection{Data integrity checks
}
53 The tape data shall be checked against the Honeywell tape block specification
54 found in
\cite{ser16:progref:bformats
}.
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.
61 \rd{chk002
}{Block checksum check
}{
62 Every data block's checksum shall be calculated and checked according
63 to
\cite{ser16:progref:bformats
}.
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
}.
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.
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
85 This feature is incompatible with data input from standard input.
88 %*******************************************************************************
89 \subsection{Additional features
}
91 \rd{h001
}{Print help message
}{
92 A help message is output to standard error.
95 %*******************************************************************************
97 \subsection{Data analysis
}
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.
105 \rd{da002
}{List exported symbols
}{
106 Output a list of all exported symbols.
109 \rd{da003
}{List called symbols
}{
110 Output a list of all called symbols.
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
}.
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:
123 \item Number of bytes read from data source
124 \item Number of blocks read in
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.
133 %*******************************************************************************
135 \subsection{Data processing
}
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.
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.
152 %*******************************************************************************
154 \subsection{Error handling
}
158 This error shall lead to an error message and immediate program
159 termination or a warning message and program continuation.
162 \newcommand{\enosup}{
163 This error shall always lead to an error message and immediate
167 \rd{err001
}{Error types
}{
168 The following distinguished error types shall exist:
170 \item Input/output error:\\
171 Error occuring during reading from the input file descriptor
172 or during writing to an output file.\\
174 \item Block integrity error:\\
175 Caused by failed check according to
\req{chk001
}.\\
177 \item Checksum error:\\
178 Caused by failed check according to
\req{chk002
}.\\
180 \item Unknown block type error:\\
181 Caused by failed check according to
\req{chk003
}.\\
183 \item Object integrity error:\\
184 Caused by failed check according to
\req{chk004
}.\\
187 Error caused by errors in the program configuration i.e. wrong
188 parameters or impossible combinations of parameters.\\
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.\\
198 \rd{err002
}{Program exit codes
}{
201 \begin{tabular
}{|r|c|
}
203 \multicolumn{1}{|c|
}{\bf Exit condition
} &
\bf Return code\\
205 Successfull program completion &
0 \\
206 File open error &
1\\
207 Input/output error &
2\\
208 Block integrity error &
3\\
210 Unknown block type error &
5\\
211 Object integrity error &
6\\
213 Internal program error &
100 \\
216 \caption[Program Exit codes
]{Exit codes
}
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
225 The following texts shall be used to form error and warning messages:
228 \begin{tabular
}{|l|l|
}
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$>$\\
242 \caption[Error and warning messages
]{Messages
}
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.
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.
256 \rd{err006
}{Informational messages
}{
257 Any informational messages go to standard error.
261 %*******************************************************************************
263 \subsection{Program configuration
}
265 \rd{cfg001
}{Configuration process
}{
266 The following sequence shall be used to acquire the working
269 \item Configuration file according to environment variable:\\
270 If the environment variable LDC
\_CONFIG is set, that
271 file shall be parsed.
272 \item Configuration file according to command line parameter:\\
273 If the command line parameter specifying a configuration
275 the specified configuration file is parsed.\\
276 Any values in this configuration file
277 override values found in the previously read
279 \item Configuration parameters passed via the command line:\\
280 Parameters passed on the command line will override
281 values from previously read configuration files. If the command line
282 mentiones a configuration file to read, this file is processed before
283 the other parameters supplied on the command line.
287 \rd{cfg002
}{Parameter types
}{
288 The program shall accept two types of parameters:
291 A switch is a binary value which can have the value true or
294 A string parameter is a parameter requiring a string value.\\
295 A typical use would be a file name for input or output.
300 \rd{cfg003
}{Switch parameters
}{
301 The following switch parameters shall be accepted:
302 \begin{table
}[H
]\begin{center
}
303 \begin{tabular
}{|r|p
{2.5em
}|p
{23em
}|
}
305 \bf Long Form &
\bf Short form &
\bf Description\\
307 help & h & Show help message (
\req{h001
})\\
308 output
\_info & a & Output data info (
\req{da005
}) .\\
309 output
\_called & c & Output a list of called symbols
311 output
\_exported & e & Output a list of exported symbols
313 output
\_unsatisfied & u & Output a list of unsatisfied
314 dependencies (
\req{da004
}).\\
315 split
\_objects & s & Split into object files
317 split
\_objects\_numbered & S & Split into numbered object files
319 ignore
\_block\_errors & b & Ignore block integrity errors
320 (
\req{err001
},
\req{chk001
}).\\
321 ignore
\_checksum\_errors & k & Ignore Checksum errors
322 (
\req{err001
}\req{chk002
}).\\
323 pause
\_on\_checksum\_error & p & Wait for user input on checksum error
325 ignore
\_unknown\_block\_errors & n & Ignore errors causes by
326 datablocks of unknown type
327 (
\req{err001
}\req{chk003
}).\\
328 ignore
\_object\_integrity\_errors & g & Ignore errors caused by objects
329 without proper end block
330 (
\req{err001
}\req{chk004
}).\\
331 quiet & q & Suppress all non-critical messages
332 to standard error (warnings, informatianal)\\
334 \end{tabular
}\end{center
}
335 \caption{Configuration switches
}
339 \rd{cfg004
}{String parameters
}{
340 The following string parameters shall be accepted:
341 \begin{table
}[H
]\begin{center
}
342 \begin{tabular
}{|r|p
{2.5em
}|l|
}
344 \bf Long Form &
\bf Short form &
\bf Description\\
346 in
\_file & i & Set input file (
\req{inp001
}). \\
347 out
\_file & o & Set output file for text output(
\req{dp008
}).\\
349 \end{tabular
}\end{center
}
350 \caption{Configuration strings
}
355 \rd{cfg005
}{Configuration file syntax
}{
356 The configuration file must comply two the following grammar, given in EBNF:
359 ConfigurationFile =
{ ConfigurationLine "<EOL>"
} ;
360 ConfigurationLine = SwitchLine | StringLine | CommentLine ;
361 SwitchLine = WSpace SwLong WSpace "=" BoolValue ;
362 StringLine = WSpace StrLong WSpace "=" String ;
363 CommentLine = WSpace
[ "#" String
] ;
365 SwLong = "output_info" | "ouput_called" | "output_exported"
366 | "output_unsatisfied" | "split_objects"
[ _"numbered"
]
367 | "ignore_block_errors" | "ignore_checksum_errors
368 | "pause_on_checksum_error"
369 | "ignore_unknown_block_errors"
370 | "ignore_object_integrity"
372 StrLong = "out_file" | "in_file" ;
373 BoolValue = TrueStr | FalseStr ;
374 String =
{ ? Every character except newline ?
} ;
375 TrueStr = "yes" | "
1" | "true" ;
376 FalseStr = | "no" | "
0" | "false" ;
379 \rd{cfg006
}{Command Line syntax
}{
380 The command line must comply to the following grammar, given in EBNF:
383 CommandLine = ProgramName Arguments ;
384 ProgramName = String ;
385 Arguments =
{ " "
} { " " Argument
} [ " " InfileName
] ;
386 Argument =
{ Switch | Parameter
}
387 InfileName = String ;
388 Switch = ShortSwitch | LongSwitch ;
389 Parameter = ShortParam | LongParam ;
390 String =
{ ? Every character except newline ?
} ;
391 ShortSwitch = "-" SwShort ;
392 LongSwitch = "--" SwLong
[ "=" BoolValue
] ;
393 ShortParam = "-" StrShort String ;
394 LongParam = "--" StrLong "=" String ;
395 SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S"
396 | "b" | "k" | "p" | "n" | "g" | "q";
398 | "output_info" | "ouput_called" | "output_exported"
399 | "output_unsatisfied" | "split_objects"
[ _"numbered"
]
400 | "ignore_block_errors" | "ignore_checksum_errors"
401 | "pause_on_checksum_error"
402 | "ignore_unknown_block_errors"
403 | "ignore_object_integrity"
406 StrLong = "out_file" ;
410 \rd{cfg007
}{Configuration implications
}{
412 \item \emph{pause
\_on\_checksum\_errors} implies
\emph{ignore
\_checksum\_errors}.
413 \item \emph{pause
\_on\_checksum\_errors} is completely ignored when input
414 is read from standard input.
415 \item \emph{output
\_*
} and
\emph{split
\_*
} inhibit
416 tape information output (
\req{da001
}).
417 \item \emph{help
} inhibits all other actions.
421 \rd{cfg008
}{Default behaviour
}{
423 \item Data is read from standard input.
424 \item All error conditions result in immediate program termination
425 and an error message.
426 \item Tape information according to
\req{da001
} is output to standard output.