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