DPANS11.HTM (27930B)
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=dpans10.htm><img src=left.gif 12 width=26 height=26 align=ALIGN border=0></a> 13 <a href=dpans12.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=11.>Table of Contents</a> 20 </td> 21 </tr> 22 </table> 23 <p> 24 <hr size=4> 25 26 <H1>11. The optional File-Access word set</H1> 27 28 <p> 29 <code> 30 See: 31 <a href=dpansa11.htm#A.11>A.11</a> The optional File-Access word set 32 </code> 33 <p> 34 35 <hr> 36 <A name=11.1> 37 <H2>11.1 Introduction</H2> 38 </a> 39 40 These words provide access to mass storage in the form of <B>files</B> 41 under the following assumptions: 42 43 <UL> 44 <LI>files are provided by a host operating system; 45 <LI>file names are represented as character strings; 46 <LI>the format of file names is determined by the host operating system; 47 <LI>an open file is identified by a single-cell file identifier (fileid); 48 <LI>file-state information (e.g., position, size) is managed by the 49 host operating system; 50 <LI>file contents are accessed as a sequence of characters; 51 <LI>file read operations return an actual transfer count, which can 52 differ from the requested transfer count. 53 </UL> 54 55 <P> 56 57 <hr> 58 <A name=11.2> 59 <H2>11.2 Additional terms</H2> 60 </a> 61 62 <dl> 63 <dt><b>file-access method:</b> 64 <dd>A permissible means of accessing a file, such as <B>read/write</B> or <B>read only</B>. 65 66 <dt><b>file position:</b> 67 <dd>The character offset from the start of the file. 68 69 <dt><b>input file:</b> 70 <dd>The file, containing a sequence of lines, that is the input source. 71 </dl> 72 73 74 <hr> 75 <A name=11.3> 76 <H2>11.3 Additional usage requirements</H2> 77 </a> 78 79 80 81 <hr> 82 <A name=11.3.1> 83 <H3>11.3.1 Data types</H3> 84 </a> 85 86 Append table 11.1 to 87 <a href=dpans3.htm#table.3.1>table 3.1</a>. 88 <P> 89 90 Table 11.1 - Data types 91 <P> 92 93 94 95 <PRE> 96 Symbol Data type Size on stack 97 ------ --------- ------------- 98 ior I/O results 1 cell 99 fam file access method 1 cell 100 fileid file identifiers 1 cell 101 </PRE> 102 103 <P> 104 105 <hr> 106 <A name=11.3.1.1> 107 <H4>11.3.1.1 File identifiers</H4> 108 </a> 109 110 File identifiers are implementation-dependent single-cell values that 111 are passed to file operators to designate specific files. Opening a 112 file assigns a file identifier, which remains valid until closed. 113 114 115 <P> 116 117 <hr> 118 <A name=11.3.1.2> 119 <H4>11.3.1.2 I/O results</H4> 120 </a> 121 122 I/O results are single-cell numbers indicating the result of I/O 123 operations. A value of zero indicates that the I/O operation completed 124 successfully; other values and their meanings are 125 implementation-defined. Reaching the end of a file shall be reported as 126 zero. 127 128 <P> 129 130 An I/O exception in the execution of a File-Access word that can return 131 an I/O result shall not cause a 132 <a href=dpans9.htm#9.6.1.2275>THROW</a>; exception indications are 133 returned in the ior. 134 135 <P> 136 137 <hr> 138 <A name=11.3.1.3> 139 <H4>11.3.1.3 File access methods</H4> 140 </a> 141 142 File access methods are implementation-defined single-cell 143 values. 144 145 <P> 146 147 <hr> 148 <A name=11.3.1.4> 149 <H4>11.3.1.4 File names</H4> 150 </a> 151 152 A character string containing the name of the file. The file name may 153 include an implementation-dependent path name. The format of file names 154 is implementation defined. 155 156 <P> 157 158 <hr> 159 <A name=11.3.2> 160 <H3>11.3.2 Blocks in files</H3> 161 </a> 162 163 If the File-Access word set is implemented, the 164 <a href=dpans7.htm>Block word set</a> shall be 165 implemented. 166 167 <P> 168 169 Blocks may, but need not, reside in files. When they do: 170 <P> 171 172 <UL> 173 <LI>Block numbers may be mapped to one or more files by 174 implementation-defined means. An ambiguous condition exists if a 175 requested block number is not currently mapped; 176 <LI>An 177 <a href=dpans7.htm#7.6.1.2400>UPDATE</a>d 178 block that came from a file shall be transferred back 179 to the same file. 180 </UL> 181 182 <p> 183 <code> 184 See: 185 <a href=dpansa11.htm#A.11.3.2>A.11.3.2</a> Blocks in files 186 </code> 187 <p> 188 189 190 <hr> 191 <A name=11.3.3> 192 <H3>11.3.3 Environmental queries</H3> 193 </a> 194 195 Append table 11.2 to 196 table 3.5. 197 198 <P> 199 200 <code> 201 See: 202 <A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries 203 </code> 204 <P> 205 206 Table 11.2 - Environmental query strings 207 <P> 208 209 210 211 <PRE> 212 String Value data type Constant? Meaning 213 ------ --------------- --------- ------- 214 FILE flag no file word set present 215 FILE-EXT flag no file extensions word set present 216 </PRE> 217 218 <P> 219 220 <hr> 221 <A name=11.3.4> 222 <H3>11.3.4 Input source</H3> 223 </a> 224 225 The File-Access word set creates another input source for the text 226 interpreter. When the input source is a text file, 227 <a href=dpans7.htm#7.6.1.0790>BLK</a> shall contain 228 zero, 229 <a href=dpans6.htm#6.2.2218>SOURCE-ID</a> 230 shall contain the fileid of that text file, and the 231 input buffer shall contain one line of the text file. 232 233 <P> 234 235 Input with 236 <a href=dpans11.htm#11.6.1.1718>INCLUDED</a>, 237 <a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a>, 238 <a href=dpans7.htm#7.6.1.1790>LOAD</a> and 239 <a href=dpans6.htm#6.1.1360>EVALUATE</a> shall be nestable 240 in any order to at least eight levels. 241 242 <P> 243 244 A program that uses more than eight levels of input-file nesting has an 245 environmental dependency. 246 247 <P> 248 249 <code> 250 See: 251 <A href=dpans3.htm#3.3.3.5>3.3.3.5</a> Input buffers, 252 <A href=dpans9.htm#9.>9.</a> Optional Exception word set. 253 </code> 254 <P> 255 256 257 <hr> 258 <A name=11.3.5> 259 <H3>11.3.5 Other transient regions</H3> 260 </a> 261 262 The list of words using memory in transient regions is extended to 263 include <A href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S". 264 265 <P> 266 267 <code> 268 See: 269 <A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions 270 </code> 271 <P> 272 273 274 <P> 275 276 <hr> 277 <A name=11.3.6> 278 <H3>11.3.6 Parsing</H3> 279 </a> 280 281 When parsing from a text file using a space delimiter, control 282 characters shall be treated the same as the space character. 283 284 <P> 285 286 Lines of at least 128 characters shall be supported. A program that 287 requires lines of more than 128 characters has an environmental 288 dependency. 289 290 <P> 291 292 A program may reposition the parse area within the input buffer by 293 manipulating the contents of 294 <a href=dpans6.htm#6.1.0560>>IN</a>. 295 More extensive repositioning can be 296 accomplished using 297 <a href=dpans6.htm#6.2.2182>SAVE-INPUT</a> and 298 <a href=dpans6.htm#6.2.2148>RESTORE-INPUT</a>. 299 300 <P> 301 302 <code> 303 See: 304 <A href=dpans3.htm#3.4.1>3.4.1</a> Parsing 305 </code> 306 <P> 307 308 <hr> 309 <A name=11.4> 310 <H2>11.4 Additional documentation requirements</H2> 311 </a> 312 313 314 <hr> 315 <A name=11.4.1> 316 <H3>11.4.1 System documentation</H3> 317 </a> 318 319 320 <hr> 321 <A name=11.4.1.1> 322 <H4>11.4.1.1 Implementation-defined options</H4> 323 </a> 324 325 326 <UL> 327 <LI>file access methods used by 328 <a href=dpans11.htm#11.6.1.0765>11.6.1.0765</a> BIN, 329 <a href=dpans11.htm#11.6.1.1010>11.6.1.1010</a> CREATE-FILE, 330 <a href=dpans11.htm#11.6.1.1970>11.6.1.1970</a> OPEN-FILE, 331 <a href=dpans11.htm#11.6.1.2054>11.6.1.2054</a> R/O, 332 <a href=dpans11.htm#11.6.1.2056>11.6.1.2056</a> R/W, 333 and 334 <a href=dpans11.htm#11.6.1.2425>11.6.1.2425</a> W/O; 335 <LI>file exceptions; 336 <LI>file line terminator 337 (<a href=dpans11.htm#11.6.1.2090>11.6.1.2090</a> READ-LINE); 338 <LI>file name format 339 (<a href=dpans11.htm#11.3.1.4>11.3.1.4</a> File names); 340 <LI>Information returned by 341 <a href=dpans11.htm#11.6.2.1524>11.6.2.1524</a> FILE-STATUS; 342 <LI>Input file state after an exception 343 (<a href=dpans11.htm#11.6.1.1717>11.6.1.1717</a> INCLUDE-FILE, 344 <a href=dpans11.htm#11.6.1.1718>11.6.1.1718</a> INCLUDED); 345 <LI>ior values and meaning 346 (<a href=dpans11.htm#11.3.1.2>11.3.1.2</a> I/O results); 347 <LI>maximum depth of file input nesting 348 (<a href=dpans11.htm#11.3.4>11.3.4</a> Input source); 349 <LI>maximum size of input line 350 (<a href=dpans11.htm#11.3.6>11.3.6</a> Parsing); 351 <LI>methods for mapping block ranges to files 352 (<a href=dpans11.htm#11.3.2>11.3.2</a> Blocks in files); 353 <LI>number of string buffers provided 354 (<a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S"); 355 <LI>size of string buffer used by 356 <a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S". 357 </UL> 358 359 360 <hr> 361 <A name=11.4.1.2> 362 <H4>11.4.1.2 Ambiguous conditions</H4> 363 </a> 364 365 <UL> 366 <LI>attempting to position a file outside its boundaries 367 (<a href=dpans11.htm#11.6.1.2142>11.6.1.2142</a> REPOSITION-FILE); 368 <LI>attempting to read from file positions not yet written 369 (<a href=dpans11.htm#11.6.1.2080>11.6.1.2080</a> READ-FILE, 370 <a href=dpans11.htm#11.6.1.2090>11.6.1.2090</a> READ-LINE); 371 <LI>fileid is invalid 372 (<a href=dpans11.htm#11.6.1.1717>11.6.1.1717</a> INCLUDE-FILE); 373 <LI>I/O exception reading or closing fileid 374 (<a href=dpans11.htm#11.6.1.1717>11.6.1.1717</a> INCLUDE-FILE, 375 <a href=dpans11.htm#11.6.1.1718>11.6.1.1718</a> INCLUDED); 376 <LI>named file cannot be opened 377 (<a href=dpans11.htm#11.6.1.1718>11.6.1.1718</a> INCLUDED); 378 <LI>requesting an unmapped block number 379 (<a href=dpans11.htm#11.3.2>11.3.2</a> Blocks in files); 380 <LI>using 381 <a href=dpans11.htm#11.6.1.2218>11.6.1.2218</a> SOURCE-ID when 382 <a href=dpans7.htm#7.6.1.0790>7.6.1.0790</a> BLK is not zero. 383 </ul> 384 385 <hr> 386 <A name=11.4.3> 387 <h4>11.4.1.3 Other system documentation</h4> 388 </a> 389 <ul> 390 <LI>no additional requirements. 391 </UL> 392 393 <hr> 394 <A name=11.4.2> 395 <H3>11.4.2 Program documentation</H3> 396 </a> 397 398 399 <hr> 400 <A name=11.4.2.1> 401 <H4>11.4.2.1 Environmental dependencies</H4> 402 </a> 403 404 <UL> 405 <LI>requiring lines longer than 128 characters 406 (<a href=dpans11.htm#11.3.6>11.3.6</a> Parsing); 407 <LI>using more than eight levels of input-file nesting 408 (<a href=dpans11.htm#11.3.4>11.3.4</a> Input source). 409 </UL> 410 411 <P> 412 413 <hr> 414 <A name=11.4.2.2> 415 <H4>11.4.2.2 Other program documentation</H4> 416 </a> 417 418 <UL> 419 <LI>no additional requirements. 420 </ul> 421 422 423 <hr> 424 <A name=11.5> 425 <h2>11.5 Compliance and labeling</h2> 426 </a> 427 428 429 <hr> 430 <A name=11.5.1> 431 <H3>11.5.1 ANS Forth systems</H3> 432 </a> 433 434 The phrase <B>Providing the File Access word set</B> shall be appended 435 to the label of any Standard System that provides all of the File Access 436 word set. 437 438 <P> 439 440 The phrase <B>Providing name(s) from the File Access Extensions word 441 set</B> shall be appended to the label of any Standard System that 442 provides portions of the File Access Extensions word set. 443 444 <P> 445 446 The phrase <B>Providing the File Access Extensions word set</B> shall be 447 appended to the label of any Standard System that provides all of the 448 File Access and File Access Extensions word sets. 449 450 451 <P> 452 453 <hr> 454 <A name=11.5.2> 455 <H3>11.5.2 ANS Forth programs</H3> 456 </a> 457 458 The phrase <B>Requiring the File Access word set</B> shall be appended 459 to the label of Standard Programs that require the system to provide the 460 File Access word set. 461 462 <P> 463 464 The phrase <B>Requiring name(s) from the File Access Extensions word 465 set</B> shall be appended to the label of Standard Programs that require 466 the system to provide portions of the File Access Extensions word set. 467 468 <P> 469 470 The phrase <B>Requiring the File Access Extensions word set</B> shall be 471 appended to the label of Standard Programs that require the system to 472 provide all of the File Access and File Access Extensions word sets. 473 474 <P> 475 476 <hr> 477 <A name=11.6> 478 <H2>11.6 Glossary</H2> 479 </a> 480 481 482 <hr> 483 <A name=11.6.1> 484 <H3>11.6.1 File Access words</H3> 485 </a> 486 487 488 <hr> 489 <A name=11.6.1.0080> 490 <code> 491 11.6.1.0080 <b>(</b> 492 </code> 493 </a> 494 <BR> 495 <B>paren</B> FILE 496 <BR> 497 <pre> 498 ( <B>"ccc<paren>"</B> -- ) 499 </pre> 500 <P> 501 502 Extend the semantics of 503 <A href=dpans6.htm#6.1.0080>6.1.0080</a> ( to include: 504 <P> 505 506 When parsing from a text file, if the end of the parse area is reached 507 before a right parenthesis is found, refill the input buffer from the 508 next line of the file, set 509 <A href=dpans6.htm#6.1.0560>>IN</a> 510 to zero, and resume parsing, repeating 511 this process until either a right parenthesis is found or the end of the 512 file is reached. 513 514 <P> 515 516 <hr> 517 <A name=11.6.1.0765> 518 <code> 519 11.6.1.0765 <b>BIN</b> 520 </code> 521 </a> 522 <BR> 523 FILE 524 <BR> 525 <pre> 526 ( fam1 -- fam2 ) 527 </pre> 528 <P> 529 530 Modify the implementation-defined file access method fam1 to 531 additionally select a <B>binary</B>, i.e., not line oriented, file 532 access method, giving access method fam2. 533 <p> 534 535 <code> 536 See: 537 <a href=dpansa11.htm#A.11.6.1.0765>A.11.6.1.0765 BIN</a> , 538 <A href=dpans11.htm#11.6.1.2054>11.6.1.2054 R/O</a> , 539 <A href=dpans11.htm#11.6.1.2056>11.6.1.2056 R/W</a> , 540 <A href=dpans11.htm#11.6.1.2425>11.6.1.2425 W/O</a> 541 </code> 542 543 <P> 544 545 <hr> 546 <A name=11.6.1.0900> 547 <code> 548 11.6.1.0900 <b>CLOSE-FILE</b> 549 </code> 550 </a> 551 <BR> 552 FILE 553 <BR> 554 <pre> 555 ( fileid -- ior ) 556 </pre> 557 <P> 558 559 Close the file identified by fileid. ior is the implementation-defined 560 I/O result code. 561 562 <P> 563 564 <hr> 565 <A name=11.6.1.1010> 566 <code> 567 11.6.1.1010 <b>CREATE-FILE</b> 568 </code> 569 </a> 570 <BR> 571 FILE 572 <BR> 573 <pre> 574 ( c-addr u fam -- fileid ior ) 575 </pre> 576 <P> 577 578 Create the file named in the character string specified by c-addr and u, 579 and open it with file access method fam. The meaning of values of fam 580 is implementation defined. If a file with the same name already exists, 581 recreate it as an empty file. 582 583 <P> 584 585 If the file was successfully created and opened, ior is zero, fileid is 586 its identifier, and the file has been positioned to the start of the 587 file. 588 589 <P> 590 591 Otherwise, ior is the implementation-defined I/O result code and fileid 592 is undefined. 593 594 <p> 595 <code> 596 See: 597 <a href=dpansa11.htm#A.11.6.1.1010>A.11.6.1.1010 CREATE-FILE</a> 598 </code> 599 <p> 600 601 602 <hr> 603 <A name=11.6.1.1190> 604 <code> 605 11.6.1.1190 <b>DELETE-FILE</b> 606 </code> 607 </a> 608 <BR> 609 FILE 610 <BR> 611 <pre> 612 ( c-addr u -- ior ) 613 </pre> 614 <P> 615 616 Delete the file named in the character string specified by c-addr u. 617 ior is the implementation-defined I/O result code. 618 619 <P> 620 621 <hr> 622 <A name=11.6.1.1520> 623 <code> 624 11.6.1.1520 <b>FILE-POSITION</b> 625 </code> 626 </a> 627 <BR> 628 FILE 629 <BR> 630 <pre> 631 ( fileid -- ud ior ) 632 </pre> 633 <P> 634 635 ud is the current file position for the file identified by fileid. ior 636 is the implementation-defined I/O result code. ud is undefined if ior 637 is non-zero. 638 639 <P> 640 641 <hr> 642 <A name=11.6.1.1522> 643 <code> 644 11.6.1.1522 <b>FILE-SIZE</b> 645 </code> 646 </a> 647 <BR> 648 FILE 649 <BR> 650 <pre> 651 ( fileid -- ud ior ) 652 </pre> 653 <P> 654 655 ud is the size, in characters, of the file identified by fileid. ior is 656 the implementation-defined I/O result code. This operation does not 657 affect the value returned by 658 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>. 659 ud is undefined if ior is 660 non-zero. 661 662 <P> 663 664 <hr> 665 <A name=11.6.1.1717> 666 <code> 667 11.6.1.1717 <b>INCLUDE-FILE</b> 668 </code> 669 </a> 670 <BR> 671 FILE 672 <BR> 673 <pre> 674 ( i*x fileid -- j*x ) 675 </pre> 676 <P> 677 678 Remove fileid from the stack. Save the current input source 679 specification, including the current value of 680 <A href=dpans6.htm#6.2.2218>SOURCE-ID</a>. Store fileid 681 in SOURCE-ID. Make the file specified by fileid the input source. 682 Store zero in 683 <A href=dpans7.htm#7.6.1.0790>BLK</a>. 684 Other stack effects are due to the words included. 685 686 <P> 687 688 Repeat until end of file: read a line from the file, fill the input 689 buffer from the contents of that line, set 690 <A href=dpans6.htm#6.1.0560>>IN</a> to zero, and interpret. 691 692 <P> 693 694 Text interpretation begins at the file position where the next file read 695 would occur. 696 697 <P> 698 699 When the end of the file is reached, close the file and restore the 700 input source specification to its saved value. 701 702 <P> 703 704 An ambiguous condition exists if fileid is invalid, if there is an I/O 705 exception reading fileid, or if an I/O exception occurs while closing 706 fileid. When an ambiguous condition exists, the status (open or closed) 707 of any files that were being interpreted is implementation-defined. 708 <P> 709 710 <code> 711 See: 712 <A href=dpans11.htm#11.3.4>11.3.4</a> Input source, 713 <a href=dpansa11.htm#A.11.6.1.1717>A.11.6.1.1717 INCLUDE-FILE</a> 714 </code> 715 <p> 716 717 718 <hr> 719 <A name=11.6.1.1718> 720 <code> 721 11.6.1.1718 <b>INCLUDED</b> 722 </code> 723 </a> 724 <BR> 725 FILE 726 <BR> 727 <pre> 728 ( i*x c-addr u -- j*x ) 729 </pre> 730 <P> 731 732 Remove c-addr u from the stack. Save the current input source 733 specification, including the current value of 734 <A href=dpans6.htm#6.2.2218>SOURCE-ID</a>. Open the file 735 specified by c-addr u, store the resulting fileid in SOURCE-ID, and make 736 it the input source. Store zero in 737 <A href=dpans7.htm#7.6.1.0790>BLK</a>. Other stack effects are due to 738 the words included. 739 740 <P> 741 742 Repeat until end of file: read a line from the file, fill the input 743 buffer from the contents of that line, set 744 <A href=dpans6.htm#6.1.0560>>IN</a> to zero, and interpret. 745 746 <P> 747 748 Text interpretation begins at the file position where the next file read 749 would occur. 750 751 <P> 752 753 When the end of the file is reached, close the file and restore the 754 input source specification to its saved value. 755 756 <P> 757 758 An ambiguous condition exists if the named file can not be opened, if an 759 I/O exception occurs reading the file, or if an I/O exception occurs 760 while closing the file. When an ambiguous condition exists, the status 761 (open or closed) of any files that were being interpreted is 762 implementation-defined. 763 764 <P> 765 766 <code> 767 See: 768 <a href=dpansa11.htm#A.11.6.1.1718>A.11.6.1.1718 INCLUDED</a> , 769 <A href=dpans11.htm#11.6.1.1717>11.6.1.1717 INCLUDE-FILE</a> 770 </code> 771 772 <P> 773 774 <hr> 775 <A name=11.6.1.1970> 776 <code> 777 11.6.1.1970 <b>OPEN-FILE</b> 778 </code> 779 </a> 780 <BR> 781 FILE 782 <BR> 783 <pre> 784 ( c-addr u fam -- fileid ior ) 785 </pre> 786 <P> 787 788 Open the file named in the character string specified by c-addr u, with 789 file access method indicated by fam. The meaning of values of fam is 790 implementation defined. 791 792 <P> 793 794 If the file is successfully opened, ior is zero, fileid is its 795 identifier, and the file has been positioned to the start of the file. 796 797 <P> 798 799 Otherwise, ior is the implementation-defined I/O result code and fileid 800 is undefined. 801 802 <p> 803 <code> 804 See: 805 <a href=dpansa11.htm#A.11.6.1.1970>A.11.6.1.1970 OPEN-FILE</a> 806 </code> 807 <p> 808 809 810 <hr> 811 <A name=11.6.1.2054> 812 <code> 813 11.6.1.2054 <b>R/O</b> 814 </code> 815 </a> 816 <BR> 817 <B>r-o</B> FILE 818 <BR> 819 <pre> 820 ( -- fam ) 821 </pre> 822 <P> 823 824 fam is the implementation-defined value for selecting the <B>read 825 only</B> file access method. 826 <p> 827 828 <code> 829 See: 830 <A href=dpans11.htm#11.6.1.1010>11.6.1.1010 CREATE-FILE</a> , 831 <A href=dpans11.htm#11.6.1.1970>11.6.1.1970 OPEN-FILE</a> 832 </code> 833 834 <P> 835 836 <hr> 837 <A name=11.6.1.2056> 838 <code> 839 11.6.1.2056 <b>R/W</b> 840 </code> 841 </a> 842 <BR> 843 <B>r-w</B> FILE 844 <BR> 845 <pre> 846 ( -- fam ) 847 </pre> 848 <P> 849 850 fam is the implementation-defined value for selecting the 851 <B>read/write</B> file access method. 852 <p> 853 854 <code> 855 See: 856 <A href=dpans11.htm#11.6.1.1010>11.6.1.1010 CREATE-FILE</a> , 857 <A href=dpans11.htm#11.6.1.1970>11.6.1.1970 OPEN-FILE</a> 858 </code> 859 860 <P> 861 862 <hr> 863 <A name=11.6.1.2080> 864 <code> 865 11.6.1.2080 <b>READ-FILE</b> 866 </code> 867 </a> 868 <BR> 869 FILE 870 <BR> 871 <pre> 872 ( c-addr u1 fileid -- u2 ior ) 873 </pre> 874 <P> 875 876 Read u1 consecutive characters to c-addr from the current position of 877 the file identified by fileid. 878 879 <P> 880 881 If u1 characters are read without an exception, ior is zero and u2 is 882 equal to u1. 883 884 <P> 885 886 If the end of the file is reached before u1 characters are read, ior is 887 zero and u2 is the number of characters actually read. 888 889 <P> 890 891 If the operation is initiated when the value returned by 892 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> 893 is equal to the value returned by 894 <A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> for the file identified by 895 fileid, ior is zero and u2 is zero. 896 897 <P> 898 899 If an exception occurs, ior is the implementation-defined I/O result 900 code, and u2 is the number of characters transferred to c-addr without 901 an exception. 902 903 <P> 904 905 An ambiguous condition exists if the operation is initiated when the 906 value returned by FILE-POSITION is greater than the value returned by 907 FILE-SIZE for the file identified by fileid, or if the requested 908 operation attempts to read portions of the file not written. 909 910 <P> 911 912 At the conclusion of the operation, FILE-POSITION returns the next file 913 position after the last character read. 914 915 <p> 916 <code> 917 See: 918 <a href=dpansa11.htm#A.11.6.1.2080>A.11.6.1.2080 READ-FILE</a> 919 </code> 920 <p> 921 922 923 <hr> 924 <A name=11.6.1.2090> 925 <code> 926 11.6.1.2090 <b>READ-LINE</b> 927 </code> 928 </a> 929 <BR> 930 FILE 931 <BR> 932 <pre> 933 ( c-addr u1 fileid -- u2 flag ior ) 934 </pre> 935 <P> 936 937 Read the next line from the file specified by fileid into memory at the 938 address c-addr. At most u1 characters are read. Up to two 939 implementation-defined line-terminating characters may be read into 940 memory at the end of the line, but are not included in the count u2. 941 The line buffer provided by c-addr should be at least u1+2 characters 942 long. 943 944 <P> 945 946 If the operation succeeded, flag is true and ior is zero. If a line 947 terminator was received before u1 characters were read, then u2 is the 948 number of characters, not including the line terminator, actually read 949 (0 <= u2 <= u1). When u1 = u2, the line terminator has yet to be 950 reached. 951 952 <P> 953 954 If the operation is initiated when the value returned by 955 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> 956 is equal to the value returned by 957 <A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> for the file identified by 958 fileid, flag is false, ior is zero, and u2 is zero. If ior is non-zero, 959 an exception occurred during the operation and ior is the 960 implementation-defined I/O result code. 961 962 <P> 963 964 An ambiguous condition exists if the operation is initiated when the 965 value returned by FILE-POSITION is greater than the value returned by 966 FILE-SIZE for the file identified by fileid, or if the requested 967 operation attempts to read portions of the file not written. 968 969 <P> 970 971 At the conclusion of the operation, FILE-POSITION returns the next file 972 position after the last character read. 973 974 <p> 975 <code> 976 See: 977 <a href=dpansa11.htm#A.11.6.1.2090>A.11.6.1.2090 READ-LINE</a> , 978 <a href=a0001.htm>RFI 0001</a>. 979 </code> 980 <p> 981 982 983 <hr> 984 <A name=11.6.1.2142> 985 <code> 986 11.6.1.2142 <b>REPOSITION-FILE</b> 987 </code> 988 </a> 989 <BR> 990 FILE 991 <BR> 992 <pre> 993 ( ud fileid -- ior ) 994 </pre> 995 <P> 996 997 Reposition the file identified by fileid to ud. ior is the 998 implementation-defined I/O result code. An ambiguous condition exists 999 if the file is positioned outside the file boundaries. 1000 1001 <P> 1002 1003 At the conclusion of the operation, 1004 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> returns the 1005 value ud. 1006 1007 <P> 1008 1009 <hr> 1010 <A name=11.6.1.2147> 1011 <code> 1012 11.6.1.2147 <b>RESIZE-FILE</b> 1013 </code> 1014 </a> 1015 <BR> 1016 FILE 1017 <BR> 1018 <pre> 1019 ( ud fileid -- ior ) 1020 </pre> 1021 <P> 1022 1023 Set the size of the file identified by fileid to ud. ior is the 1024 implementation-defined I/O result code. 1025 1026 <P> 1027 1028 If the resultant file is larger than the file before the operation, the 1029 portion of the file added as a result of the operation might not have 1030 been written. 1031 1032 <P> 1033 1034 At the conclusion of the operation, 1035 <A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> returns the value ud and 1036 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> 1037 returns an unspecified value. 1038 <p> 1039 1040 <code> 1041 See: 1042 <A href=dpans11.htm#11.6.1.2080>11.6.1.2080 READ-FILE</a> , 1043 <A href=dpans11.htm#11.6.1.2090>11.6.1.2090 READ-LINE</a> 1044 </code> 1045 1046 <P> 1047 1048 <hr> 1049 <A name=11.6.1.2165> 1050 <code> 1051 11.6.1.2165 <b>S"</b> 1052 </code> 1053 </a> 1054 <BR> 1055 <B>s-quote</B> FILE 1056 <BR> 1057 <P> 1058 1059 Extend the semantics of 1060 <A href=dpans6.htm#6.1.2165>6.1.2165</a> S" to be: 1061 1062 <PRE> 1063 Interpretation: ( <B>"ccc<quote>"</B> -- c-addr u ) 1064 </PRE> 1065 <P> 1066 1067 Parse ccc delimited by " (double quote). Store the resulting string 1068 c-addr u at a temporary location. The maximum length of the temporary 1069 buffer is implementation-dependent but shall be no less than 80 1070 characters. Subsequent uses of S" may overwrite the temporary buffer. 1071 At least one such buffer shall be provided. 1072 1073 1074 <PRE> 1075 Compilation: ( <B>"ccc<quote>"</B> -- ) 1076 </PRE> 1077 1078 <P> 1079 1080 Parse ccc delimited by " (double quote). Append the run-time semantics 1081 given below to the current definition. 1082 1083 <PRE> 1084 Run-time: ( -- c-addr u ) 1085 </PRE> 1086 <P> 1087 1088 Return c-addr and u that describe a string consisting of the characters 1089 ccc. 1090 1091 <P> 1092 1093 <code> 1094 See: 1095 <A href=dpans3.htm#3.4.1>3.4.1</a> Parsing, 1096 <A href=dpans6.htm#6.2.0855>6.2.0855 C"</a> , 1097 <a href=dpansa11.htm#A.11.6.1.2165>A.11.6.1.2165 S"</a> , 1098 <A href=dpans11.htm#11.3.5>11.3.5</a> Other transient regions. 1099 </code> 1100 1101 <P> 1102 1103 <hr> 1104 <A name=11.6.1.2218> 1105 <code> 1106 11.6.1.2218 <b>SOURCE-ID</b> 1107 </code> 1108 </a> 1109 <BR> 1110 <B>source-i-d</B> FILE 1111 <BR> 1112 <pre> 1113 ( -- 0 | -1 | fileid ) 1114 </pre> 1115 <P> 1116 1117 Extend 1118 <A href=dpans6.htm#6.2.2218>6.2.2218</a> 1119 SOURCE-ID to include text-file input as follows: 1120 1121 1122 <PRE> 1123 SOURCE-ID Input source 1124 --------- ------------ 1125 fileid Text file <B>fileid</B> 1126 -1 String (via <A href=dpans6.htm#6.1.1360>EVALUATE</a>) 1127 0 User input device 1128 </PRE> 1129 <P> 1130 1131 An ambiguous condition exists if SOURCE-ID is used when 1132 <A href=dpans7.htm#7.6.1.0790>BLK</a> contains a 1133 non-zero value. 1134 1135 <P> 1136 1137 <hr> 1138 <A name=11.6.1.2425> 1139 <code> 1140 11.6.1.2425 <b>W/O</b> 1141 </code> 1142 </a> 1143 <BR> 1144 <B>w-o</B> FILE 1145 <BR> 1146 <pre> 1147 ( -- fam ) 1148 </pre> 1149 <P> 1150 1151 fam is the implementation-defined value for selecting the <B>write 1152 only</B> file access method. 1153 <p> 1154 1155 <code> 1156 See: 1157 <A href=dpans11.htm#11.6.1.1010>11.6.1.1010 CREATE-FILE</a> , 1158 <A href=dpans11.htm#11.6.1.1970>11.6.1.1970 OPEN-FILE</a> 1159 </code> 1160 1161 <P> 1162 1163 <hr> 1164 <A name=11.6.1.2480> 1165 <code> 1166 11.6.1.2480 <b>WRITE-FILE</b> 1167 </code> 1168 </a> 1169 <BR> 1170 FILE 1171 <BR> 1172 <pre> 1173 ( c-addr u fileid -- ior ) 1174 </pre> 1175 <P> 1176 1177 Write u characters from c-addr to the file identified by fileid starting 1178 at its current position. ior is the implementation-defined I/O result 1179 code. 1180 1181 <P> 1182 1183 At the conclusion of the operation, 1184 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> returns the next file 1185 position after the last character written to the file, and 1186 <A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> 1187 returns a value greater than or equal to the value returned by 1188 FILE-POSITION. 1189 <p> 1190 1191 <code> 1192 See: 1193 <A href=dpans11.htm#11.6.1.2080>11.6.1.2080 READ-FILE</a> , 1194 <A href=dpans11.htm#11.6.1.2090>11.6.1.2090 READ-LINE</a> 1195 </code> 1196 1197 <P> 1198 1199 <hr> 1200 <A name=11.6.1.2485> 1201 <code> 1202 11.6.1.2485 <b>WRITE-LINE</b> 1203 </code> 1204 </a> 1205 <BR> 1206 FILE 1207 <BR> 1208 <pre> 1209 ( c-addr u fileid -- ior ) 1210 </pre> 1211 <P> 1212 1213 Write u characters from c-addr followed by the implementation-dependent 1214 line terminator to the file identified by fileid starting at its current 1215 position. ior is the implementation-defined I/O result code. 1216 1217 <P> 1218 1219 At the conclusion of the operation, 1220 <A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> returns the next file 1221 position after the last character written to the file, and 1222 <A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> 1223 returns a value greater than or equal to the value returned by 1224 FILE-POSITION. 1225 <p> 1226 1227 <code> 1228 See: 1229 <A href=dpans11.htm#11.6.1.2080>11.6.1.2080 READ-FILE</a> , 1230 <A href=dpans11.htm#11.6.1.2090>11.6.1.2090 READ-LINE</a> 1231 </code> 1232 1233 <P> 1234 1235 <hr> 1236 <a name=11.6.2> 1237 <H3>11.6.2 File-Access extension words</H3> 1238 </a> 1239 1240 1241 <hr> 1242 <A name=11.6.2.1524> 1243 <code> 1244 11.6.2.1524 <b>FILE-STATUS</b> 1245 </code> 1246 </a> 1247 <BR> 1248 FILE EXT 1249 <BR> 1250 <pre> 1251 ( c-addr u -- x ior ) 1252 </pre> 1253 <P> 1254 1255 Return the status of the file identified by the character string c-addr 1256 u. If the file exists, ior is zero; otherwise ior is the 1257 implementation-defined I/O result code. x contains 1258 implementation-defined information about the file. 1259 1260 <P> 1261 1262 <hr> 1263 <A name=11.6.2.1560> 1264 <code> 1265 11.6.2.1560 <b>FLUSH-FILE</b> 1266 </code> 1267 </a> 1268 <BR> 1269 FILE EXT 1270 <BR> 1271 <pre> 1272 ( fileid -- ior ) 1273 </pre> 1274 <P> 1275 1276 Attempt to force any buffered information written to the file referred 1277 to by fileid to be written to mass storage, and the size information for 1278 the file to be recorded in the storage directory if changed. If the 1279 operation is successful, ior is zero. Otherwise, it is an 1280 implementation-defined I/O result code. 1281 1282 1283 <P> 1284 1285 <hr> 1286 <A name=11.6.2.2125> 1287 <code> 1288 11.6.2.2125 <b>REFILL</b> 1289 </code> 1290 </a> 1291 <BR> 1292 FILE EXT 1293 <BR> 1294 <pre> 1295 ( -- flag ) 1296 </pre> 1297 <P> 1298 1299 Extend the execution semantics of 1300 <A href=dpans6.htm#6.2.2125>6.2.2125</a> REFILL with the 1301 following: 1302 1303 <P> 1304 1305 When the input source is a text file, attempt to read the next line from 1306 the text-input file. If successful, make the result the current input 1307 buffer, set 1308 <A href=dpans6.htm#6.1.0560>>IN</a> 1309 to zero, and return true. Otherwise return false. 1310 <P> 1311 1312 <code> 1313 See: 1314 <A href=dpans7.htm#7.6.2.2125>7.6.2.2125 REFILL</a> 1315 </code> 1316 <P> 1317 1318 <hr> 1319 <A name=11.6.2.2130> 1320 <code> 1321 11.6.2.2130 <b>RENAME-FILE</b> 1322 </code> 1323 </a> 1324 <BR> 1325 FILE EXT 1326 <BR> 1327 <pre> 1328 ( c-addr1 u1 c-addr2 u2 -- ior ) 1329 </pre> 1330 <P> 1331 1332 Rename the file named by the character string c-addr1 u1 to the name in 1333 the character string c-addr2 u2. ior is the implementation-defined I/O 1334 result code. 1335 1336 1337 <hr> 1338 <A href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents 1339 <BR> 1340 <A href=dpans12.htm><IMG src="right.gif" ></A> 1341 Next Section 1342 <P> 1343 </BODY> 1344 </HTML> 1345