Commit | Line | Data |
0d7e20a5 |
1 | # VMS::Stdio - VMS extensions to Perl's stdio calls |
748a9306 |
2 | # |
3 | # Author: Charles Bailey bailey@genetics.upenn.edu |
562a7b0c |
4 | # Version: 2.2 |
5 | # Revised: 19-Jul-1998 |
c1441b10 |
6 | # Docs revised: 13-Oct-1998 Dan Sugalski <sugalskd@ous.edu> |
0d7e20a5 |
7 | |
8 | package VMS::Stdio; |
9 | |
10 | require 5.002; |
11 | use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA ); |
12 | use Carp '&croak'; |
13 | use DynaLoader (); |
14 | use Exporter (); |
15 | |
562a7b0c |
16 | $VERSION = '2.2'; |
740ce14c |
17 | @ISA = qw( Exporter DynaLoader IO::File ); |
0d7e20a5 |
18 | @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY &O_NOWAIT |
19 | &O_RDONLY &O_RDWR &O_TRUNC &O_WRONLY ); |
562a7b0c |
20 | @EXPORT_OK = qw( &binmode &flush &getname &remove &rewind &sync &setdef &tmpnam |
17f28c40 |
21 | &vmsopen &vmssysopen &waitfh &writeof ); |
0d7e20a5 |
22 | %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY |
23 | &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC |
24 | &O_WRONLY ) ], |
562a7b0c |
25 | FUNCTIONS => [ qw( &binmode &flush &getname &remove &rewind |
26 | &setdef &sync &tmpnam &vmsopen &vmssysopen |
17f28c40 |
27 | &waitfh &writeof ) ] ); |
0d7e20a5 |
28 | |
29 | bootstrap VMS::Stdio $VERSION; |
30 | |
31 | sub AUTOLOAD { |
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"); |
09b7f37c |
37 | *$AUTOLOAD = sub { $val; } |
0d7e20a5 |
38 | } |
740ce14c |
39 | else { # We don't know about it; hand off to IO::File |
40 | require IO::File; |
55497cff |
41 | |
5f05dabc |
42 | *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }"; |
43 | croak "Error autoloading IO::File::$constname: $@" if $@; |
0d7e20a5 |
44 | } |
45 | goto &$AUTOLOAD; |
46 | } |
47 | |
48 | sub DESTROY { close($_[0]); } |
49 | |
50 | |
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 |
54 | |
55 | package VMS::stdio; |
56 | |
57 | sub AUTOLOAD { |
58 | my($func) = $AUTOLOAD; |
59 | $func =~ s/.*:://; |
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; |
65 | } |
66 | elsif ($func eq 'fgetname') { |
67 | Carp::carp("Old function &fgetname is now &getname"); |
68 | goto &VMS::Stdio::getname; |
69 | } |
70 | else { goto &{"VMS::Stdio::$func"}; } |
71 | } |
72 | |
73 | package VMS::Stdio; # in case we ever use AutoLoader |
74 | |
75 | 1; |
76 | |
77 | __END__ |
748a9306 |
78 | |
79 | =head1 NAME |
80 | |
2ceaccd7 |
81 | VMS::Stdio - standard I/O functions via VMS extensions |
748a9306 |
82 | |
83 | =head1 SYNOPSIS |
84 | |
c1441b10 |
85 | use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam |
86 | &vmsopen &vmssysopen &waitfh &writeof ); |
87 | setdef("new:[default.dir]"); |
88 | $uniquename = tmpnam; |
89 | $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!; |
90 | $name = getname($fh); |
91 | print $fh "Hello, world!\n"; |
92 | flush($fh); |
93 | sync($fh); |
94 | rewind($fh); |
95 | $line = <$fh>; |
96 | undef $fh; # closes file |
97 | $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin"); |
98 | sysread($fh,$data,128); |
99 | waitfh($fh); |
100 | close($fh); |
101 | remove("another.file"); |
102 | writeof($pipefh); |
562a7b0c |
103 | binmode($fh); |
c1441b10 |
104 | |
748a9306 |
105 | =head1 DESCRIPTION |
106 | |
2ceaccd7 |
107 | This package gives Perl scripts access via VMS extensions to several |
0d7e20a5 |
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. |
113 | |
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: |
120 | |
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 ); |
125 | # import both |
126 | use VMS::Stdio qw( :CONSTANTS :FUNCTIONS ); |
127 | # import neither |
128 | use VMS::Stdio (); |
129 | |
130 | Of course, you can also choose to import specific functions by |
131 | name, as usual. |
132 | |
740ce14c |
133 | This package C<ISA> IO::File, so that you can call IO::File |
0d7e20a5 |
134 | methods on the handles returned by C<vmsopen> and C<vmssysopen>. |
740ce14c |
135 | The IO::File package is not initialized, however, until you |
0d7e20a5 |
136 | actually call a method that VMS::Stdio doesn't provide. This |
d5d9880c |
137 | is done to save startup time for users who don't wish to use |
740ce14c |
138 | the IO::File methods. |
0d7e20a5 |
139 | |
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. |
148 | |
4ac9195f |
149 | =over 4 |
2ceaccd7 |
150 | |
562a7b0c |
151 | =item binmode |
152 | |
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. |
162 | |
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. |
166 | |
0d7e20a5 |
167 | =item flush |
168 | |
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. |
175 | |
176 | =item getname |
177 | |
178 | The C<getname> function returns the file specification associated |
740ce14c |
179 | with a Perl I/O handle. If an error occurs, it returns C<undef>. |
748a9306 |
180 | |
0d7e20a5 |
181 | =item remove |
748a9306 |
182 | |
0d7e20a5 |
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 |
189 | |
190 | unlink($file) if VMS::Filespec::candelete($file); |
748a9306 |
191 | |
0d7e20a5 |
192 | =item rewind |
193 | |
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. |
198 | |
17f28c40 |
199 | =item setdef |
200 | |
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 |
d5d9880c |
204 | C<undef> if it encounters an error. |
17f28c40 |
205 | |
0d7e20a5 |
206 | =item sync |
207 | |
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>. |
211 | |
212 | =item tmpnam |
748a9306 |
213 | |
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>. |
217 | |
0d7e20a5 |
218 | =item vmsopen |
748a9306 |
219 | |
0d7e20a5 |
220 | The C<vmsopen> function enables you to specify optional RMS arguments |
5f05dabc |
221 | to the VMS CRTL when opening a file. Its operation is similar to the built-in |
0d7e20a5 |
222 | Perl C<open> function (see L<perlfunc> for a complete description), |
5f05dabc |
223 | but it will only open normal files; it cannot open pipes or duplicate |
740ce14c |
224 | existing I/O handles. Up to 8 optional arguments may follow the |
748a9306 |
225 | file name. These arguments should be strings which specify |
0d7e20a5 |
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>. |
230 | |
5f05dabc |
231 | You can use the file handle returned by C<vmsopen> just as you |
0d7e20a5 |
232 | would any other Perl file handle. The class VMS::Stdio ISA |
740ce14c |
233 | IO::File, so you can call IO::File methods using the handle |
0d7e20a5 |
234 | returned by C<vmsopen>. However, C<use>ing VMS::Stdio does not |
740ce14c |
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 |
0d7e20a5 |
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. |
242 | |
4ac9195f |
243 | File characteristic options: |
c1441b10 |
244 | |
245 | =over 2 |
246 | |
247 | =item alq=INTEGER |
248 | |
249 | Sets the allocation quantity for this file |
250 | |
251 | =item bls=INTEGER |
252 | |
253 | File blocksize |
254 | |
255 | =item ctx=STRING |
256 | |
257 | Sets the context for the file. Takes one of these arguments: |
258 | |
259 | =over 4 |
260 | |
261 | =item bin |
262 | |
263 | Disables LF to CRLF translation |
264 | |
265 | =item cvt |
266 | |
267 | Negates previous setting of C<ctx=noctx> |
268 | |
269 | =item nocvt |
270 | |
271 | Disables conversion of FORTRAN carriage control |
272 | |
273 | =item rec |
274 | |
275 | Force record-mode access |
276 | |
277 | =item stm |
278 | |
279 | Force stream mode |
280 | |
281 | =item xplct |
282 | |
283 | Causes records to be flushed I<only> when the file is closed, or when an |
284 | explicit flush is done |
285 | |
286 | =back |
287 | |
288 | =item deq=INTEGER |
289 | |
290 | Sets the default extension quantity |
291 | |
292 | =item dna=FILESPEC |
293 | |
294 | Sets the default filename string. Used to fill in any missing pieces of the |
295 | filename passed. |
296 | |
297 | =item fop=STRING |
298 | |
299 | File processing option. Takes one or more of the following (in a |
300 | comma-separated list if there's more than one) |
301 | |
302 | =over 4 |
303 | |
304 | =item ctg |
305 | |
306 | Contiguous. |
307 | |
308 | =item cbt |
309 | |
310 | Contiguous-best-try. |
311 | |
312 | =item dfw |
313 | |
314 | Deferred write; only applicable to files opened for shared access. |
315 | |
316 | =item dlt |
317 | |
318 | Delete file on close. |
319 | |
320 | =item tef |
321 | |
322 | Truncate at end-of-file. |
323 | |
324 | =item cif |
325 | |
326 | Create if nonexistent. |
327 | |
328 | =item sup |
329 | |
330 | Supersede. |
331 | |
332 | =item scf |
333 | |
334 | Submit as command file on close. |
335 | |
336 | =item spl |
337 | |
338 | Spool to system printer on close. |
339 | |
340 | =item tmd |
341 | |
342 | Temporary delete. |
343 | |
344 | =item tmp |
345 | |
346 | Temporary (no file directory). |
347 | |
348 | =item nef |
349 | |
350 | Not end-of-file. |
351 | |
352 | =item rck |
353 | |
354 | Read check compare operation. |
355 | |
356 | =item wck |
357 | |
358 | Write check compare operation. |
359 | |
360 | =item mxv |
361 | |
362 | Maximize version number. |
363 | |
364 | =item rwo |
365 | |
366 | Rewind file on open. |
367 | |
368 | =item pos |
369 | |
370 | Current position. |
371 | |
372 | =item rwc |
373 | |
374 | Rewind file on close. |
375 | |
376 | =item sqo |
377 | |
378 | File can only be processed in a sequential manner. |
379 | |
380 | =back |
381 | |
382 | =item fsz=INTEGER |
383 | |
384 | Fixed header size |
385 | |
386 | =item gbc=INTEGER |
387 | |
388 | Global buffers requested for the file |
389 | |
390 | =item mbc=INTEGER |
391 | |
392 | Multiblock count |
393 | |
394 | =item mbf=INTEGER |
395 | |
396 | Bultibuffer count |
397 | |
398 | =item mrs=INTEGER |
399 | |
400 | Maximum record size |
401 | |
402 | =item rat=STRING |
403 | |
404 | File record attributes. Takes one of the following: |
405 | |
406 | =over 4 |
407 | |
408 | =item cr |
409 | |
410 | Carriage-return control. |
411 | |
412 | =item blk |
413 | |
414 | Disallow records to span block boundaries. |
415 | |
416 | =item ftn |
417 | |
418 | FORTRAN print control. |
419 | |
420 | =item none |
421 | |
422 | Explicitly forces no carriage control. |
423 | |
424 | =item prn |
425 | |
426 | Print file format. |
427 | |
428 | =back |
429 | |
430 | =item rfm=STRING |
431 | |
432 | File record format. Takes one of the following: |
433 | |
434 | =over 4 |
435 | |
436 | =item fix |
437 | |
438 | Fixed-length record format. |
439 | |
440 | =item stm |
441 | |
442 | RMS stream record format. |
443 | |
444 | =item stmlf |
445 | |
446 | Stream format with line-feed terminator. |
447 | |
448 | =item stmcr |
449 | |
450 | Stream format with carriage-return terminator. |
451 | |
452 | =item var |
453 | |
454 | Variable-length record format. |
455 | |
456 | =item vfc |
457 | |
458 | Variable-length record with fixed control. |
459 | |
460 | =item udf |
461 | |
462 | Undefined format |
463 | |
464 | =back |
465 | |
466 | =item rop=STRING |
467 | |
468 | Record processing operations. Takes one or more of the following in a |
469 | comma-separated list: |
470 | |
471 | =over 4 |
472 | |
473 | =item asy |
474 | |
475 | Asynchronous I/O. |
476 | |
477 | =item cco |
478 | |
479 | Cancel Ctrl/O (used with Terminal I/O). |
480 | |
481 | =item cvt |
482 | |
483 | Capitalizes characters on a read from the terminal. |
484 | |
485 | =item eof |
486 | |
487 | Positions the record stream to the end-of-file for the connect operation |
488 | only. |
489 | |
490 | =item nlk |
491 | |
492 | Do not lock record. |
493 | |
494 | =item pmt |
495 | |
496 | Enables use of the prompt specified by pmt=usr-prmpt on input from the |
497 | terminal. |
498 | |
499 | =item pta |
500 | |
501 | Eliminates any information in the type-ahead buffer on a read from the |
502 | terminal. |
503 | |
504 | =item rea |
505 | |
506 | Locks record for a read operation for this process, while allowing other |
507 | accessors to read the record. |
508 | |
509 | =item rlk |
510 | |
511 | Locks record for write. |
512 | |
513 | =item rne |
514 | |
515 | Suppresses echoing of input data on the screen as it is entered on the |
516 | keyboard. |
517 | |
518 | =item rnf |
519 | |
520 | Indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control |
521 | commands on terminal input, but are to be passed to the application |
522 | program. |
523 | |
524 | =item rrl |
525 | |
526 | Reads regardless of lock. |
527 | |
528 | =item syncsts |
529 | |
530 | Returns success status of RMS$_SYNCH if the requested service completes its |
531 | task immediately. |
532 | |
533 | =item tmo |
534 | |
535 | Timeout I/O. |
536 | |
537 | =item tpt |
538 | |
539 | Allows put/write services using sequential record access mode to occur at |
540 | any point in the file, truncating the file at that point. |
541 | |
542 | =item ulk |
543 | |
544 | Prohibits RMS from automatically unlocking records. |
545 | |
546 | =item wat |
547 | |
548 | Wait until record is available, if currently locked by another stream. |
549 | |
550 | =item rah |
551 | |
552 | Read ahead. |
553 | |
554 | =item wbh |
555 | |
556 | Write behind. |
557 | |
558 | =back |
559 | |
560 | =item rtv=INTEGER |
561 | |
562 | The number of retrieval pointers that RMS has to maintain (0 to 127255) |
563 | |
564 | =item shr=STRING |
565 | |
566 | File sharing options. Choose one of the following: |
567 | |
568 | =over 4 |
569 | |
570 | =item del |
571 | |
572 | Allows users to delete. |
573 | |
574 | =item get |
575 | |
576 | Allows users to read. |
577 | |
578 | =item mse |
579 | |
580 | Allows mainstream access. |
581 | |
582 | =item nil |
583 | |
584 | Prohibits file sharing. |
585 | |
586 | =item put |
587 | |
588 | Allows users to write. |
589 | |
590 | =item upd |
591 | |
592 | Allows users to update. |
593 | |
594 | =item upi |
595 | |
596 | Allows one or more writers. |
597 | |
598 | =back |
599 | |
600 | =item tmo=INTEGER |
601 | |
602 | I/O timeout value |
603 | |
604 | =back |
605 | |
0d7e20a5 |
606 | =item vmssysopen |
607 | |
608 | This function bears the same relationship to the CORE function |
609 | C<sysopen> as C<vmsopen> does to C<open>. Its first three arguments |
610 | are the name, access flags, and permissions for the file. Like |
611 | C<vmsopen>, it takes up to 8 additional string arguments which |
612 | specify file characteristics. Its return value is identical to |
613 | that of C<vmsopen>. |
614 | |
615 | The symbolic constants for the mode argument are exported by |
616 | VMS::Stdio by default, and are also exported by the Fcntl package. |
617 | |
618 | =item waitfh |
619 | |
620 | This function causes Perl to wait for the completion of an I/O |
621 | operation on the file handle specified as its argument. It is |
622 | used with handles opened for asynchronous I/O, and performs its |
623 | task by calling the CRTL routine fwait(). |
748a9306 |
624 | |
17f28c40 |
625 | =item writeof |
626 | |
627 | This function writes an EOF to a file handle, if the device driver |
628 | supports this operation. Its primary use is to send an EOF to a |
629 | subprocess through a pipe opened for writing without closing the |
630 | pipe. It returns a true value if successful, and C<undef> if |
631 | it encounters an error. |
632 | |
4ac9195f |
633 | =back |
634 | |
748a9306 |
635 | =head1 REVISION |
636 | |
c1441b10 |
637 | This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and |
85add8c2 |
638 | 5.6.0. |
748a9306 |
639 | |
640 | =cut |