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