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.01
   5 #   Revised: 10-Dec-1996
   6
   7 package VMS::Stdio;
   8
   9 require 5.002;
  10 use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA );
  11 use Carp '&croak';
  12 use DynaLoader ();
  13 use Exporter ();
  14
  15 $VERSION = '2.01';
  16 @ISA = qw( Exporter DynaLoader IO::File );
  17 @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY &O_NOWAIT
  18               &O_RDONLY &O_RDWR  &O_TRUNC &O_WRONLY );
  19 @EXPORT_OK = qw( &flush &getname &remove &rewind &sync &tmpnam
  20                  &vmsopen &vmssysopen &waitfh );
  21 %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( &flush &getname &remove &rewind &sync
  25                                      &tmpnam &vmsopen &vmssysopen &waitfh ) ] );
  26
  27 bootstrap VMS::Stdio $VERSION;
  28
  29 sub AUTOLOAD {
  30     my($constname) = $AUTOLOAD;
  31     $constname =~ s/.*:://;
  32     if ($constname =~ /^O_/) {
  33       my($val) = constant($constname);
  34       defined $val or croak("Unknown VMS::Stdio constant $constname");
  35       *$AUTOLOAD = sub { val; }
  36     }
  37     else { # We don't know about it; hand off to IO::File
  38       require IO::File;
  39
  40       *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }";
  41       croak "Error autoloading IO::File::$constname: $@" if $@;
  42     }
  43     goto &$AUTOLOAD;
  44 }
  45
  46 sub DESTROY { close($_[0]); }
  47
  48
  49 ################################################################################
  50 # Intercept calls to old VMS::stdio package, complain, and hand off
  51 # This will be removed in a future version of VMS::Stdio
  52
  53 package VMS::stdio;
  54
  55 sub AUTOLOAD {
  56   my($func) = $AUTOLOAD;
  57   $func =~ s/.*:://;
  58   # Cheap trick: we know DynaLoader has required Carp.pm
  59   Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code");
  60   if ($func eq 'vmsfopen') {
  61     Carp::carp("Old function &vmsfopen is now &vmsopen");
  62     goto &VMS::Stdio::vmsopen;
  63   }
  64   elsif ($func eq 'fgetname') {
  65     Carp::carp("Old function &fgetname is now &getname");
  66     goto &VMS::Stdio::getname;
  67   }
  68   else { goto &{"VMS::Stdio::$func"}; }
  69 }
  70
  71 package VMS::Stdio;  # in case we ever use AutoLoader
  72
  73 1;
  74
  75 __END__
  76
  77 =head1 NAME
  78
  79 VMS::Stdio
  80
  81 =head1 SYNOPSIS
  82
  83 use VMS::Stdio qw( &flush &getname &remove &rewind &sync &tmpnam
  84                    &vmsopen &vmssysopen &waitfh );
  85 $uniquename = tmpnam;
  86 $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;
  87 $name = getname($fh);
  88 print $fh "Hello, world!\n";
  89 flush($fh);
  90 sync($fh);
  91 rewind($fh);
  92 $line = <$fh>;
  93 undef $fh;  # closes file
  94 $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");
  95 sysread($fh,$data,128);
  96 waitfh($fh);
  97 close($fh);
  98 remove("another.file");
  99
 100 =head1 DESCRIPTION
 101
 102 This package gives Perl scripts access to VMS extensions to several
 103 C stdio operations not available through Perl's CORE I/O functions.
 104 The specific routines are described below.  These functions are
 105 prototyped as unary operators, with the exception of C<vmsopen>
 106 and C<vmssysopen>, which can take any number of arguments, and
 107 C<tmpnam>, which takes none.
 108
 109 All of the routines are available for export, though none are
 110 exported by default.  All of the constants used by C<vmssysopen>
 111 to specify access modes are exported by default.  The routines
 112 are associated with the Exporter tag FUNCTIONS, and the constants
 113 are associated with the Exporter tag CONSTANTS, so you can more
 114 easily choose what you'd like to import:
 115
 116     # import constants, but not functions
 117     use VMS::Stdio;  # same as use VMS::Stdio qw( :DEFAULT );
 118     # import functions, but not constants
 119     use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS );
 120     # import both
 121     use VMS::Stdio qw( :CONSTANTS :FUNCTIONS );
 122     # import neither
 123     use VMS::Stdio ();
 124
 125 Of course, you can also choose to import specific functions by
 126 name, as usual.
 127
 128 This package C<ISA> IO::File, so that you can call IO::File
 129 methods on the handles returned by C<vmsopen> and C<vmssysopen>.
 130 The IO::File package is not initialized, however, until you
 131 actually call a method that VMS::Stdio doesn't provide.  This
 132 is doen to save startup time for users who don't wish to use
 133 the IO::File methods.
 134
 135 B<Note:>  In order to conform to naming conventions for Perl
 136 extensions and functions, the name of this package has been
 137 changed to VMS::Stdio as of Perl 5.002, and the names of some
 138 routines have been changed.  Calls to the old VMS::stdio routines
 139 will generate a warning, and will be routed to the equivalent
 140 VMS::Stdio function.  This compatibility interface will be
 141 removed in a future release of this extension, so please
 142 update your code to use the new routines.
 143
 144 =item flush
 145
 146 This function causes the contents of stdio buffers for the specified
 147 file handle to be flushed.  If C<undef> is used as the argument to
 148 C<flush>, all currently open file handles are flushed.  Like the CRTL
 149 fflush() routine, it does not flush any underlying RMS buffers for the
 150 file, so the data may not be flushed all the way to the disk.  C<flush>
 151 returns a true value if successful, and C<undef> if not.
 152
 153 =item getname
 154
 155 The C<getname> function returns the file specification associated
 156 with a Perl I/O handle.  If an error occurs, it returns C<undef>.
 157
 158 =item remove
 159
 160 This function deletes the file named in its argument, returning
 161 a true value if successful and C<undef> if not.  It differs from
 162 the CORE Perl function C<unlink> in that it does not try to
 163 reset file protection if the original protection does not give
 164 you delete access to the file (cf. L<perlvms>).  In other words,
 165 C<remove> is equivalent to
 166
 167   unlink($file) if VMS::Filespec::candelete($file);
 168
 169 =item rewind
 170
 171 C<rewind> resets the current position of the specified file handle
 172 to the beginning of the file.  It's really just a convenience
 173 method equivalent in effect to C<seek($fh,0,0)>.  It returns a
 174 true value if successful, and C<undef> if it fails.
 175
 176 =item sync
 177
 178 This function flushes buffered data for the specified file handle
 179 from stdio and RMS buffers all the way to disk.  If successful, it
 180 returns a true value; otherwise, it returns C<undef>.
 181
 182 =item tmpnam
 183
 184 The C<tmpnam> function returns a unique string which can be used
 185 as a filename when creating temporary files.  If, for some
 186 reason, it is unable to generate a name, it returns C<undef>.
 187
 188 =item vmsopen
 189
 190 The C<vmsopen> function enables you to specify optional RMS arguments
 191 to the VMS CRTL when opening a file.  Its operation is similar to the built-in
 192 Perl C<open> function (see L<perlfunc> for a complete description),
 193 but it will only open normal files; it cannot open pipes or duplicate
 194 existing I/O handles.  Up to 8 optional arguments may follow the
 195 file name.  These arguments should be strings which specify
 196 optional file characteristics as allowed by the CRTL. (See the
 197 CRTL reference manual description of creat() and fopen() for details.)
 198 If successful, C<vmsopen> returns a VMS::Stdio file handle; if an
 199 error occurs, it returns C<undef>.
 200
 201 You can use the file handle returned by C<vmsopen> just as you
 202 would any other Perl file handle.  The class VMS::Stdio ISA
 203 IO::File, so you can call IO::File methods using the handle
 204 returned by C<vmsopen>.  However, C<use>ing VMS::Stdio does not
 205 automatically C<use> IO::File; you must do so explicitly in
 206 your program if you want to call IO::File methods.  This is
 207 done to avoid the overhead of initializing the IO::File package
 208 in programs which intend to use the handle returned by C<vmsopen>
 209 as a normal Perl file handle only.  When the scalar containing
 210 a VMS::Stdio file handle is overwritten, C<undef>d, or goes
 211 out of scope, the associated file is closed automatically.
 212
 213 =item vmssysopen
 214
 215 This function bears the same relationship to the CORE function
 216 C<sysopen> as C<vmsopen> does to C<open>.  Its first three arguments
 217 are the name, access flags, and permissions for the file.  Like
 218 C<vmsopen>, it takes up to 8 additional string arguments which
 219 specify file characteristics.  Its return value is identical to
 220 that of C<vmsopen>.
 221
 222 The symbolic constants for the mode argument are exported by
 223 VMS::Stdio by default, and are also exported by the Fcntl package.
 224
 225 =item waitfh
 226
 227 This function causes Perl to wait for the completion of an I/O
 228 operation on the file handle specified as its argument.  It is
 229 used with handles opened for asynchronous I/O, and performs its
 230 task by calling the CRTL routine fwait().
 231
 232 =head1 REVISION
 233
 234 This document was last revised on 10-Dec-1996, for Perl 5.004.
 235
 236 =cut