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