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