share/doc/papers/px/pxin3.n

   1 .\" Copyright (c) 1979 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)pxin3.n     5.2 (Berkeley) 4/17/91
  33 .\" $FreeBSD: src/share/doc/papers/px/pxin3.n,v 1.1.1.1.14.1 2000/11/30 17:13:59 ru Exp $
  34 .\" $DragonFly: src/share/doc/papers/px/pxin3.n,v 1.2 2003/06/17 04:36:56 dillon Exp $
  35 .\"
  36 .ta 8n 16n 24n
  37 .nr H1 2
  38 .if n .ND
  39 .NH
  40 Input/output
  41 .NH 2
  42 The files structure
  43 .PP
  44 Each file in the Pascal environment is represented by a pointer
  45 to a
  46 .I files
  47 structure in the heap.
  48 At the location addressed by the pointer is the element
  49 in the file's window variable.
  50 Behind this window variable is information about the file,
  51 at the following offsets:
  52 .so table3.1.n
  53 .PP
  54 Here
  55 .SM FBUF
  56 is a pointer to the system FILE block for the file.
  57 The standard system I/O library is
  58 used that provides block buffered input/output,
  59 with 1024 characters normally transferred at each read or write.
  60 .PP
  61 The files in the
  62 Pascal environment,
  63 are all linked together on a single file chain through the
  64 .SM FCHAIN
  65 links.
  66 For each file the
  67 .SM FLEV
  68 pointer gives its associated file variable.
  69 These are used to free files at block exit as described in section 3.3
  70 below.
  71 .PP
  72 The
  73 FNAME
  74 and
  75 PFNAME
  76 give the associated
  77 file name for the file and the name to be used when printing
  78 error diagnostics respectively.
  79 Although these names are usually the same,
  80 .I input
  81 and
  82 .I output
  83 usually have no associated
  84 file name so the distinction is necessary.
  85 .PP
  86 The
  87 FUNIT
  88 word contains
  89 a set of flags.
  90 whose representations are:
  91 .TS
  92 center;
  93 l l l.
  94 EOF     0x0100  At end-of-file
  95 EOLN    0x0200  At end-of-line (text files only)
  96 SYNC    0x0400  File window is out of sync
  97 TEMP    0x0800  File is temporary
  98 FREAD   0x1000  File is open for reading
  99 FWRITE  0x2000  File is open for writing
 100 FTEXT   0x4000  File is a text file; process EOLN
 101 FDEF    0x8000  File structure created, but file not opened
 102 .TE
 103 .PP
 104 The
 105 EOF
 106 and
 107 EOLN
 108 bits here reflect the associated built-in function values.
 109 TEMP
 110 specifies that the file has a generated temporary name and that
 111 it should therefore be removed when its block exits.
 112 FREAD
 113 and
 114 FWRITE
 115 specify that
 116 .I reset
 117 and
 118 .I rewrite
 119 respectively have been done on the file so that
 120 input or output operations can be done.
 121 FTEXT
 122 specifies the file is a text file so that
 123 EOLN
 124 processing should be done,
 125 with newline characters turned into blanks, etc.
 126 .PP
 127 The
 128 SYNC
 129 bit,
 130 when true,
 131 specifies that there is no usable image in the file buffer window.
 132 As discussed in the
 133 .I "Berkeley Pascal User's Manual,"
 134 the interactive environment necessitates having
 135 ``input^'' undefined at the beginning
 136 of execution so that a program may print a prompt
 137 before the user is required to type input.
 138 The
 139 SYNC
 140 bit implements this.
 141 When it is set,
 142 it specifies that the element in the window
 143 must be updated before it can be used.
 144 This is never done until necessary.
 145 .NH 2
 146 Initialization of files
 147 .PP
 148 All the variables in the Pascal runtime environment are cleared to zero on
 149 block entry.
 150 This is necessary for simple processing of files.
 151 If a file is unused, its pointer will be
 152 .B nil.
 153 All references to an inactive file are thus references through a
 154 .B nil
 155 pointer.
 156 If the Pascal system did not clear storage to zero before execution
 157 it would not be possible to detect inactive files in this simple way;
 158 it would probably be necessary to generate (possibly complicated)
 159 code to initialize
 160 each file on block entry.
 161 .PP
 162 When a file is first mentioned in a
 163 .I reset
 164 or
 165 .I rewrite
 166 call,
 167 a buffer of the form described above is associated with it,
 168 and the necessary information about the file is placed in this
 169 buffer.
 170 The file is also linked into the active file chain.
 171 This chain is kept sorted by block mark address, the
 172 FLEV
 173 entries.
 174 .NH 2
 175 Block exit
 176 .PP
 177 When block exit occurs the interpreter must free the files that are in
 178 use in the block
 179 and their associated buffers.
 180 This is simple and efficient because the files in the active file chain are
 181 sorted by increasing block mark address.
 182 This means that the files for the current block will be at the front
 183 of the chain.
 184 For each file that is no longer accessible
 185 the interpreter first flushes the files buffer
 186 if it is an output file.
 187 The interpreter then returns the file buffer and the files structure and window
 188 to the free space in the heap and removes the file from the active file chain.
 189 .NH 2
 190 Flushing
 191 .PP
 192 Flushing all the file buffers at abnormal termination,
 193 or on a call to the procedure
 194 .I flush
 195 or
 196 .I message
 197 is done by flushing
 198 each file on the file chain that has the
 199 FWRITE
 200 bit set in its flags word.
 201 .NH 2
 202 The active file
 203 .PP
 204 For input-output,
 205 .I px
 206 maintains a notion of an active file.
 207 Each operation that references a file makes the file
 208 it will be using the active file and then does its operation.
 209 A subtle point here is that one may do a procedure call to
 210 .I write
 211 that involves a call to a function that references another file,
 212 thereby destroying the active file set up before the
 213 .I write.
 214 Thus the active file is saved at block entry
 215 in the block mark and restored at block exit.\*(Dg
 216 .FS
 217 \*(dg\ It would probably be better to dispense with the notion of
 218 active file and use another mechanism that did not involve extra
 219 overhead on each procedure and function call.
 220 .FE
 221 .NH 2
 222 File operations
 223 .PP
 224 Files in Pascal can be used in two distinct ways:
 225 as the object of
 226 .I read,
 227 .I write,
 228 .I get,
 229 and
 230 .I put
 231 calls, or indirectly as though they were pointers.
 232 The second use as pointers must be careful
 233 not to destroy the active file in a reference such as
 234 .LS
 235 write(output, input\(ua)
 236 .LE
 237 or the system would incorrectly write on the input device.
 238 .PP
 239 The fundamental operator related to the use of a file is
 240 .SM FNIL.
 241 This takes the file variable, as a pointer,
 242 insures that the pointer is not
 243 .B nil,
 244 and also that a usable image is in the file window,
 245 by forcing the
 246 .SM SYNC
 247 bit to be cleared.
 248 .PP
 249 A simple example that demonstrates the use of the file operators
 250 is given by
 251 .LS
 252 writeln(f)
 253 .LE
 254 that produces
 255 .DS
 256 .mD
 257 .TS
 258 lp-2w(8) l.
 259 RV:\fIl f\fP
 260 UNIT
 261 WRITLN
 262 .TE
 263 .DE
 264 .NH 2
 265 Read operations
 266 .SH
 267 GET
 268 .IP
 269 Advance the active file to the next input element.
 270 .SH
 271 FNIL
 272 .IP
 273 A file pointer is on the stack. Insure that the associated file is active
 274 and that the file is synced so that there is input available in the window.
 275 .SH
 276 READ*
 277 .IP
 278 If the file is a text file, read a block of text
 279 and convert it to the internal type of the specified
 280 operand. If the file is not a text file then
 281 do an unformatted read of the next record.
 282 The procedure
 283 .SM READLN
 284 reads upto and including the next end of line character.
 285 .SH
 286 READE A
 287 .IP
 288 The operator
 289 .SM READE
 290 reads a string name of an enumerated type and converts it
 291 to its internal value.
 292 .SM READE
 293 takes a pointer to a data structure as shown in figure 3.2.
 294 .so fig3.2.n
 295 See the description of
 296 .SM NAM
 297 in the next section for an example.
 298 .NH 2
 299 Write operations
 300 .SH
 301 PUT
 302 .IP
 303 Output the element in the active file window.
 304 .SH
 305 WRITEF s
 306 .IP
 307 The argument(s) on the stack are output
 308 by the
 309 .I fprintf
 310 standard
 311 .SM I/O
 312 library routine.
 313 The sub-opcode
 314 .I s
 315 specifies the number
 316 of longword arguments on the stack.
 317 .SH
 318 WRITEC
 319 .IP
 320 The character on the top of the stack is output
 321 without formatting. Formatted characters must be output with
 322 .SM WRITEF .
 323 .SH
 324 WRITES
 325 .IP
 326 The string specified by the pointer on the top of the stack is output
 327 by the
 328 .I fwrite
 329 standard
 330 .SM I/O
 331 library routine.
 332 All characters including nulls are printed.
 333 .SH
 334 WRITLN
 335 .IP
 336 A linefeed is output to the active file.
 337 The line-count for the file is
 338 incremented and checked against the line limit.
 339 .SH
 340 PAGE
 341 .IP
 342 A formfeed is output to the active file.
 343 .SH
 344 NAM A
 345 .IP
 346 The value on the top of the stack is converted to a pointer
 347 to an enumerated type string name.
 348 The address
 349 .SM A
 350 points to an enumerated type structure identical
 351 to that used by
 352 .SM READE .
 353 An error is raised if the value is out of range.
 354 The form of this structure for the predefined type
 355 .B boolean
 356 is shown in figure 3.3.
 357 .so fig3.3.n
 358 The code for
 359 .SM NAM
 360 is
 361 .DS
 362 .mD
 363 _NAM:
 364         \fBincl\fR      lc
 365         \fBaddl3\fR     (lc)+,ap,r6     #r6 points to scalar name list
 366         \fBmovl\fR      (sp)+,r3        #r3 has data value
 367         \fBcmpw\fR      r3,(r6)+        #check value out of bounds
 368         \fBbgequ\fR     enamrng
 369         \fBmovzwl\fR    (r6)[r3],r4     #r4 has string index
 370         \fBpushab\fR    (r6)[r4]        #push string pointer
 371         \fBjmp\fR       (loop)
 372 enamrng:
 373         \fBmovw\fR      $ENAMRNG,_perrno
 374         \fBjbr\fR       error
 375 .DE
 376 The address of the table is calculated by adding the base address
 377 of the interpreter code,
 378 .I ap
 379 to the offset pointed to by
 380 .I lc .
 381 The first word of the table gives the number of records and
 382 provides a range check of the data to be output.
 383 The pointer is then calculated as
 384 .DS
 385 .mD
 386 tblbase = ap + A;
 387 size = *tblbase++;
 388 return(tblbase + tblbase[value]);
 389 .DE
 390 .SH
 391 MAX s,w
 392 .IP
 393 The sub-opcode
 394 .I s
 395 is subtracted from the integer on the top of the stack.
 396 The maximum of the result and the second argument,
 397 .I w ,
 398 replaces the value on the top of the stack.
 399 This function verifies that variable specified
 400 width arguments are non-negative, and meet certain minimum width
 401 requirements.
 402 .SH
 403 MIN s
 404 .IP
 405 The minimum of the value on the top of the stack
 406 and the sub-opcode replaces the value on the top
 407 of the stack.
 408 .sp 1
 409 .LP
 410 The uses of files and the file operations are summarized
 411 in an example which outputs a real variable (r) with a variable
 412 width field (i).
 413 .LS
 414 writeln('r =',r:i,' ',true);
 415 .LE
 416 that generates the code
 417 .DS
 418 .mD
 419 .TS
 420 lp-2w(8) l.
 421 UNITOUT
 422 FILE
 423 CON14:1
 424 CON14:3
 425 LVCON:4 "r ="
 426 WRITES
 427 RV8\fI:l        r\fP
 428 RV4\fI:l        i\fP
 429 MAX:8   1
 430 RV4\fI:l        i\fP
 431 MAX:1   1
 432 LVCON:8 " %*.*E"
 433 FILE
 434 WRITEF:6
 435 CONC4   \' \'
 436 WRITEC
 437 CON14:1
 438 NAM     \fIbool\fP
 439 LVCON:4 "%s"
 440 FILE
 441 WRITEF:3
 442 WRITLN
 443 .TE
 444 .DE
 445 .PP
 446 Here the operator
 447 .SM UNITOUT
 448 is an abbreviated form of the operator
 449 .SM UNIT
 450 that is used when the file to be made active is
 451 .I output .
 452 A file descriptor, record count, string size, and a pointer
 453 to the constant string ``r ='' are pushed
 454 and then output by
 455 .SM WRITES .
 456 Next the value of
 457 .I r
 458 is pushed on the stack
 459 and the precision size is calculated by taking
 460 seven less than the width, but not less than one.
 461 This is followed by the width that is reduced by
 462 one to leave space for the required leading blank.
 463 If the width is too narrow, it
 464 is expanded by
 465 .I fprintf .
 466 A pointer to the format string is pushed followed
 467 by a file descriptor and the operator
 468 .SM WRITEF
 469 that prints out
 470 .I r .
 471 The value of six on
 472 .SM WRITEF
 473 comes from two longs for
 474 .I r
 475 and a long each for the precision, width, format string pointer,
 476 and file descriptor.
 477 The operator
 478 .SM CONC4
 479 pushes the
 480 .I blank
 481 character onto a long on the stack that is then printed out by
 482 .SM WRITEC .
 483 The internal representation for
 484 .I true
 485 is pushed as a long onto the stack and is
 486 then replaced by a pointer to the string ``true''
 487 by the operator
 488 .SM NAM
 489 using the table
 490 .I bool
 491 for conversion.
 492 This string is output by the operator
 493 .SM WRITEF
 494 using the format string ``%s''.
 495 Finally the operator
 496 .SM WRITLN
 497 appends a newline to the file.
 498 .NH 2
 499 File activation and status operations
 500 .SH
 501 UNIT*
 502 .IP
 503 The file pointed to by the file pointer on the top
 504 of the stack is converted to be the active file.
 505 The opcodes
 506 .SM UNITINP
 507 and
 508 .SM UNITOUT
 509 imply standard input and output respectively
 510 instead of explicitly pushing their file pointers.
 511 .SH
 512 FILE
 513 .IP
 514 The standard
 515 .SM I/O
 516 library file descriptor associated with the active file
 517 is pushed onto the stack.
 518 .SH
 519 EOF
 520 .IP
 521 The file pointed to by the file pointer on the top
 522 of the stack is checked for end of file. A boolean
 523 is returned with
 524 .I true
 525 indicating the end of file condition.
 526 .SH
 527 EOLN
 528 .IP
 529 The file pointed to by the file pointer on the top
 530 of the stack is checked for end of line. A boolean
 531 is returned with
 532 .I true
 533 indicating the end of line condition.
 534 Note that only text files can check for end of line.
 535 .NH 2
 536 File housekeeping operations
 537 .SH
 538 DEFNAME
 539 .IP
 540 Four data items are passed on the stack;
 541 the size of the data type associated with the file,
 542 the maximum size of the file name,
 543 a pointer to the file name,
 544 and a pointer to the file variable.
 545 A file record is created with the specified window size
 546 and the file variable set to point to it.
 547 The file is marked as defined but not opened.
 548 This allows
 549 .B program
 550 statement association of file names with file variables
 551 before their use by a
 552 .SM RESET
 553 or a
 554 .SM REWRITE .
 555 .SH
 556 BUFF s
 557 .IP
 558 The sub-opcode is placed in the external variable
 559 .I _bufopt
 560 to specify the amount of I/O buffering that is desired.
 561 The current options are:
 562 .DS
 563 0 \- character at a time buffering
 564 1 \- line at a time buffering
 565 2 \- block buffering
 566 .DE
 567 The default value is 1.
 568 .SH
 569 RESET
 570 .br
 571 REWRITE
 572 .IP
 573 Four data items are passed on the stack;
 574 the size of the data type associated with the file,
 575 the maximum size of the name (possibly zero),
 576 a pointer to the file name (possibly null),
 577 and a pointer to the file variable.
 578 If the file has never existed it is created as in
 579 .SM DEFNAME .
 580 If no file name is specified and no previous name exists
 581 (for example one created by
 582 .SM DEFNAME
 583 ) then a system temporary name is created.
 584 .SM RESET
 585 then opens the file for input, while
 586 .SM REWRITE
 587 opens the file for output.
 588 .sp 1
 589 .PP
 590 The three remaining file operations are
 591 .SM FLUSH
 592 that flushes the active file,
 593 .SM REMOVE
 594 that takes the pointer to a file name and removes the
 595 specified file, and
 596 .SM MESSAGE
 597 that flushes all the output files and sets the
 598 standard error file to be the active file.