share/doc/papers/px/pxin3.n

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