Penguin
Recent Changes
Annotated edit history of perlvms(1) version 2 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 PERLVMS
2 !!!PERLVMS
3 NAME
4 DESCRIPTION
5 Installation
6 Organization of Perl Images
7 File specifications
8 PERL5LIB and PERLLIB
9 Command line
10 Perl functions
11 Perl variables
12 Standard modules with VMS-specific differences
13 Revision date
14 AUTHOR
15 ----
16 !!NAME
17
18
19 perlvms - VMS-specific documentation for Perl
20 !!DESCRIPTION
21
22
23 Gathered below are notes describing details of Perl 5's
24 behavior on VMS . They are a supplement to
25 the regular Perl 5 documentation, so we have focussed on the
26 ways in which Perl 5 functions differently under
27 VMS than it does under Unix, and on the
28 interactions between Perl and the rest of the operating
29 system. We haven't tried to duplicate complete descriptions
30 of Perl features from the main Perl documentation, which can
31 be found in the ''[[.pod]'' subdirectory of the Perl
32 distribution.
33
34
35 We hope these notes will save you from confusion and lost
36 sleep when writing Perl scripts on VMS . If
37 you find we've missed something you think should appear
38 here, please don't hesitate to drop a line to
39 vmsperl@newman.upenn.edu.
40 !!Installation
41
42
43 Directions for building and installing Perl 5 can be found
44 in the file ''README .vms'' in the main
45 source directory of the Perl distribution..
46 !!Organization of Perl Images
47
48
49 __Core Images__
50
51
52 During the installation process, three Perl images are
53 produced. ''Miniperl.Exe'' is an executable image which
54 contains all of the basic functionality of Perl, but cannot
55 take advantage of Perl extensions. It is used to generate
56 several files needed to build the complete Perl and various
57 extensions. Once you've finished installing Perl, you can
58 delete this image.
59
60
61 Most of the complete Perl resides in the shareable image
62 ''!PerlShr.Exe'', which provides a core to which the Perl
63 executable image and all Perl extensions are linked. You
64 should place this image in ''Sys$Share'', or define the
65 logical name ''!PerlShr'' to translate to the full file
66 specification of this image. It should be world readable.
67 (Remember that if a user has execute only access to
68 ''!PerlShr'', VMS will treat it as if it
69 were a privileged shareable image, and will therefore
70 require all downstream shareable images to be INSTALLed,
71 etc.)
72
73
74 Finally, ''Perl.Exe'' is an executable image containing
75 the main entry point for Perl, as well as some
76 initialization code. It should be placed in a public
77 directory, and made world executable. In order to run Perl
78 with command line arguments, you should define a foreign
79 command to invoke this image.
80
81
82 __Perl Extensions__
83
84
85 Perl extensions are packages which provide both
86 XS and Perl code to add new functionality to
87 perl. ( XS is a meta-language which
88 simplifies writing C code which interacts with Perl, see
89 perlxs for more details.) The Perl code for an extension is
90 treated like any other library module - it's made available
91 in your script through the appropriate use or
92 require statement, and usually defines a Perl
93 package containing the extension.
94
95
96 The portion of the extension provided by the
97 XS code may be connected to the rest of Perl
98 in either of two ways. In the __static__ configuration,
99 the object code for the extension is linked directly into
100 ''!PerlShr.Exe'', and is initialized whenever Perl is
101 invoked. In the __dynamic__ configuration, the
102 extension's machine code is placed into a separate shareable
103 image, which is mapped by Perl's !DynaLoader when the
104 extension is used or required in your
105 script. This allows you to maintain the extension as a
106 separate entity, at the cost of keeping track of the
107 additional shareable image. Most extensions can be set up as
108 either static or dynamic.
109
110
111 The source code for an extension usually resides in its own
112 directory. At least three files are generally provided:
113 ''Extshortname.xs'' (where ''Extshortname'' is the
114 portion of the extension's name following the last
115 ::), containing the XS code,
116 ''Extshortname.pm'', the Perl library module for the
117 extension, and ''Makefile.PL'', a Perl script which uses
118 the !MakeMaker library modules supplied with Perl to
119 generate a ''Descrip.MMS'' file for the
120 extension.
121
122
123 __Installing static extensions__
124
125
126 Since static extensions are incorporated directly into
127 ''!PerlShr.Exe'', you'll have to rebuild Perl to
128 incorporate a new extension. You should edit the main
129 ''Descrip.MMS'' or ''Makefile'' you use to build Perl,
130 adding the extension's name to the ext macro, and
131 the extension's object file to the extobj macro.
132 You'll also need to build the extension's object file,
133 either by adding dependencies to the main
134 ''Descrip.MMS'', or using a separate ''Descrip.MMS''
135 for the extension. Then, rebuild ''!PerlShr.Exe'' to
136 incorporate the new code.
137
138
139 Finally, you'll need to copy the extension's Perl library
140 module to the ''[[.Extname]'' subdirectory under one of
141 the directories in @INC, where ''Extname'' is
142 the name of the extension, with all :: replaced by
143 . (e.g. the library module for extension Foo::Bar
144 would be copied to a ''[[.Foo.Bar]''
145 subdirectory).
146
147
148 __Installing dynamic extensions__
149
150
151 In general, the distributed kit for a Perl extension
152 includes a file named Makefile.PL, which is a Perl program
153 which is used to create a ''Descrip.MMS'' file which can
154 be used to build and install the files required by the
155 extension. The kit should be unpacked into a directory tree
156 __not__ under the main Perl source directory, and the
157 procedure for building the extension is simply
158
159
160 $ perl Makefile.PL ! Create Descrip.MMS
161 $ mmk ! Build necessary files
162 $ mmk test ! Run test code, if supplied
163 $ mmk install ! Install into public Perl tree
164 ''N.B.'' The procedure by which extensions are built and tested creates several levels (at least 4) under the directory in which the extension's source files live. For this reason, you shouldn't nest the source directory too deeply in your directory structure, lest you exceed RMS ' maximum of 8 levels of subdirectory in a filespec. (You can use rooted logical names to get another 8 levels of nesting, if you can't place the files near the top of the physical directory structure.)
165
166
167 VMS support for this process in the current
168 release of Perl is sufficient to handle most extensions.
169 However, it does not yet recognize extra libraries required
170 to build shareable images which are part of an extension, so
171 these must be added to the linker options file for the
172 extension by hand. For instance, if the
173 ''PGPLOT'' extension to Perl requires the
174 ''PGPLOTSHR .EXE'' shareable image in
175 order to properly link the Perl extension, then the line
176 PGPLOTSHR/Share must be added to the linker options
177 file ''PGPLOT .Opt'' produced during the
178 build process for the Perl extension.
179
180
181 By default, the shareable image for an extension is placed
182 ''[[.lib.site_perl.autoArch''.''Extname]'' directory of
183 the installed Perl directory tree (where ''Arch'' is
184 ''VMS_VAX'' or
185 ''VMS_AXP'' , and ''Extname'' is the
186 name of the extension, with each :: translated to
187 .). (See the !MakeMaker documentation for more
188 details on installation options for extensions.) However, it
189 can be manually placed in any of several locations: - the
190 ''[[.Lib.Auto.Arch$PVersExtname]'' subdirectory of one of
191 the directories in @INC (where ''PVers'' is the
192 version of Perl you're using, as supplied in $],
193 with '.' converted to '_'), or - one of the directories in
194 @INC, or - a directory which the extensions Perl
195 library module passes to the !DynaLoader when asking it to
196 map the shareable image, or - ''Sys$Share'' or
197 ''Sys$Library''. If the shareable image isn't in any of
198 these places, you'll need to define a logical name
199 ''Extshortname'', where ''Extshortname'' is the
200 portion of the extension's name after the last ::,
201 which translates to the full file specification of the
202 shareable image.
203 !!File specifications
204
205
206 __Syntax__
207
208
209 We have tried to make Perl aware of both VMS-style and Unix-
210 style file specifications wherever possible. You may use
211 either style, or both, on the command line and in scripts,
212 but you may not combine the two styles within a single file
213 specification. VMS Perl interprets Unix
214 pathnames in much the same way as the CRTL
215 (''e.g.'' the first component of an absolute path is read
216 as the device name for the VMS file
217 specification). There are a set of functions provided in the
218 VMS::Filespec package for explicit interconversion
219 between VMS and Unix syntax; its
220 documentation provides more details.
221
222
223 Filenames are, of course, still case-insensitive. For
224 consistency, most Perl routines return filespecs using lower
225 case letters only, regardless of the case used in the
226 arguments passed to them. (This is true only when running
227 under VMS ; Perl respects the
228 case-sensitivity of OSs like Unix.)
229
230
231 We've tried to minimize the dependence of Perl library
232 modules on Unix syntax, but you may find that some of these,
233 as well as some scripts written for Unix systems, will
234 require that you use Unix syntax, since they will assume
235 that '/' is the directory separator, ''etc.'' If you find
236 instances of this in the Perl distribution itself, please
237 let us know, so we can try to work around them.
238
239
240 __Wildcard expansion__
241
242
243 File specifications containing wildcards are allowed both on
244 the command line and within Perl globs (e.g.
245 VMS syntax, the resultant filespecs will
246 follow VMS syntax; if a Unix-style filespec
247 is passed in, Unix-style filespecs will be
248 returned.
249
250
251 In both cases, VMS wildcard expansion is
252 performed. (csh-style wildcard expansion is available if you
253 use File::Glob::glob.) If the wildcard filespec
254 contains a device or directory specification, then the
255 resultant filespecs will also contain a device and
256 directory; otherwise, device and directory information are
257 removed. VMS-style resultant filespecs will contain a full
258 device and directory, while Unix-style resultant filespecs
259 will contain only as much of a directory path as was present
260 in the input filespec. For example, if your default
261 directory is Perl_Root:[[000000], the expansion of
262 [[.t]*.* will yield filespecs like
263 ``perl_root:[[t]base.dir'', while the expansion of
264 t/*/* will yield filespecs like ``t/base.dir''.
265 (This is done to match the behavior of glob expansion
266 performed by Unix shells.)
267
268
269 Similarly, the resultant filespec will contain the file
270 version only if one was present in the input
271 filespec.
272
273
274 __Pipes__
275
276
277 Input and output pipes to Perl filehandles are supported;
278 the ``file name'' is passed to lib$''spawn()'' for
279 asynchronous execution. You should be careful to close any
280 pipes you have opened in a Perl script, lest you leave any
281 ``orphaned'' subprocesses around when Perl
282 exits.
283
284
285 You may also use backticks to invoke a DCL
286 subprocess, whose output is used as the return value of the
287 expression. The string between the backticks is handled as
288 if it were the argument to the system operator (see
289 below). In this case, Perl will wait for the subprocess to
290 complete before continuing.
291 !!PERL5LIB and PERLLIB
292
293
294 The PERL5LIB and PERLLIB
295 logical names work as documented in perl, except that the
296 element separator is '' instead of ':'. The directory
297 specifications may use either VMS or Unix
298 syntax.
299 !!Command line
300
301
302 __I/O redirection and backgrounding__
303
304
305 Perl for VMS supports redirection of input
306 and output on the command line, using a subset of Bourne
307 shell syntax:
308
309
310
311 In addition, output may be piped to a subprocess, using the character ''. Anything after this character on the command line is passed to a subprocess for execution; the subprocess takes the output of Perl as its input.
312
313
314 Finally, if the command line ends with '
315
316
317 __Command line switches__
318
319
320 The following command line switches behave differently under
321 VMS than described in perlrun. Note also that
322 in order to pass uppercase switches to Perl, you need to
323 enclose them in double-quotes on the command line, since the
324 CRTL downcases all unquoted
325 strings.
326
327
328 -i
329
330
331 If the -i switch is present but no extension for a
332 backup copy is given, then inplace editing creates a new
333 version of a file; the existing copy is not deleted. (Note
334 that if an extension is given, an existing file is renamed
335 to the backup file, as is the case under other operating
336 systems, so it does not remain as a previous version under
337 the original filename.)
338
339
340 -S
341
342
343 If the -S switch is present ''and'' the script
344 name does not contain a directory, then Perl translates the
345 logical name DCL$PATH as a searchlist, using
346 each translation as a directory in which to look for the
347 script. In addition, if no file type is specified, Perl
348 looks in each directory for a file matching the name
349 specified, with a blank type, a type of ''.pl'', and a
350 type of ''.com'', in that order.
351
352
353 -u
354
355
356 The -u switch causes the VMS
357 debugger to be invoked after the Perl program is compiled,
358 but before it has run. It does not create a core dump
359 file.
360 !!Perl functions
361
362
363 As of the time this document was last revised, the following
364 Perl functions were implemented in the VMS
365 port of Perl (functions marked with * are discussed in more
366 detail below):
367
368
369 file tests*, abs, alarm, atan, backticks*, binmode*, bless,
370 caller, chdir, chmod, chown, chomp, chop, chr,
371 close, closedir, cos, crypt*, defined, delete,
372 die, do, dump*, each, endpwent, eof, eval, exec*,
373 exists, exit, exp, fileno, fork*, getc, getlogin,
374 getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
375 grep, hex, import, index, int, join, keys, kill*,
376 last, lc, lcfirst, length, local, localtime, log, m//,
377 map, mkdir, my, next, no, oct, open, opendir, ord, pack,
378 pipe, pop, pos, print, printf, push, q//, qq//, qw//,
379 qx//*, quotemeta, rand, read, readdir, redo, ref, rename,
380 require, reset, return, reverse, rewinddir, rindex,
381 rmdir, s///, scalar, seek, seekdir, select(internal),
382 select (system call)*, setpwent, shift, sin, sleep,
383 sort, splice, split, sprintf, sqrt, srand, stat,
384 study, substr, sysread, system*, syswrite, tell,
385 telldir, tie, time, times*, tr///, uc, ucfirst, umask,
386 undef, unlink*, unpack, untie, unshift, use, utime*,
387 values, vec, wait, waitpid*, wantarray, warn, write, y///
388 The following functions were not implemented in the VMS port, and calling them produces a fatal error (usually) or undefined behavior (rarely, we hope):
389
390
391 chroot, dbmclose, dbmopen, fcntl, flock,
392 getpgrp, getppid, getpriority, getgrent, getgrgid,
393 getgrnam, setgrent, endgrent, ioctl, link, lstat,
394 msgctl, msgget, msgsend, msgrcv, readlink, semctl,
395 semget, semop, setpgrp, setpriority, shmctl, shmget,
396 shmread, shmwrite, socketpair, symlink, syscall
397 The following functions are available on Perls compiled with Dec C 5.2 or greater and running VMS 7.0 or greater
398
399
400 truncate
401 The following functions may or may not be implemented, depending on what type of socket support you've built into your copy of Perl:
402
403
404 accept, bind, connect, getpeername,
405 gethostbyname, getnetbyname, getprotobyname,
406 getservbyname, gethostbyaddr, getnetbyaddr,
407 getprotobynumber, getservbyport, gethostent,
408 getnetent, getprotoent, getservent, sethostent,
409 setnetent, setprotoent, setservent, endhostent,
410 endnetent, endprotoent, endservent, getsockname,
411 getsockopt, listen, recv, select(system call)*,
412 send, setsockopt, shutdown, socket
413 File tests
414
415
416 The tests -b, -B, -c,
417 -C, -d, -e, -f,
418 -o, -M, -s, -S,
419 -t, -T, and -z work as
420 advertised. The return values for -r, -w,
421 and -x tell you whether you can actually access the
422 file; this may not reflect the UIC-based file protections.
423 Since real and effective UIC don't differ
424 under VMS , -O, -R,
425 -W, and -X are equivalent to -o,
426 -r, -w, and -x. Similarly,
427 several other tests, including -A, -g,
428 -k, -l, -p, and -u,
429 aren't particularly meaningful under VMS ,
430 and the values returned by these tests reflect whatever your
431 CRTL stat() routine does to the
432 equivalent bits in the st_mode field. Finally, -d
433 returns true if passed a device specification without an
434 explicit directory (e.g. DUA1:), as well as if
435 passed a directory.
436
437
438 Note: Some sites have reported problems when using the
439 file-access tests (-r, -w, and
440 -x) on files accessed via DEC 's
441 DFS . Specifically, since DFS
442 does not currently provide access to the extended file
443 header of files on remote volumes, attempts to examine the
444 ACL fail, and the file tests will return
445 false, with $! indicating that the file does not
446 exist. You can use stat on these files, since that
447 checks UIC-based protection only, and then manually check
448 the appropriate bits, as defined by your C compiler's
449 ''stat.h'', in the mode value it returns, if you need an
450 approximation of the file's protections.
451
452
453 backticks
454
455
456 Backticks create a subprocess, and pass the enclosed string
457 to it for execution as a DCL command. Since
458 the subprocess is created directly via lib$spawn(),
459 any valid DCL command string may be
460 specified.
461
462
463 binmode FILEHANDLE
464
465
466 The binmode operator will attempt to insure that no
467 translation of carriage control occurs on input from or
468 output to this filehandle. Since this involves reopening the
469 file and then restoring its file position indicator, if this
470 function returns FALSE , the underlying
471 filehandle may no longer point to an open file, or may point
472 to a different position in the file than before
473 binmode was called.
474
475
476 Note that binmode is generally not necessary when
477 using normal filehandles; it is provided so that you can
478 control I/O to existing record-structured files when
479 necessary. You can also use the vmsfopen function
480 in the VMS::Stdio extension to gain finer control of I/O to
481 files and devices with different record
482 structures.
483
484
485 crypt PLAINTEXT ,
486 USER
487
488
489 The crypt operator uses the
490 sys$hash_password system service to generate the
491 hashed representation of PLAINTEXT . If
492 USER is a valid username, the algorithm and
493 salt values are taken from that user's UAF
494 record. If it is not, then the preferred algorithm and a
495 salt of 0 are used. The quadword encrypted value is returned
496 as an 8-character string.
497
498
499 The value returned by crypt may be compared against
500 the encrypted password from the UAF returned
501 by the getpw* functions, in order to authenticate
502 users. If you're going to do this, remember that the
503 encrypted password in the UAF was generated
504 using uppercase username and password strings; you'll have
505 to upcase the arguments to crypt to insure that
506 you'll get the proper value:
507
508
509 sub validate_passwd {
510 my($user,$passwd) = @_;
511 my($pwdhash);
512 if ( !($pwdhash = (getpwnam($user))[[1])
513 $pwdhash ne crypt(
514
515
516 dump
517
518
519 Rather than causing Perl to abort and dump core, the
520 dump operator invokes the VMS
521 debugger. If you continue to execute the Perl program under
522 the debugger, control will be transferred to the label
523 specified as the argument to dump, or, if no label
524 was specified, back to the beginning of the program. All
525 other state of the program (''e.g.'' values of variables,
526 open file handles) are not affected by calling
527 dump.
528
529
530 exec LIST
531
532
533 The exec operator behaves in one of two different
534 ways. If called after a call to fork, it will
535 invoke the CRTL execv() routine,
536 passing its arguments to the subprocess created by
537 fork for execution. In this case, it is subject to
538 all limitations that affect execv(). (In
539 particular, this usually means that the command executed in
540 the subprocess must be an image compiled from C source code,
541 and that your options for passing file descriptors and
542 signal handlers to the subprocess are limited.)
543
544
545 If the call to exec does not follow a call to
546 fork, it will cause Perl to exit, and to invoke the
547 command given as an argument to exec via
548 lib$do_command. If the argument begins with '@' or
549 '$' (other than as part of a filespec), then it is executed
550 as a DCL command. Otherwise, the first token
551 on the command line is treated as the filespec of an image
552 to run, and an attempt is made to invoke it (using
553 ''.Exe'' and the process defaults to expand the filespec)
554 and pass the rest of exec's argument to it as
555 parameters. If the token has no file type, and matches a
556 file with null type, then an attempt is made to determine
557 whether the file is an executable image which should be
558 invoked using MCR or a text file which should be
559 passed to DCL as a command
560 procedure.
561
562
563 You can use exec in both ways within the same
564 script, as long as you call fork and exec
565 in pairs. Perl keeps track of how many times fork
566 and exec have been called, and will call the
567 CRTL execv() routine if there have
568 previously been more calls to fork than to
569 exec.
570
571
572 fork
573
574
575 The fork operator works in the same way as the
576 CRTL vfork() routine, which is quite
577 different under VMS than under Unix.
578 Specifically, while fork returns 0 after it is
579 called and the subprocess PID after
580 exec is called, in both cases the thread of
581 execution is within the parent process, so there is no
582 opportunity to perform operations in the subprocess before
583 calling exec.
584
585
586 In general, the use of fork and exec to
587 create subprocess is not recommended under
588 VMS ; wherever possible, use the
589 system operator or piped filehandles
590 instead.
591
592
593 getpwent
594
595
596 getpwnam
597
598
599 getpwuid
600
601
602 These operators obtain the information described in
603 perlfunc, if you have the privileges necessary to retrieve
604 the named user's UAF information via
605 sys$getuai. If not, then only the $name,
606 $uid, and $gid items are returned. The
607 $dir item contains the login directory in
608 VMS syntax, while the $comment item
609 contains the login directory in Unix syntax. The
610 $gcos item contains the owner field from the
611 UAF record. The $quota item is not
612 used.
613
614
615 gmtime
616
617
618 The gmtime operator will function properly if you
619 have a working CRTL gmtime()
620 routine, or if the logical name
621 SYS$TIMEZONE_DIFFERENTIAL is defined as the
622 number of seconds which must be added to UTC
623 to yield local time. (This logical name is defined
624 automatically if you are running a version of
625 VMS with built-in UTC
626 support.) If neither of these cases is true, a warning
627 message is printed, and undef is
628 returned.
629
630
631 kill
632
633
634 In most cases, kill is implemented via the
635 CRTL 's kill() function, so it will
636 behave according to that function's documentation. If you
637 send a SIGKILL , however, the
638 $DELPRC system service is called directly. This
639 insures that the target process is actually deleted, if at
640 all possible. (The CRTL 's kill()
641 function is presently implemented via $FORCEX,
642 which is ignored by supervisor-mode images like
643 DCL .)
644
645
646 Also, negative signal values don't do anything special under
647 VMS ; they're just converted to the
648 corresponding positive value.
649
650
651 qx//
652
653
654 See the entry on backticks above.
655
656
657 select (system call)
658
659
660 If Perl was not built with socket support, the system call
661 version of select is not available at all. If
662 socket support is present, then the system call version of
663 select functions only for file descriptors attached
664 to sockets. It will not provide information about regular
665 files or pipes, since the CRTL
666 select() routine does not provide this
667 functionality.
668
669
670 stat EXPR
671
672
673 Since VMS keeps track of files according to a
674 different scheme than Unix, it's not really possible to
675 represent the file's ID in the
676 st_dev and st_ino fields of a struct
677 stat. Perl tries its best, though, and the values it
678 uses are pretty unlikely to be the same for two different
679 files. We can't guarantee this, though, so caveat
680 scriptor.
681
682
683 system LIST
684
685
686 The system operator creates a subprocess, and
687 passes its arguments to the subprocess for execution as a
688 DCL command. Since the subprocess is created
689 directly via lib$spawn(), any valid
690 DCL command string may be specified. If the
691 string begins with '@', it is treated as a
692 DCL command unconditionally. Otherwise, if
693 the first token contains a character used as a delimiter in
694 file specification (e.g. : or ]), an
695 attempt is made to expand it using a default type of
696 ''.Exe'' and the process defaults, and if successful, the
697 resulting file is invoked via MCR. This allows you
698 to invoke an image directly simply by passing the file
699 specification to system, a common Unixish idiom. If
700 the token has no file type, and matches a file with null
701 type, then an attempt is made to determine whether the file
702 is an executable image which should be invoked using
703 MCR or a text file which should be passed to
704 DCL as a command procedure.
705
706
707 If LIST consists of the empty string,
708 system spawns an interactive DCL
709 subprocess, in the same fashion as typing
710 __SPAWN__ at the DCL
711 prompt.
712
713
714 Perl waits for the subprocess to complete before continuing
715 execution in the current process. As described in perlfunc,
716 the return value of system is a fake ``status''
717 which follows POSIX semantics; see the
718 description of $? in this document for more detail.
719 The actual VMS exit status of the subprocess
720 is available in $^S (as long as you haven't used
721 another Perl function that resets $? and
722 $^S in the meantime).
723
724
725 time
726
727
728 The value returned by time is the offset in seconds
729 from 01-JAN-1970 00:00:00 (just like the CRTL
730 's ''times()'' routine), in order to make life easier for
731 code coming in from the POSIX/Unix world.
732
733
734 times
735
736
737 The array returned by the times operator is divided
738 up according to the same rules the CRTL
739 times() routine. Therefore, the ``system time''
740 elements will always be 0, since there is no difference
741 between ``user time'' and ``system'' time under
742 VMS , and the time accumulated by a
743 subprocess may or may not appear separately in the ``child
744 time'' field, depending on whether times keeps track of
745 subprocesses separately. Note especially that the
746 VAXCRTL (at least) keeps track only of
747 subprocesses spawned using fork and exec; it will not
748 accumulate the times of subprocesses spawned via pipes,
749 system, or backticks.
750
751
752 unlink LIST
753
754
755 unlink will delete the highest version of a file
756 only; in order to delete all versions, you need to
757 say
758
759
760 1 while (unlink LIST);
761 You may need to make this change to scripts written for a Unix system which expect that after a call to unlink, no files with the names passed to unlink will exist. (Note: This can be changed at compile time; if you use Config and $Config{'d_unlink_all_versions'} is define, then unlink will delete all versions of a file on the first call.)
762
763
764 unlink will delete a file if at all possible, even
765 if it requires changing file protection (though it won't try
766 to change the protection of the parent directory). You can
767 tell whether you've got explicit delete access to a file by
768 using the VMS::Filespec::candelete operator. For
769 instance, in order to delete only files to which you have
770 delete access, you could say something like
771
772
773 sub safe_unlink {
774 my($file,$num);
775 foreach $file (@_) {
776 next unless VMS::Filespec::candelete($file);
777 $num += unlink $file;
778 }
779 $num;
780 }
781 (or you could just use VMS::Stdio::remove, if you've installed the VMS::Stdio extension distributed with Perl). If unlink has to change the file protection to delete the file, and you interrupt it in midstream, the file may be left intact, but with a changed ACL allowing you delete access.
782
783
784 utime LIST
785
786
787 Since ODS-2 , the VMS file
788 structure for disk files, does not keep track of access
789 times, this operator changes only the modification time of
790 the file ( VMS revision date).
791
792
793 waitpid PID ,FLAGS
794
795
796 If PID is a subprocess started by a piped
797 open() (see open), waitpid will wait for
798 that subprocess, and return its final status value. If
799 PID is a subprocess created in some other way
800 (e.g. SPAWNed before Perl was invoked), or is not a
801 subprocess of the current process, waitpid will
802 check once per second whether the process has completed, and
803 when it has, will return 0. (If PID specifies
804 a process that isn't a subprocess of the current process,
805 and you invoked Perl with the -w switch, a warning
806 will be issued.)
807
808
809 The FLAGS argument is ignored in all
810 cases.
811 !!Perl variables
812
813
814 The following VMS-specific information applies to the
815 indicated ``special'' Perl variables, in addition to the
816 general information in perlvar. Where there is a conflict,
817 this information takes precedence.
818
819
820 %ENV
821
822
823 The operation of the %ENV array depends on the
824 translation of the logical name
825 ''PERL_ENV_TABLES'' . If defined, it
826 should be a search list, each element of which specifies a
827 location for %ENV elements. If you tell Perl to
828 read or set the element $ENV{''name''},
829 then Perl uses the translations of
830 ''PERL_ENV_TABLES'' as
831 follows:
832
833
834 CRTL_ENV
835
836
837 This string tells Perl to consult the CRTL 's
838 internal environ array of key-value pairs, using
839 ''name'' as the key. In most cases, this contains only a
840 few keys, but if Perl was invoked via the C
841 exec[[lv]e() function, as is the case for
842 CGI processing by some HTTP
843 servers, then the environ array may have been
844 populated by the calling program.
845
846
847 CLISYM_[[ LOCAL ]
848
849
850 A string beginning with CLISYM_tells Perl to
851 consult the CLI 's symbol tables, using
852 ''name'' as the name of the symbol. When reading an
853 element of %ENV, the local symbol table is scanned
854 first, followed by the global symbol table.. The characters
855 following CLISYM_ are significant when an element
856 of %ENV is set or deleted: if the complete string
857 is CLISYM_LOCAL, the change is made in the local
858 symbol table; otherwise the global symbol table is
859 changed.
860
861
862 Any other string
863
864
865 If an element of ''PERL_ENV_TABLES''
866 translates to any other string, that string is used as the
867 name of a logical name table, which is consulted using
868 ''name'' as the logical name. The normal search order of
869 access modes is used.
870
871
872 ''PERL_ENV_TABLES'' is translated once
873 when Perl starts up; any changes you make while Perl is
874 running do not affect the behavior of %ENV. If
875 ''PERL_ENV_TABLES'' is not defined, then
876 Perl defaults to consulting first the logical name tables
877 specified by ''LNM$FILE_DEV'' , and then
878 the CRTL environ array.
879
880
881 In all operations on %ENV, the key string is
882 treated as if it were entirely uppercase, regardless of the
883 case actually specified in the Perl expression.
884
885
886 When an element of %ENV is read, the locations to
887 which ''PERL_ENV_TABLES'' points are
888 checked in order, and the value obtained from the first
889 successful lookup is returned. If the name of the
890 %ENV element contains a semi-colon, it and any
891 characters after it are removed. These are ignored when the
892 CRTL environ array or a
893 CLI symbol table is consulted. However, the
894 name is looked up in a logical name table, the suffix after
895 the semi-colon is treated as the translation index to be
896 used for the lookup. This lets you look up successive values
897 for search list logical names. For instance, if you
898 say
899
900
901 $ Define STORY once,upon,a,time,there,was
902 $ perl -e
903 Perl will print ONCE UPON A TIME THERE WAS, assuming, of course, that ''PERL_ENV_TABLES'' is set up so that the logical name story is found, rather than a CLI symbol or CRTL environ element with the same name.
904
905
906 When an element of %ENV is set to a defined string,
907 the corresponding definition is made in the location to
908 which the first translation of
909 ''PERL_ENV_TABLES'' points. If this causes
910 a logical name to be created, it is defined in supervisor
911 mode. (The same is done if an existing logical name was
912 defined in executive or kernel mode; an existing user or
913 supervisor mode logical name is reset to the new value.) If
914 the value is an empty string, the logical name's translation
915 is defined as a single NUL (
916 ASCII 00) character, since a logical name
917 cannot translate to a zero-length string. (This restriction
918 does not apply to CLI symbols or
919 CRTL environ values; they are set to
920 the empty string.) An element of the CRTL
921 environ array can be set only if your copy of Perl
922 knows about the CRTL 's setenv()
923 function. (This is present only in some versions of the
924 DECCRTL ; check $Config{d_setenv} to
925 see whether your copy of Perl was built with a
926 CRTL that has this function.)
927
928
929 When an element of %ENV is set to undef,
930 the element is looked up as if it were being read, and if it
931 is found, it is deleted. (An item ``deleted'' from the
932 CRTL environ array is set to the
933 empty string; this can only be done if your copy of Perl
934 knows about the CRTL setenv()
935 function.) Using delete to remove an element from
936 %ENV has a similar effect, but after the element is
937 deleted, another attempt is made to look up the element, so
938 an inner-mode logical name or a name in another location
939 will replace the logical name just deleted. In either case,
940 only the first value found searching
941 PERL_ENV_TABLES is altered. It is not
942 possible at present to define a search list logical name via
943 %ENV.
944
945
946 The element $ENV{DEFAULT} is special: when read, it
947 returns Perl's current default device and directory, and
948 when set, it resets them, regardless of the definition of
949 ''PERL_ENV_TABLES'' . It cannot be cleared
950 or deleted; attempts to do so are silently
951 ignored.
952
953
954 Note that if you want to pass on any elements of the C-local
955 environ array to a subprocess which isn't started by
956 fork/exec, or isn't running a C program, you can ``promote''
957 them to logical names in the current process, which will
958 then be inherited by all subprocesses, by
959 saying
960
961
962 foreach my $key (qw[[C-local keys you want promoted]) {
963 my $temp = $ENV{$key}; # read from C-local array
964 $ENV{$key} = $temp; # and define as logical name
965 }
966 (You can't just say $ENV{$key} = $ENV{$key}, since the Perl optimizer is smart enough to elide the expression.)
967
968
969 Don't try to clear %ENV by saying %ENV =
970 ();, it will throw a fatal error. This is equivalent to
971 doing the following from DCL:
972
973
974 DELETE/LOGICAL *
975 You can imagine how bad things would be if, for example, the SYS$MANAGER or SYS$SYSTEM logicals were deleted.
976
977
978 At present, the first time you iterate over %ENV
979 using keys, or values, you will incur a
980 time penalty as all logical names are read, in order to
981 fully populate %ENV. Subsequent iterations will not
982 reread logical names, so they won't be as slow, but they
983 also won't reflect any changes to logical name tables caused
984 by other programs.
985
986
987 You do need to be careful with the logicals representing
988 process-permanent files, such as SYS$INPUT and
989 SYS$OUTPUT. The translations for these logicals are
990 prepended with a two-byte binary value (0x1B 0x00) that
991 needs to be stripped off if you want to use it. (In previous
992 versions of Perl it wasn't possible to get the values of
993 these logicals, as the null byte acted as an end-of-string
994 marker)
995
996
997 $!
998
999
1000 The string value of $! is that returned by the
1001 CRTL 's ''strerror()'' function, so it
1002 will include the VMS message for VMS-specific
1003 errors. The numeric value of $! is the value of
1004 errno, except if errno is EVMSERR ,
1005 in which case $! contains the value of vaxc$errno.
1006 Setting $! always sets errno to the value
1007 specified. If this value is EVMSERR , it also
1008 sets vaxc$errno to 4 ( NONAME-F-NOMSG ), so
1009 that the string value of $! won't reflect the
1010 VMS error message from before $! was
1011 set.
1012
1013
1014 $^E
1015
1016
1017 This variable provides direct access to VMS
1018 status values in vaxc$errno, which are often more specific
1019 than the generic Unix-style error messages in $!.
1020 Its numeric value is the value of vaxc$errno, and its string
1021 value is the corresponding VMS message
1022 string, as retrieved by sys$''getmsg()''. Setting
1023 $^E sets vaxc$errno to the value
1024 specified.
1025
1026
1027 $?
1028
1029
1030 The ``status value'' returned in $? is synthesized
1031 from the actual exit status of the subprocess in a way that
1032 approximates POSIX wait(5) semantics,
1033 in order to allow Perl programs to portably test for
1034 successful completion of subprocesses. The low order 8 bits
1035 of $? are always 0 under VMS , since
1036 the termination status of a process may or may not have been
1037 generated by an exception. The next 8 bits are derived from
1038 the severity portion of the subprocess' exit status: if the
1039 severity was success or informational, these bits are all 0;
1040 otherwise, they contain the severity value shifted left one
1041 bit. As a result, $? will always be zero if the
1042 subprocess' exit status indicated successful completion, and
1043 non-zero if a warning or error occurred. The actual
1044 VMS exit status may be found in $^S
1045 (q.v.).
1046
1047
1048 $^S
1049
1050
1051 Under VMS , this is the 32-bit
1052 VMS status value returned by the last
1053 subprocess to complete. Unlike $?, no manipulation
1054 is done to make this look like a POSIX
1055 wait(5) value, so it may be treated as a normal
1056 VMS status value.
1057
1058
1059 $
1060
1061
1062 Setting $ for an I/O stream causes data to be
1063 flushed all the way to disk on each write (''i.e.'' not
1064 just to the underlying RMS buffers for a
1065 file). In other words, it's equivalent to calling
1066 ''fflush()'' and ''fsync()'' from C.
1067 !!Standard modules with VMS-specific differences
1068
1069
1070 __SDBM_File__
1071
1072
1073 SDBM_File works properly on VMS . It has,
1074 however, one minor difference. The database directory file
1075 created has a ''.sdbm_dir'' extension rather than a
1076 ''.dir'' extension. ''.dir'' files are
1077 VMS filesystem directory files, and using
1078 them for other purposes could cause unacceptable
1079 problems.
1080 !!Revision date
1081
1082
1083 This document was last updated on 26-Feb-2000, for Perl 5,
1084 patchlevel 6.
1085 !!AUTHOR
1086
1087
1088 Charles Bailey
1089 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.