1 # VMS::Stdio - VMS extensions to Perl's stdio calls
3 # Author: Charles Bailey bailey@genetics.upenn.edu
6 # Docs revised: 13-Oct-1998 Dan Sugalski <sugalskd@ous.edu>
11 use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA );
17 @ISA = qw( Exporter DynaLoader IO::File );
18 @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY &O_NOWAIT
19 &O_RDONLY &O_RDWR &O_TRUNC &O_WRONLY );
20 @EXPORT_OK = qw( &binmode &flush &getname &remove &rewind &sync &setdef &tmpnam
21 &vmsopen &vmssysopen &waitfh &writeof );
22 %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY
23 &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC
25 FUNCTIONS => [ qw( &binmode &flush &getname &remove &rewind
26 &setdef &sync &tmpnam &vmsopen &vmssysopen
27 &waitfh &writeof ) ] );
29 bootstrap VMS::Stdio $VERSION;
32 my($constname) = $AUTOLOAD;
33 $constname =~ s/.*:://;
34 if ($constname =~ /^O_/) {
35 my($val) = constant($constname);
36 defined $val or croak("Unknown VMS::Stdio constant $constname");
37 *$AUTOLOAD = sub { $val; }
39 else { # We don't know about it; hand off to IO::File
42 *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }";
43 croak "Error autoloading IO::File::$constname: $@" if $@;
48 sub DESTROY { close($_[0]); }
51 ################################################################################
52 # Intercept calls to old VMS::stdio package, complain, and hand off
53 # This will be removed in a future version of VMS::Stdio
58 my($func) = $AUTOLOAD;
60 # Cheap trick: we know DynaLoader has required Carp.pm
61 Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code");
62 if ($func eq 'vmsfopen') {
63 Carp::carp("Old function &vmsfopen is now &vmsopen");
64 goto &VMS::Stdio::vmsopen;
66 elsif ($func eq 'fgetname') {
67 Carp::carp("Old function &fgetname is now &getname");
68 goto &VMS::Stdio::getname;
70 else { goto &{"VMS::Stdio::$func"}; }
73 package VMS::Stdio; # in case we ever use AutoLoader
81 VMS::Stdio - standard I/O functions via VMS extensions
85 use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam
86 &vmsopen &vmssysopen &waitfh &writeof );
87 setdef("new:[default.dir]");
89 $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;
91 print $fh "Hello, world!\n";
96 undef $fh; # closes file
97 $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");
98 sysread($fh,$data,128);
101 remove("another.file");
107 This package gives Perl scripts access via VMS extensions to several
108 C stdio operations not available through Perl's CORE I/O functions.
109 The specific routines are described below. These functions are
110 prototyped as unary operators, with the exception of C<vmsopen>
111 and C<vmssysopen>, which can take any number of arguments, and
112 C<tmpnam>, which takes none.
114 All of the routines are available for export, though none are
115 exported by default. All of the constants used by C<vmssysopen>
116 to specify access modes are exported by default. The routines
117 are associated with the Exporter tag FUNCTIONS, and the constants
118 are associated with the Exporter tag CONSTANTS, so you can more
119 easily choose what you'd like to import:
121 # import constants, but not functions
122 use VMS::Stdio; # same as use VMS::Stdio qw( :DEFAULT );
123 # import functions, but not constants
124 use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS );
126 use VMS::Stdio qw( :CONSTANTS :FUNCTIONS );
130 Of course, you can also choose to import specific functions by
133 This package C<ISA> IO::File, so that you can call IO::File
134 methods on the handles returned by C<vmsopen> and C<vmssysopen>.
135 The IO::File package is not initialized, however, until you
136 actually call a method that VMS::Stdio doesn't provide. This
137 is doen to save startup time for users who don't wish to use
138 the IO::File methods.
140 B<Note:> In order to conform to naming conventions for Perl
141 extensions and functions, the name of this package has been
142 changed to VMS::Stdio as of Perl 5.002, and the names of some
143 routines have been changed. Calls to the old VMS::stdio routines
144 will generate a warning, and will be routed to the equivalent
145 VMS::Stdio function. This compatibility interface will be
146 removed in a future release of this extension, so please
147 update your code to use the new routines.
153 This function causes the file handle to be reopened with the CRTL's
154 carriage control processing disabled; its effect is the same as that
155 of the C<b> access mode in C<vmsopen>. After the file is reopened,
156 the file pointer is positioned as close to its position before the
157 call as possible (I<i.e.> as close as fsetpos() can get it -- for
158 some record-structured files, it's not possible to return to the
159 exact byte offset in the file). Because the file must be reopened,
160 this function cannot be used on temporary-delete files. C<binmode>
161 returns true if successful, and C<undef> if not.
163 Note that the effect of C<binmode> differs from that of the binmode()
164 function on operating systems such as Windows and MSDOS, and is not
165 needed to process most types of file.
169 This function causes the contents of stdio buffers for the specified
170 file handle to be flushed. If C<undef> is used as the argument to
171 C<flush>, all currently open file handles are flushed. Like the CRTL
172 fflush() routine, it does not flush any underlying RMS buffers for the
173 file, so the data may not be flushed all the way to the disk. C<flush>
174 returns a true value if successful, and C<undef> if not.
178 The C<getname> function returns the file specification associated
179 with a Perl I/O handle. If an error occurs, it returns C<undef>.
183 This function deletes the file named in its argument, returning
184 a true value if successful and C<undef> if not. It differs from
185 the CORE Perl function C<unlink> in that it does not try to
186 reset file protection if the original protection does not give
187 you delete access to the file (cf. L<perlvms>). In other words,
188 C<remove> is equivalent to
190 unlink($file) if VMS::Filespec::candelete($file);
194 C<rewind> resets the current position of the specified file handle
195 to the beginning of the file. It's really just a convenience
196 method equivalent in effect to C<seek($fh,0,0)>. It returns a
197 true value if successful, and C<undef> if it fails.
201 This function sets the default device and directory for the process.
202 It is identical to the built-in chdir() operator, except that the change
203 persists after Perl exits. It returns a true value on success, and
204 C<undef> if it encounters and error.
208 This function flushes buffered data for the specified file handle
209 from stdio and RMS buffers all the way to disk. If successful, it
210 returns a true value; otherwise, it returns C<undef>.
214 The C<tmpnam> function returns a unique string which can be used
215 as a filename when creating temporary files. If, for some
216 reason, it is unable to generate a name, it returns C<undef>.
220 The C<vmsopen> function enables you to specify optional RMS arguments
221 to the VMS CRTL when opening a file. Its operation is similar to the built-in
222 Perl C<open> function (see L<perlfunc> for a complete description),
223 but it will only open normal files; it cannot open pipes or duplicate
224 existing I/O handles. Up to 8 optional arguments may follow the
225 file name. These arguments should be strings which specify
226 optional file characteristics as allowed by the CRTL. (See the
227 CRTL reference manual description of creat() and fopen() for details.)
228 If successful, C<vmsopen> returns a VMS::Stdio file handle; if an
229 error occurs, it returns C<undef>.
231 You can use the file handle returned by C<vmsopen> just as you
232 would any other Perl file handle. The class VMS::Stdio ISA
233 IO::File, so you can call IO::File methods using the handle
234 returned by C<vmsopen>. However, C<use>ing VMS::Stdio does not
235 automatically C<use> IO::File; you must do so explicitly in
236 your program if you want to call IO::File methods. This is
237 done to avoid the overhead of initializing the IO::File package
238 in programs which intend to use the handle returned by C<vmsopen>
239 as a normal Perl file handle only. When the scalar containing
240 a VMS::Stdio file handle is overwritten, C<undef>d, or goes
241 out of scope, the associated file is closed automatically.
245 =head2 File characteristic options
251 Sets the allocation quantity for this file
259 Sets the context for the file. Takes one of these arguments:
265 Disables LF to CRLF translation
269 Negates previous setting of C<ctx=noctx>
273 Disables conversion of FORTRAN carriage control
277 Force record-mode access
285 Causes records to be flushed I<only> when the file is closed, or when an
286 explicit flush is done
292 Sets the default extension quantity
296 Sets the default filename string. Used to fill in any missing pieces of the
301 File processing option. Takes one or more of the following (in a
302 comma-separated list if there's more than one)
316 Deferred write; only applicable to files opened for shared access.
320 Delete file on close.
324 Truncate at end-of-file.
328 Create if nonexistent.
336 Submit as command file on close.
340 Spool to system printer on close.
348 Temporary (no file directory).
356 Read check compare operation.
360 Write check compare operation.
364 Maximize version number.
376 Rewind file on close.
380 File can only be processed in a sequential manner.
390 Global buffers requested for the file
406 File record attributes. Takes one of the following:
412 Carriage-return control.
416 Disallow records to span block boundaries.
420 FORTRAN print control.
424 Explicitly forces no carriage control.
434 File record format. Takes one of the following:
440 Fixed-length record format.
444 RMS stream record format.
448 Stream format with line-feed terminator.
452 Stream format with carriage-return terminator.
456 Variable-length record format.
460 Variable-length record with fixed control.
470 Record processing operations. Takes one or more of the following in a
471 comma-separated list:
481 Cancel Ctrl/O (used with Terminal I/O).
485 Capitalizes characters on a read from the terminal.
489 Positions the record stream to the end-of-file for the connect operation
498 Enables use of the prompt specified by pmt=usr-prmpt on input from the
503 Eliminates any information in the type-ahead buffer on a read from the
508 Locks record for a read operation for this process, while allowing other
509 accessors to read the record.
513 Locks record for write.
517 Suppresses echoing of input data on the screen as it is entered on the
522 Indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control
523 commands on terminal input, but are to be passed to the application
528 Reads regardless of lock.
532 Returns success status of RMS$_SYNCH if the requested service completes its
541 Allows put/write services using sequential record access mode to occur at
542 any point in the file, truncating the file at that point.
546 Prohibits RMS from automatically unlocking records.
550 Wait until record is available, if currently locked by another stream.
564 The number of retrieval pointers that RMS has to maintain (0 to 127255)
568 File sharing options. Choose one of the following:
574 Allows users to delete.
578 Allows users to read.
582 Allows mainstream access.
586 Prohibits file sharing.
590 Allows users to write.
594 Allows users to update.
598 Allows one or more writers.
612 This function bears the same relationship to the CORE function
613 C<sysopen> as C<vmsopen> does to C<open>. Its first three arguments
614 are the name, access flags, and permissions for the file. Like
615 C<vmsopen>, it takes up to 8 additional string arguments which
616 specify file characteristics. Its return value is identical to
619 The symbolic constants for the mode argument are exported by
620 VMS::Stdio by default, and are also exported by the Fcntl package.
624 This function causes Perl to wait for the completion of an I/O
625 operation on the file handle specified as its argument. It is
626 used with handles opened for asynchronous I/O, and performs its
627 task by calling the CRTL routine fwait().
631 This function writes an EOF to a file handle, if the device driver
632 supports this operation. Its primary use is to send an EOF to a
633 subprocess through a pipe opened for writing without closing the
634 pipe. It returns a true value if successful, and C<undef> if
635 it encounters an error.
639 This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and