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