Commit | Line | Data |
---|---|---|
0d7e20a5 | 1 | # VMS::Stdio - VMS extensions to Perl's stdio calls |
748a9306 LW |
2 | # |
3 | # Author: Charles Bailey bailey@genetics.upenn.edu | |
562a7b0c CB |
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 | ||
ae8d64f5 | 16 | $VERSION = '2.4'; |
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 CB |
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 LW |
78 | |
79 | =head1 NAME | |
80 | ||
2ceaccd7 | 81 | VMS::Stdio - standard I/O functions via VMS extensions |
748a9306 LW |
82 | |
83 | =head1 SYNOPSIS | |
84 | ||
c1441b10 HM |
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 LW |
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 CB |
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 CB |
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 LW |
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 HM |
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 CB |
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 MS |
633 | =back |
634 | ||
748a9306 LW |
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 LW |
639 | |
640 | =cut |