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