vms/ext/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.2';
  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 &tmpnam
  86                      &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
 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 =over 4
 244
 245 =head2 File characteristic options
 246
 247 =over 2
 248
 249 =item alq=INTEGER
 250
 251 Sets the allocation quantity for this file
 252
 253 =item bls=INTEGER
 254
 255 File blocksize
 256
 257 =item ctx=STRING
 258
 259 Sets the context for the file. Takes one of these arguments:
 260
 261 =over 4
 262
 263 =item bin
 264
 265 Disables LF to CRLF translation
 266
 267 =item cvt
 268
 269 Negates previous setting of C<ctx=noctx>
 270
 271 =item nocvt
 272
 273 Disables conversion of FORTRAN carriage control
 274
 275 =item rec
 276
 277 Force record-mode access
 278
 279 =item stm
 280
 281 Force stream mode
 282
 283 =item xplct
 284
 285 Causes records to be flushed I<only> when the file is closed, or when an
 286 explicit flush is done
 287
 288 =back
 289
 290 =item deq=INTEGER
 291
 292 Sets the default extension quantity
 293
 294 =item dna=FILESPEC
 295
 296 Sets the default filename string. Used to fill in any missing pieces of the
 297 filename passed.
 298
 299 =item fop=STRING
 300
 301 File processing option. Takes one or more of the following (in a
 302 comma-separated list if there's more than one)
 303
 304 =over 4
 305
 306 =item ctg
 307
 308 Contiguous.
 309
 310 =item cbt
 311
 312 Contiguous-best-try.
 313
 314 =item dfw
 315
 316 Deferred write; only applicable to files opened for shared access.
 317
 318 =item dlt
 319
 320 Delete file on close.
 321
 322 =item tef
 323
 324 Truncate at end-of-file.
 325
 326 =item cif
 327
 328 Create if nonexistent.
 329
 330 =item sup
 331
 332 Supersede.
 333
 334 =item scf
 335
 336 Submit as command file on close.
 337
 338 =item spl
 339
 340 Spool to system printer on close.
 341
 342 =item tmd
 343
 344 Temporary delete.
 345
 346 =item tmp
 347
 348 Temporary (no file directory).
 349
 350 =item nef
 351
 352 Not end-of-file.
 353
 354 =item rck
 355
 356 Read check compare operation.
 357
 358 =item wck
 359
 360 Write check compare operation.
 361
 362 =item mxv
 363
 364 Maximize version number.
 365
 366 =item rwo
 367
 368 Rewind file on open.
 369
 370 =item pos
 371
 372 Current position.
 373
 374 =item rwc
 375
 376 Rewind file on close.
 377
 378 =item sqo
 379
 380 File can only be processed in a sequential manner.
 381
 382 =back
 383
 384 =item fsz=INTEGER
 385
 386 Fixed header size
 387
 388 =item gbc=INTEGER
 389
 390 Global buffers requested for the file
 391
 392 =item mbc=INTEGER
 393
 394 Multiblock count
 395
 396 =item mbf=INTEGER
 397
 398 Bultibuffer count
 399
 400 =item mrs=INTEGER
 401
 402 Maximum record size
 403
 404 =item rat=STRING
 405
 406 File record attributes. Takes one of the following:
 407
 408 =over 4
 409
 410 =item cr
 411
 412 Carriage-return control.
 413
 414 =item blk
 415
 416 Disallow records to span block boundaries.
 417
 418 =item ftn
 419
 420 FORTRAN print control.
 421
 422 =item none
 423
 424 Explicitly forces no carriage control.
 425
 426 =item prn
 427
 428 Print file format.
 429
 430 =back
 431
 432 =item rfm=STRING
 433
 434 File record format. Takes one of the following:
 435
 436 =over 4
 437
 438 =item fix
 439
 440 Fixed-length record format.
 441
 442 =item stm
 443
 444 RMS stream record format.
 445
 446 =item stmlf
 447
 448 Stream format with line-feed terminator.
 449
 450 =item stmcr
 451
 452 Stream format with carriage-return terminator.
 453
 454 =item var
 455
 456 Variable-length record format.
 457
 458 =item vfc
 459
 460 Variable-length record with fixed control.
 461
 462 =item udf
 463
 464 Undefined format
 465
 466 =back
 467
 468 =item rop=STRING
 469
 470 Record processing operations. Takes one or more of the following in a
 471 comma-separated list:
 472
 473 =over 4
 474
 475 =item asy
 476
 477 Asynchronous I/O.
 478
 479 =item cco
 480
 481 Cancel Ctrl/O (used with Terminal I/O).
 482
 483 =item cvt
 484
 485 Capitalizes characters on a read from the terminal.
 486
 487 =item eof
 488
 489 Positions the record stream to the end-of-file for the connect operation
 490 only.
 491
 492 =item nlk
 493
 494 Do not lock record.
 495
 496 =item pmt
 497
 498 Enables use of the prompt specified by pmt=usr-prmpt on input from the
 499 terminal.
 500
 501 =item pta
 502
 503 Eliminates any information in the type-ahead buffer on a read from the
 504 terminal.
 505
 506 =item rea
 507
 508 Locks record for a read operation for this process, while allowing other
 509 accessors to read the record.
 510
 511 =item rlk
 512
 513 Locks record for write.
 514
 515 =item rne
 516
 517 Suppresses echoing of input data on the screen as it is entered on the
 518 keyboard.
 519
 520 =item rnf
 521
 522 Indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control
 523 commands on terminal input, but are to be passed to the application
 524 program.
 525
 526 =item rrl
 527
 528 Reads regardless of lock.
 529
 530 =item syncsts
 531
 532 Returns success status of RMS$_SYNCH if the requested service completes its
 533 task immediately.
 534
 535 =item tmo
 536
 537 Timeout I/O.
 538
 539 =item tpt
 540
 541 Allows put/write services using sequential record access mode to occur at
 542 any point in the file, truncating the file at that point.
 543
 544 =item ulk
 545
 546 Prohibits RMS from automatically unlocking records.
 547
 548 =item wat
 549
 550 Wait until record is available, if currently locked by another stream.
 551
 552 =item rah
 553
 554 Read ahead.
 555
 556 =item wbh
 557
 558 Write behind.
 559
 560 =back
 561
 562 =item rtv=INTEGER
 563
 564 The number of retrieval pointers that RMS has to maintain (0 to 127255)
 565
 566 =item shr=STRING
 567
 568 File sharing options. Choose one of the following:
 569
 570 =over 4
 571
 572 =item del
 573
 574 Allows users to delete.
 575
 576 =item get
 577
 578 Allows users to read.
 579
 580 =item mse
 581
 582 Allows mainstream access.
 583
 584 =item nil
 585
 586 Prohibits file sharing.
 587
 588 =item put
 589
 590 Allows users to write.
 591
 592 =item upd
 593
 594 Allows users to update.
 595
 596 =item upi
 597
 598 Allows one or more writers.
 599
 600 =back
 601
 602 =item tmo=INTEGER
 603
 604 I/O timeout value
 605
 606 =back
 607
 608 =back
 609
 610 =item vmssysopen
 611
 612 This function bears the same relationship to the CORE function
 613 C<sysopen> as C<vmsopen> does to C<open>.  Its first three arguments
 614 are the name, access flags, and permissions for the file.  Like
 615 C<vmsopen>, it takes up to 8 additional string arguments which
 616 specify file characteristics.  Its return value is identical to
 617 that of C<vmsopen>.
 618
 619 The symbolic constants for the mode argument are exported by
 620 VMS::Stdio by default, and are also exported by the Fcntl package.
 621
 622 =item waitfh
 623
 624 This function causes Perl to wait for the completion of an I/O
 625 operation on the file handle specified as its argument.  It is
 626 used with handles opened for asynchronous I/O, and performs its
 627 task by calling the CRTL routine fwait().
 628
 629 =item writeof
 630
 631 This function writes an EOF to a file handle, if the device driver
 632 supports this operation.  Its primary use is to send an EOF to a
 633 subprocess through a pipe opened for writing without closing the
 634 pipe.  It returns a true value if successful, and C<undef> if
 635 it encounters an error.
 636
 637 =head1 REVISION
 638
 639 This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and
 640 5.6.0.
 641
 642 =cut