#   VMS::Stdio - VMS extensions to Perl's stdio calls##   Author:  Charles Bailey  bailey@genetics.upenn.edu#   Version: 2.2#   Revised: 19-Jul-1998#   Docs revised: 13-Oct-1998 Dan Sugalski <sugalskd@ous.edu>package VMS::Stdio;require 5.002;use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA );use Carp '&croak';use DynaLoader ();use Exporter (); $VERSION = '2.2';@ISA = qw( Exporter DynaLoader IO::File );@EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY &O_NOWAIT              &O_RDONLY &O_RDWR  &O_TRUNC &O_WRONLY );@EXPORT_OK = qw( &binmode &flush &getname &remove &rewind &sync &setdef &tmpnam                 &vmsopen &vmssysopen &waitfh &writeof );%EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY                                    &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC                                    &O_WRONLY ) ],                 FUNCTIONS => [ qw( &binmode &flush &getname &remove &rewind                                    &setdef &sync &tmpnam &vmsopen &vmssysopen                                    &waitfh &writeof ) ] );bootstrap VMS::Stdio $VERSION;sub AUTOLOAD {    my($constname) = $AUTOLOAD;    $constname =~ s/.*:://;    if ($constname =~ /^O_/) {      my($val) = constant($constname);      defined $val or croak("Unknown VMS::Stdio constant $constname");      *$AUTOLOAD = sub { $val; }    }    else { # We don't know about it; hand off to IO::File      require IO::File;      *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }";      croak "Error autoloading IO::File::$constname: $@" if $@;    }    goto &$AUTOLOAD;}sub DESTROY { close($_[0]); }################################################################################# Intercept calls to old VMS::stdio package, complain, and hand off# This will be removed in a future version of VMS::Stdiopackage VMS::stdio;sub AUTOLOAD {  my($func) = $AUTOLOAD;  $func =~ s/.*:://;  # Cheap trick: we know DynaLoader has required Carp.pm  Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code");  if ($func eq 'vmsfopen') {    Carp::carp("Old function &vmsfopen is now &vmsopen");    goto &VMS::Stdio::vmsopen;  }  elsif ($func eq 'fgetname') {    Carp::carp("Old function &fgetname is now &getname");    goto &VMS::Stdio::getname;  }  else { goto &{"VMS::Stdio::$func"}; }}package VMS::Stdio;  # in case we ever use AutoLoader1;__END__=head1 NAMEVMS::Stdio - standard I/O functions via VMS extensions=head1 SYNOPSIS  use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam                     &vmsopen &vmssysopen &waitfh &writeof );  setdef("new:[default.dir]");  $uniquename = tmpnam;  $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;  $name = getname($fh);  print $fh "Hello, world!\n";  flush($fh);  sync($fh);  rewind($fh);  $line = <$fh>;  undef $fh;  # closes file  $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");  sysread($fh,$data,128);  waitfh($fh);  close($fh);  remove("another.file");  writeof($pipefh);  binmode($fh);=head1 DESCRIPTIONThis package gives Perl scripts access via VMS extensions to severalC stdio operations not available through Perl's CORE I/O functions.The specific routines are described below.  These functions areprototyped as unary operators, with the exception of C<vmsopen>and C<vmssysopen>, which can take any number of arguments, andC<tmpnam>, which takes none.All of the routines are available for export, though none areexported by default.  All of the constants used by C<vmssysopen>to specify access modes are exported by default.  The routinesare associated with the Exporter tag FUNCTIONS, and the constantsare associated with the Exporter tag CONSTANTS, so you can moreeasily choose what you'd like to import:    # import constants, but not functions    use VMS::Stdio;  # same as use VMS::Stdio qw( :DEFAULT );    # import functions, but not constants    use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS );     # import both    use VMS::Stdio qw( :CONSTANTS :FUNCTIONS );     # import neither    use VMS::Stdio ();Of course, you can also choose to import specific functions byname, as usual.This package C<ISA> IO::File, so that you can call IO::Filemethods on the handles returned by C<vmsopen> and C<vmssysopen>.The IO::File package is not initialized, however, until youactually call a method that VMS::Stdio doesn't provide.  Thisis done to save startup time for users who don't wish to usethe IO::File methods.B<Note:>  In order to conform to naming conventions for Perlextensions and functions, the name of this package has beenchanged to VMS::Stdio as of Perl 5.002, and the names of someroutines have been changed.  Calls to the old VMS::stdio routineswill generate a warning, and will be routed to the equivalentVMS::Stdio function.  This compatibility interface will beremoved in a future release of this extension, so pleaseupdate your code to use the new routines.=over=item binmodeThis function causes the file handle to be reopened with the CRTL'scarriage control processing disabled; its effect is the same as thatof the C<b> access mode in C<vmsopen>.  After the file is reopened,the file pointer is positioned as close to its position before thecall as possible (I<i.e.> as close as fsetpos() can get it -- forsome record-structured files, it's not possible to return to theexact byte offset in the file).  Because the file must be reopened,this function cannot be used on temporary-delete files. C<binmode>returns true if successful, and C<undef> if not.Note that the effect of C<binmode> differs from that of the binmode()function on operating systems such as Windows and MSDOS, and is notneeded to process most types of file.=item flushThis function causes the contents of stdio buffers for the specifiedfile handle to be flushed.  If C<undef> is used as the argument toC<flush>, all currently open file handles are flushed.  Like the CRTLfflush() routine, it does not flush any underlying RMS buffers for thefile, so the data may not be flushed all the way to the disk.  C<flush>returns a true value if successful, and C<undef> if not.=item getnameThe C<getname> function returns the file specification associatedwith a Perl I/O handle.  If an error occurs, it returns C<undef>.=item removeThis function deletes the file named in its argument, returninga true value if successful and C<undef> if not.  It differs fromthe CORE Perl function C<unlink> in that it does not try toreset file protection if the original protection does not giveyou delete access to the file (cf. L<perlvms>).  In other words,C<remove> is equivalent to  unlink($file) if VMS::Filespec::candelete($file);=item rewindC<rewind> resets the current position of the specified file handleto the beginning of the file.  It's really just a conveniencemethod equivalent in effect to C<seek($fh,0,0)>.  It returns atrue value if successful, and C<undef> if it fails.=item setdefThis function sets the default device and directory for the process.It is identical to the built-in chdir() operator, except that the changepersists after Perl exits.  It returns a true value on success, andC<undef> if it encounters an error.=item syncThis function flushes buffered data for the specified file handlefrom stdio and RMS buffers all the way to disk.  If successful, itreturns a true value; otherwise, it returns C<undef>.=item tmpnamThe C<tmpnam> function returns a unique string which can be usedas a filename when creating temporary files.  If, for somereason, it is unable to generate a name, it returns C<undef>.=item vmsopenThe C<vmsopen> function enables you to specify optional RMS argumentsto the VMS CRTL when opening a file.  Its operation is similar to the built-inPerl C<open> function (see L<perlfunc> for a complete description),but it will only open normal files; it cannot open pipes or duplicateexisting I/O handles.  Up to 8 optional arguments may follow thefile name.  These arguments should be strings which specifyoptional file characteristics as allowed by the CRTL. (See theCRTL reference manual description of creat() and fopen() for details.)If successful, C<vmsopen> returns a VMS::Stdio file handle; if anerror occurs, it returns C<undef>.You can use the file handle returned by C<vmsopen> just as youwould any other Perl file handle.  The class VMS::Stdio ISAIO::File, so you can call IO::File methods using the handlereturned by C<vmsopen>.  However, C<use>ing VMS::Stdio does notautomatically C<use> IO::File; you must do so explicitly inyour program if you want to call IO::File methods.  This isdone to avoid the overhead of initializing the IO::File packagein programs which intend to use the handle returned by C<vmsopen>as a normal Perl file handle only.  When the scalar containinga VMS::Stdio file handle is overwritten, C<undef>d, or goesout of scope, the associated file is closed automatically.=over 4=head2 File characteristic options=over 2=item alq=INTEGERSets the allocation quantity for this file=item bls=INTEGERFile blocksize=item ctx=STRINGSets the context for the file. Takes one of these arguments:=over 4=item binDisables LF to CRLF translation=item cvtNegates previous setting of C<ctx=noctx>=item nocvtDisables conversion of FORTRAN carriage control=item recForce record-mode access=item stmForce stream mode=item xplctCauses records to be flushed I<only> when the file is closed, or when anexplicit flush is done=back=item deq=INTEGERSets the default extension quantity=item dna=FILESPECSets the default filename string. Used to fill in any missing pieces of thefilename passed.=item fop=STRINGFile processing option. Takes one or more of the following (in acomma-separated list if there's more than one)=over 4=item ctgContiguous.=item cbtContiguous-best-try.=item dfwDeferred write; only applicable to files opened for shared access.=item dltDelete file on close.=item tefTruncate at end-of-file.=item cifCreate if nonexistent.=item supSupersede.=item scfSubmit as command file on close.=item splSpool to system printer on close.=item tmdTemporary delete.=item tmpTemporary (no file directory).=item nefNot end-of-file.=item rckRead check compare operation.=item wckWrite check compare operation.=item mxvMaximize version number.=item rwoRewind file on open.=item posCurrent position.=item rwcRewind file on close.=item sqoFile can only be processed in a sequential manner.=back=item fsz=INTEGERFixed header size=item gbc=INTEGERGlobal buffers requested for the file=item mbc=INTEGERMultiblock count=item mbf=INTEGERBultibuffer count=item mrs=INTEGERMaximum record size=item rat=STRINGFile record attributes. Takes one of the following:=over 4=item crCarriage-return control.=item blkDisallow records to span block boundaries.=item ftnFORTRAN print control.=item noneExplicitly forces no carriage control.=item prnPrint file format.=back=item rfm=STRINGFile record format. Takes one of the following:=over 4=item fixFixed-length record format.=item stmRMS stream record format.=item stmlfStream format with line-feed terminator.=item stmcrStream format with carriage-return terminator.=item varVariable-length record format.=item vfcVariable-length record with fixed control.=item udfUndefined format=back=item rop=STRINGRecord processing operations. Takes one or more of the following in acomma-separated list:=over 4=item asyAsynchronous I/O.=item ccoCancel Ctrl/O (used with Terminal I/O).=item cvtCapitalizes characters on a read from the terminal.=item eofPositions the record stream to the end-of-file for the connect operationonly.=item nlkDo not lock record.=item pmtEnables use of the prompt specified by pmt=usr-prmpt on input from theterminal.=item ptaEliminates any information in the type-ahead buffer on a read from theterminal.=item reaLocks record for a read operation for this process, while allowing otheraccessors to read the record.=item rlkLocks record for write.=item rneSuppresses echoing of input data on the screen as it is entered on thekeyboard.=item rnfIndicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered controlcommands on terminal input, but are to be passed to the applicationprogram.=item rrlReads regardless of lock.=item syncstsReturns success status of RMS$_SYNCH if the requested service completes itstask immediately.=item tmoTimeout I/O.=item tptAllows put/write services using sequential record access mode to occur atany point in the file, truncating the file at that point.=item ulkProhibits RMS from automatically unlocking records.=item watWait until record is available, if currently locked by another stream.=item rahRead ahead.=item wbhWrite behind.=back=item rtv=INTEGERThe number of retrieval pointers that RMS has to maintain (0 to 127255)=item shr=STRINGFile sharing options. Choose one of the following:=over 4=item delAllows users to delete.=item getAllows users to read.=item mseAllows mainstream access.=item nilProhibits file sharing.=item putAllows users to write.=item updAllows users to update.=item upiAllows one or more writers.=back=item tmo=INTEGERI/O timeout value=back=back=item vmssysopenThis function bears the same relationship to the CORE functionC<sysopen> as C<vmsopen> does to C<open>.  Its first three argumentsare the name, access flags, and permissions for the file.  LikeC<vmsopen>, it takes up to 8 additional string arguments whichspecify file characteristics.  Its return value is identical tothat of C<vmsopen>.The symbolic constants for the mode argument are exported byVMS::Stdio by default, and are also exported by the Fcntl package.=item waitfhThis function causes Perl to wait for the completion of an I/Ooperation on the file handle specified as its argument.  It isused with handles opened for asynchronous I/O, and performs itstask by calling the CRTL routine fwait().=item writeofThis function writes an EOF to a file handle, if the device driversupports this operation.  Its primary use is to send an EOF to asubprocess through a pipe opened for writing without closing thepipe.  It returns a true value if successful, and C<undef> ifit encounters an error.=head1 REVISIONThis document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and5.6.0.=cut