Commit | Line | Data |
0d7e20a5 |
1 | # VMS::Stdio - VMS extensions to Perl's stdio calls |
748a9306 |
2 | # |
3 | # Author: Charles Bailey bailey@genetics.upenn.edu |
0d7e20a5 |
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 FileHandle ); |
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 FileHandle |
38 | require FileHandle; |
39 | my($obj) = shift(@_); |
40 | $obj->FileHandle::$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__ |
748a9306 |
75 | |
76 | =head1 NAME |
77 | |
0d7e20a5 |
78 | VMS::Stdio |
748a9306 |
79 | |
80 | =head1 SYNOPSIS |
81 | |
0d7e20a5 |
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"); |
748a9306 |
98 | |
99 | =head1 DESCRIPTION |
100 | |
0d7e20a5 |
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> FileHandle, so that you can call FileHandle |
128 | methods on the handles returned by C<vmsopen> and C<vmssysopen>. |
129 | The FileHandle 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 FileHandle 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 FileHandle. If an error occurs, it returns C<undef>. |
748a9306 |
156 | |
0d7e20a5 |
157 | =item remove |
748a9306 |
158 | |
0d7e20a5 |
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); |
748a9306 |
167 | |
0d7e20a5 |
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 |
748a9306 |
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 | |
0d7e20a5 |
187 | =item vmsopen |
748a9306 |
188 | |
0d7e20a5 |
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 |
748a9306 |
193 | existing FileHandles. Up to 8 optional arguments may follow the |
194 | file name. These arguments should be strings which specify |
0d7e20a5 |
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 | FileHandle, so you can call FileHandle methods using the handle |
203 | returned by C<vmsopen>. However, C<use>ing VMS::Stdio does not |
204 | automatically C<use> FileHandle; you must do so explicitly in |
205 | your program if you want to call FileHandle methods. This is |
206 | done to avoid the overhead of initializing the FileHandle 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(). |
748a9306 |
230 | |
231 | =head1 REVISION |
232 | |
0d7e20a5 |
233 | This document was last revised on 28-Jan-1996, for Perl 5.002. |
748a9306 |
234 | |
235 | =cut |