ext/VMS-Stdio/Stdio.pm

   1 #   VMS::Stdio - VMS extensions to Perl's stdio calls
   2 #
   3 #   Author:  Charles Bailey  bailey@genetics.upenn.edu
   4 #   Version: 2.2
   5 #   Revised: 19-Jul-1998
   6 #   Docs revised: 13-Oct-1998 Dan Sugalski <sugalskd@ous.edu>
   7
   8 package VMS::Stdio;
   9
  10 require 5.002;
  11 use Carp '&croak';
  12 use DynaLoader ();
  13 use Exporter ();
  14
  15 our $VERSION = '2.44';
  16 our @ISA = qw( Exporter DynaLoader IO::File );
  17 our @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY &O_NOWAIT
  18               &O_RDONLY &O_RDWR  &O_TRUNC &O_WRONLY );
  19 our @EXPORT_OK = qw( &binmode &flush &getname &remove &rewind &sync &setdef &tmpnam
  20                  &vmsopen &vmssysopen &waitfh &writeof );
  21 our %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY
  22                                     &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC
  23                                     &O_WRONLY ) ],
  24                  FUNCTIONS => [ qw( &binmode &flush &getname &remove &rewind
  25                                     &setdef &sync &tmpnam &vmsopen &vmssysopen
  26                                     &waitfh &writeof ) ] );
  27
  28 bootstrap VMS::Stdio $VERSION;
  29
  30 sub AUTOLOAD {
  31     my($constname) = $AUTOLOAD;
  32     $constname =~ s/.*:://;
  33     if ($constname =~ /^O_/) {
  34       my($val) = constant($constname);
  35       defined $val or croak("Unknown VMS::Stdio constant $constname");
  36       *$AUTOLOAD = sub { $val; }
  37     }
  38     else { # We don't know about it; hand off to IO::File
  39       require IO::File;
  40
  41       *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }";
  42       croak "Error autoloading IO::File::$constname: $@" if $@;
  43     }
  44     goto &$AUTOLOAD;
  45 }
  46
  47 sub DESTROY { close($_[0]); }
  48
  49
  50 1;
  51
  52 __END__
  53
  54 =head1 NAME
  55
  56 VMS::Stdio - standard I/O functions via VMS extensions
  57
  58 =head1 SYNOPSIS
  59
  60   use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync
  61                      &tmpnam &vmsopen &vmssysopen &waitfh &writeof );
  62   setdef("new:[default.dir]");
  63   $uniquename = tmpnam;
  64   $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;
  65   $name = getname($fh);
  66   print $fh "Hello, world!\n";
  67   flush($fh);
  68   sync($fh);
  69   rewind($fh);
  70   $line = <$fh>;
  71   undef $fh;  # closes file
  72   $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");
  73   sysread($fh,$data,128);
  74   waitfh($fh);
  75   close($fh);
  76   remove("another.file");
  77   writeof($pipefh);
  78   binmode($fh);
  79
  80 =head1 DESCRIPTION
  81
  82 This package gives Perl scripts access via VMS extensions to several
  83 C stdio operations not available through Perl's CORE I/O functions.
  84 The specific routines are described below.  These functions are
  85 prototyped as unary operators, with the exception of C<vmsopen>
  86 and C<vmssysopen>, which can take any number of arguments, and
  87 C<tmpnam>, which takes none.
  88
  89 All of the routines are available for export, though none are
  90 exported by default.  All of the constants used by C<vmssysopen>
  91 to specify access modes are exported by default.  The routines
  92 are associated with the Exporter tag FUNCTIONS, and the constants
  93 are associated with the Exporter tag CONSTANTS, so you can more
  94 easily choose what you'd like to import:
  95
  96     # import constants, but not functions
  97     use VMS::Stdio;  # same as use VMS::Stdio qw( :DEFAULT );
  98     # import functions, but not constants
  99     use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS );
 100     # import both
 101     use VMS::Stdio qw( :CONSTANTS :FUNCTIONS );
 102     # import neither
 103     use VMS::Stdio ();
 104
 105 Of course, you can also choose to import specific functions by
 106 name, as usual.
 107
 108 This package C<ISA> IO::File, so that you can call IO::File
 109 methods on the handles returned by C<vmsopen> and C<vmssysopen>.
 110 The IO::File package is not initialized, however, until you
 111 actually call a method that VMS::Stdio doesn't provide.  This
 112 is done to save startup time for users who don't wish to use
 113 the IO::File methods.
 114
 115 B<Note:>  In order to conform to naming conventions for Perl
 116 extensions and functions, the name of this package was
 117 changed to from VMS::stdio to VMS::Stdio as of Perl 5.002, and the names of some
 118 routines were changed.  For many releases, calls to the old VMS::stdio routines
 119 would generate a warning, and then route to the equivalent
 120 VMS::Stdio function.  This compatibility interface has now been removed.
 121
 122 =over 4
 123
 124 =item binmode
 125
 126 This function causes the file handle to be reopened with the CRTL's
 127 carriage control processing disabled; its effect is the same as that
 128 of the C<b> access mode in C<vmsopen>.  After the file is reopened,
 129 the file pointer is positioned as close to its position before the
 130 call as possible (I<i.e.> as close as fsetpos() can get it -- for
 131 some record-structured files, it's not possible to return to the
 132 exact byte offset in the file).  Because the file must be reopened,
 133 this function cannot be used on temporary-delete files. C<binmode>
 134 returns true if successful, and C<undef> if not.
 135
 136 Note that the effect of C<binmode> differs from that of the binmode()
 137 function on operating systems such as Windows and MSDOS, and is not
 138 needed to process most types of file.
 139
 140 =item flush
 141
 142 This function causes the contents of stdio buffers for the specified
 143 file handle to be flushed.  If C<undef> is used as the argument to
 144 C<flush>, all currently open file handles are flushed.  Like the CRTL
 145 fflush() routine, it does not flush any underlying RMS buffers for the
 146 file, so the data may not be flushed all the way to the disk.  C<flush>
 147 returns a true value if successful, and C<undef> if not.
 148
 149 =item getname
 150
 151 The C<getname> function returns the file specification associated
 152 with a Perl I/O handle.  If an error occurs, it returns C<undef>.
 153
 154 =item remove
 155
 156 This function deletes the file named in its argument, returning
 157 a true value if successful and C<undef> if not.  It differs from
 158 the CORE Perl function C<unlink> in that it does not try to
 159 reset file protection if the original protection does not give
 160 you delete access to the file (cf. L<perlvms>).  In other words,
 161 C<remove> is equivalent to
 162
 163   unlink($file) if VMS::Filespec::candelete($file);
 164
 165 =item rewind
 166
 167 C<rewind> resets the current position of the specified file handle
 168 to the beginning of the file.  It's really just a convenience
 169 method equivalent in effect to C<seek($fh,0,0)>.  It returns a
 170 true value if successful, and C<undef> if it fails.
 171
 172 =item setdef
 173
 174 This function sets the default device and directory for the process.
 175 It is identical to the built-in chdir() operator, except that the change
 176 persists after Perl exits.  It returns a true value on success, and
 177 C<undef> if it encounters an error.
 178
 179 =item sync
 180
 181 This function flushes buffered data for the specified file handle
 182 from stdio and RMS buffers all the way to disk.  If successful, it
 183 returns a true value; otherwise, it returns C<undef>.
 184
 185 =item tmpnam
 186
 187 The C<tmpnam> function returns a unique string which can be used
 188 as a filename when creating temporary files.  If, for some
 189 reason, it is unable to generate a name, it returns C<undef>.
 190
 191 =item vmsopen
 192
 193 The C<vmsopen> function enables you to specify optional RMS arguments
 194 to the VMS CRTL when opening a file.  Its operation is similar to the built-in
 195 Perl C<open> function (see L<perlfunc> for a complete description),
 196 but it will only open normal files; it cannot open pipes or duplicate
 197 existing I/O handles.  Up to 8 optional arguments may follow the
 198 file name.  These arguments should be strings which specify
 199 optional file characteristics as allowed by the CRTL. (See the
 200 CRTL reference manual description of creat() and fopen() for details.)
 201 If successful, C<vmsopen> returns a VMS::Stdio file handle; if an
 202 error occurs, it returns C<undef>.
 203
 204 You can use the file handle returned by C<vmsopen> just as you
 205 would any other Perl file handle.  The class VMS::Stdio ISA
 206 IO::File, so you can call IO::File methods using the handle
 207 returned by C<vmsopen>.  However, C<use>ing VMS::Stdio does not
 208 automatically C<use> IO::File; you must do so explicitly in
 209 your program if you want to call IO::File methods.  This is
 210 done to avoid the overhead of initializing the IO::File package
 211 in programs which intend to use the handle returned by C<vmsopen>
 212 as a normal Perl file handle only.  When the scalar containing
 213 a VMS::Stdio file handle is overwritten, C<undef>d, or goes
 214 out of scope, the associated file is closed automatically.
 215
 216 File characteristic options:
 217
 218 =over 2
 219
 220 =item alq=INTEGER
 221
 222 Sets the allocation quantity for this file
 223
 224 =item bls=INTEGER
 225
 226 File blocksize
 227
 228 =item ctx=STRING
 229
 230 Sets the context for the file. Takes one of these arguments:
 231
 232 =over 4
 233
 234 =item bin
 235
 236 Disables LF to CRLF translation
 237
 238 =item cvt
 239
 240 Negates previous setting of C<ctx=noctx>
 241
 242 =item nocvt
 243
 244 Disables conversion of FORTRAN carriage control
 245
 246 =item rec
 247
 248 Force record-mode access
 249
 250 =item stm
 251
 252 Force stream mode
 253
 254 =item xplct
 255
 256 Causes records to be flushed I<only> when the file is closed, or when an
 257 explicit flush is done
 258
 259 =back
 260
 261 =item deq=INTEGER
 262
 263 Sets the default extension quantity
 264
 265 =item dna=FILESPEC
 266
 267 Sets the default filename string. Used to fill in any missing pieces of the
 268 filename passed.
 269
 270 =item fop=STRING
 271
 272 File processing option. Takes one or more of the following (in a
 273 comma-separated list if there's more than one)
 274
 275 =over 4
 276
 277 =item ctg
 278
 279 Contiguous.
 280
 281 =item cbt
 282
 283 Contiguous-best-try.
 284
 285 =item dfw
 286
 287 Deferred write; only applicable to files opened for shared access.
 288
 289 =item dlt
 290
 291 Delete file on close.
 292
 293 =item tef
 294
 295 Truncate at end-of-file.
 296
 297 =item cif
 298
 299 Create if nonexistent.
 300
 301 =item sup
 302
 303 Supersede.
 304
 305 =item scf
 306
 307 Submit as command file on close.
 308
 309 =item spl
 310
 311 Spool to system printer on close.
 312
 313 =item tmd
 314
 315 Temporary delete.
 316
 317 =item tmp
 318
 319 Temporary (no file directory).
 320
 321 =item nef
 322
 323 Not end-of-file.
 324
 325 =item rck
 326
 327 Read check compare operation.
 328
 329 =item wck
 330
 331 Write check compare operation.
 332
 333 =item mxv
 334
 335 Maximize version number.
 336
 337 =item rwo
 338
 339 Rewind file on open.
 340
 341 =item pos
 342
 343 Current position.
 344
 345 =item rwc
 346
 347 Rewind file on close.
 348
 349 =item sqo
 350
 351 File can only be processed in a sequential manner.
 352
 353 =back
 354
 355 =item fsz=INTEGER
 356
 357 Fixed header size
 358
 359 =item gbc=INTEGER
 360
 361 Global buffers requested for the file
 362
 363 =item mbc=INTEGER
 364
 365 Multiblock count
 366
 367 =item mbf=INTEGER
 368
 369 Bultibuffer count
 370
 371 =item mrs=INTEGER
 372
 373 Maximum record size
 374
 375 =item rat=STRING
 376
 377 File record attributes. Takes one of the following:
 378
 379 =over 4
 380
 381 =item cr
 382
 383 Carriage-return control.
 384
 385 =item blk
 386
 387 Disallow records to span block boundaries.
 388
 389 =item ftn
 390
 391 FORTRAN print control.
 392
 393 =item none
 394
 395 Explicitly forces no carriage control.
 396
 397 =item prn
 398
 399 Print file format.
 400
 401 =back
 402
 403 =item rfm=STRING
 404
 405 File record format. Takes one of the following:
 406
 407 =over 4
 408
 409 =item fix
 410
 411 Fixed-length record format.
 412
 413 =item stm
 414
 415 RMS stream record format.
 416
 417 =item stmlf
 418
 419 Stream format with line-feed terminator.
 420
 421 =item stmcr
 422
 423 Stream format with carriage-return terminator.
 424
 425 =item var
 426
 427 Variable-length record format.
 428
 429 =item vfc
 430
 431 Variable-length record with fixed control.
 432
 433 =item udf
 434
 435 Undefined format
 436
 437 =back
 438
 439 =item rop=STRING
 440
 441 Record processing operations. Takes one or more of the following in a
 442 comma-separated list:
 443
 444 =over 4
 445
 446 =item asy
 447
 448 Asynchronous I/O.
 449
 450 =item cco
 451
 452 Cancel Ctrl/O (used with Terminal I/O).
 453
 454 =item cvt
 455
 456 Capitalizes characters on a read from the terminal.
 457
 458 =item eof
 459
 460 Positions the record stream to the end-of-file for the connect operation
 461 only.
 462
 463 =item nlk
 464
 465 Do not lock record.
 466
 467 =item pmt
 468
 469 Enables use of the prompt specified by pmt=usr-prmpt on input from the
 470 terminal.
 471
 472 =item pta
 473
 474 Eliminates any information in the type-ahead buffer on a read from the
 475 terminal.
 476
 477 =item rea
 478
 479 Locks record for a read operation for this process, while allowing other
 480 accessors to read the record.
 481
 482 =item rlk
 483
 484 Locks record for write.
 485
 486 =item rne
 487
 488 Suppresses echoing of input data on the screen as it is entered on the
 489 keyboard.
 490
 491 =item rnf
 492
 493 Indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control
 494 commands on terminal input, but are to be passed to the application
 495 program.
 496
 497 =item rrl
 498
 499 Reads regardless of lock.
 500
 501 =item syncsts
 502
 503 Returns success status of RMS$_SYNCH if the requested service completes its
 504 task immediately.
 505
 506 =item tmo
 507
 508 Timeout I/O.
 509
 510 =item tpt
 511
 512 Allows put/write services using sequential record access mode to occur at
 513 any point in the file, truncating the file at that point.
 514
 515 =item ulk
 516
 517 Prohibits RMS from automatically unlocking records.
 518
 519 =item wat
 520
 521 Wait until record is available, if currently locked by another stream.
 522
 523 =item rah
 524
 525 Read ahead.
 526
 527 =item wbh
 528
 529 Write behind.
 530
 531 =back
 532
 533 =item rtv=INTEGER
 534
 535 The number of retrieval pointers that RMS has to maintain (0 to 127255)
 536
 537 =item shr=STRING
 538
 539 File sharing options. Choose one of the following:
 540
 541 =over 4
 542
 543 =item del
 544
 545 Allows users to delete.
 546
 547 =item get
 548
 549 Allows users to read.
 550
 551 =item mse
 552
 553 Allows mainstream access.
 554
 555 =item nil
 556
 557 Prohibits file sharing.
 558
 559 =item put
 560
 561 Allows users to write.
 562
 563 =item upd
 564
 565 Allows users to update.
 566
 567 =item upi
 568
 569 Allows one or more writers.
 570
 571 =back
 572
 573 =item tmo=INTEGER
 574
 575 I/O timeout value
 576
 577 =back
 578
 579 =item vmssysopen
 580
 581 This function bears the same relationship to the CORE function
 582 C<sysopen> as C<vmsopen> does to C<open>.  Its first three arguments
 583 are the name, access flags, and permissions for the file.  Like
 584 C<vmsopen>, it takes up to 8 additional string arguments which
 585 specify file characteristics.  Its return value is identical to
 586 that of C<vmsopen>.
 587
 588 The symbolic constants for the mode argument are exported by
 589 VMS::Stdio by default, and are also exported by the Fcntl package.
 590
 591 =item waitfh
 592
 593 This function causes Perl to wait for the completion of an I/O
 594 operation on the file handle specified as its argument.  It is
 595 used with handles opened for asynchronous I/O, and performs its
 596 task by calling the CRTL routine fwait().
 597
 598 =item writeof
 599
 600 This function writes an EOF to a file handle, if the device driver
 601 supports this operation.  Its primary use is to send an EOF to a
 602 subprocess through a pipe opened for writing without closing the
 603 pipe.  It returns a true value if successful, and C<undef> if
 604 it encounters an error.
 605
 606 =back
 607
 608 =head1 REVISION
 609
 610 This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and
 611 5.6.0.
 612
 613 =cut