DPANSA11.HTM (8080B)
1 <HTML><HEAD> 2 <TITLE>DPANS94</TITLE> 3 <link disabled rel="stylesheet" href="mpexc6.css"> 4 <style>@import url(mpexc6.css);</style> 5 </head> 6 7 <BODY> 8 <table width=100%> 9 <tr> 10 <td align=left> 11 <a href=dpansa10.htm><img src=left.gif 12 width=26 height=26 align=ALIGN border=0></a> 13 <a href=dpansa12.htm><img src=right.gif 14 width=26 height=26 align=ALIGN border=0></a> 15 </td> 16 <td align=right> 17 <a href=dpans.htm#toc><img src=up.gif 18 width=26 height=26 align=ALIGN border=0></a> 19 <a name=A.11>Table of Contents</a> 20 </td> 21 </tr> 22 </table> 23 <p> 24 <hr size=4> 25 26 <H3>A.11 The optional File-Access word set</H3> 27 28 Many Forth systems support access to a host file system, and many of 29 these support interpretation of Forth from source text files. The 30 Forth-83 Standard did not address host OS files. Nevertheless, a degree 31 of similarity exists among modern implementations. 32 33 <P> 34 35 For example, files must be opened and closed, created and deleted. 36 Forth file-system implementations differ mostly in the treatment and 37 disposition of the exception codes, and in the format of the 38 file-identification strings. The underlying mechanism for creating 39 file-control blocks might or might not be visible. We have chosen to 40 keep it invisible. 41 42 <P> 43 44 Files must also be read and written. Text files, if supported, must be 45 read and written one line at a time. Interpretation of text files 46 implies that they are somehow integrated into the text interpreter input 47 mechanism. These and other requirements have shaped the file-access 48 extensions word set. 49 50 <P> 51 52 Most of the existing implementations studied use simple English words 53 for common host file functions: OPEN, CLOSE, READ, etc. Although we 54 would have preferred to do likewise, there were so many minor variations 55 in implementation of these words that adopting any particular meaning 56 would have broken much existing code. We have used names with a suffix 57 -FILE for most of these words. We encourage implementors to conform 58 their single-word primitives to the ANS behaviors, and hope that if this 59 is done on a widespread basis we can adopt better definition names in a 60 future standard. 61 62 <P> 63 64 Specific rationales 65 for members of this word set follow. 66 67 <P> 68 69 <hr> 70 <a name=A.11.3> 71 <H3>A.11.3 Additional usage requirements</H3> 72 </a> 73 74 <hr> 75 <a name=A.11.3.2> 76 <H4>A.11.3.2 Blocks in files</H4> 77 </a> 78 79 Many systems reuse file identifiers; when a file is closed, a 80 subsequently opened file may be given the same identifier. If the 81 original file has blocks still in block buffers, these will be 82 incorrectly associated with the newly opened file with disastrous 83 results. The block buffer system must be flushed to avoid this. 84 85 <P> 86 87 <hr> 88 <a name=A.11.6> 89 <H3>A.11.6 Glossary</H3> 90 </a> 91 92 93 <hr> 94 <a name=A.11.6.1.0765> 95 A.11.6.1.0765 BIN 96 </a> 97 <P> 98 99 Some operating systems require that files be opened in a different mode 100 to access their contents as an unstructured stream of binary data rather 101 than as a sequence of lines. 102 103 <P> 104 105 The arguments to 106 <a href=dpans11.htm#11.6.1.2080>READ-FILE</a> and 107 <a href=dpans11.htm#11.6.1.2480>WRITE-FILE</a> are 108 arrays of character 109 storage elements, each element consisting of at least 8 bits. The 110 Technical Committee intends that, in BIN mode, the contents of these 111 storage elements can be written to a file and later read back without 112 alteration. The Technical Committee has declined to address issues 113 regarding the impact of <B>wide</B> characters on the File and Block 114 word sets. 115 116 <P> 117 118 <hr> 119 <a name=A.11.6.1.1010> 120 A.11.6.1.1010 CREATE-FILE 121 </a> 122 <P> 123 124 Typical use: 125 126 <PRE> 127 : X .. S" TEST.FTH" R/W CREATE-FILE ABORT" CREATE-FILE FAILED" ... ; 128 </PRE> 129 <P> 130 131 <hr> 132 <a name=A.11.6.1.1717> 133 A.11.6.1.1717 INCLUDE-FILE 134 </a> 135 <P> 136 137 Here are two implementation alternatives for saving the input source 138 specification in the presence of text file input: 139 140 <P> 141 142 1) Save the file position (as returned by 143 <a href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>) of the beginning 144 of the line being interpreted. To restore the input source specification, 145 seek to that position and re-read the line into the input buffer. 146 147 <P> 148 149 2) Allocate a separate line buffer for each active text input file, using 150 that buffer as the input buffer. This method avoids the <B>seek and reread</B> 151 step, and allows the use of <B>pseudo-files</B> such as pipes and other 152 sequential-access-only communication channels. 153 154 <P> 155 156 <hr> 157 <a name=A.11.6.1.1718> 158 A.11.6.1.1718 INCLUDED 159 </a> 160 <P> 161 162 Typical use: <code>... S" filename" INCLUDED ...</code> 163 164 <P> 165 166 <hr> 167 <a name=A.11.6.1.1970> 168 A.11.6.1.1970 OPEN-FILE 169 </a> 170 <P> 171 172 Typical use: 173 174 <PRE> 175 : X .. S" TEST.FTH" R/W OPEN-FILE ABORT" OPEN-FILE FAILED" ... ; 176 </PRE> 177 <P> 178 179 <hr> 180 <a name=A.11.6.1.2080> 181 A.11.6.1.2080 READ-FILE 182 </a> 183 <P> 184 185 A typical sequential 186 file-processing algorithm might look like: 187 188 <PRE> 189 BEGIN ( ) 190 ... READ-FILE THROW ( length ) 191 ?DUP WHILE ( length ) 192 ... ( ) 193 REPEAT ( ) 194 </PRE> 195 196 <P> 197 198 In this example, 199 <a href=dpans9.htm#9.6.1.2275>THROW</a> 200 is used to handle (unexpected) exception 201 conditions, which are reported as non-zero values of the ior return 202 value from READ-FILE. End-of-file is reported as a zero value of the 203 <B>length</B> return value. 204 205 <P> 206 207 <hr> 208 <a name=A.11.6.1.2090> 209 A.11.6.1.2090 READ-LINE 210 </a> 211 <P> 212 213 Implementations are allowed to store the line terminator in the memory 214 buffer in order to allow the use of line reading functions provided by 215 host operating systems, some of which store the terminator. Without 216 this provision, a temporary buffer might be needed. The two-character 217 limitation is sufficient for the vast majority of existing operating 218 systems. Implementations on host operating systems whose line 219 terminator sequence is longer than two characters may have to take 220 special action to prevent the storage of more than two terminator 221 characters. 222 223 <P> 224 225 Standard Programs may not depend on the presence of any such terminator 226 sequence in the buffer. 227 228 <P> 229 230 A typical line-oriented sequential file-processing algorithm might look 231 like: 232 233 <PRE> 234 BEGIN ( ) 235 ... READ-LINE THROW ( length not-eof-flag ) 236 WHILE ( length ) 237 ... ( ) 238 REPEAT DROP ( ) 239 </PRE> 240 241 <P> 242 243 In this example, 244 <a href=dpans9.htm#9.6.1.2275>THROW</a> 245 is used to handle (unexpected) I/O exception condition, 246 which are reported as non-zero values of the <B>ior</B> return value from 247 READ-LINE. 248 249 <P> 250 251 READ-LINE needs a separate end-of-file flag because empty (zero-length) lines 252 are a routine occurrence, so a zero-length line cannot be used to signify 253 end-of-file. 254 255 <P> 256 257 <hr> 258 <a name=A.11.6.1.2165> 259 A.11.6.1.2165 S" 260 </a> 261 <P> 262 263 Typical use: <code>... S" ccc" ...</code> 264 265 <P> 266 267 The interpretation semantics for S" are intended to provide a simple 268 mechanism for entering a string in the interpretation state. Since an 269 implementation may choose to provide only one buffer for interpreted 270 strings, an interpreted string is subject to being overwritten by the 271 next execution of S" in interpretation state. It is intended that no 272 standard words other than S" should in themselves cause the interpreted 273 string to be overwritten. However, since words such as 274 <a href=dpans6.htm#6.1.1360>EVALUATE</a>, 275 <a href=dpans7.htm#7.6.1.1790>LOAD</a>, 276 <a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a> and 277 <a href=dpans11.htm#11.6.1.1718>INCLUDED</a> 278 can result in the interpretation of arbitrary 279 text, possibly including instances of S", the interpreted string may be 280 invalidated by some uses of these words. 281 282 <P> 283 284 When the possibility of overwriting a string can arise, it is prudent to 285 copy the string to a <B>safe</B> buffer allocated by the application. 286 287 <P> 288 289 Programs wishing to parse in the fashion of S" are advised to use 290 <a href=dpans6.htm#6.2.2008>PARSE</a> 291 or 292 <a href=dpans6.htm#6.1.2450>WORD</a> 293 <a href=dpans6.htm#6.1.0980>COUNT</a> 294 instead of S", preventing the overwriting of the 295 interpreted string buffer. 296 297 <P> 298 299 <hr> 300 <A href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents 301 <BR> 302 <A href=dpansa12.htm><IMG src="right.gif" ></A> 303 Next Section 304 <P> 305 </BODY> 306 </HTML>