1PERLVMS(1) Perl Programmers Reference Guide PERLVMS(1)
2
6 perlvms - VMS-specific documentation for Perl
7
9 Gathered below are notes describing details of Perl 5's behavior on
10 VMS. They are a supplement to the regular Perl 5 documentation, so we
11 have focussed on the ways in which Perl 5 functions differently under
12 VMS than it does under Unix, and on the interactions between Perl and
13 the rest of the operating system. We haven't tried to duplicate com‐
14 plete descriptions of Perl features from the main Perl documentation,
15 which can be found in the [.pod] subdirectory of the Perl distribution.
16 We hope these notes will save you from confusion and lost sleep when
18 writing Perl scripts on VMS. If you find we've missed something you
19 think should appear here, please don't hesitate to drop a line to
20 vmsperl@perl.org.
21
23 Directions for building and installing Perl 5 can be found in the file
24 README.vms in the main source directory of the Perl distribution..
25
27 Core Images
28 During the installation process, three Perl images are produced.
30 Miniperl.Exe is an executable image which contains all of the basic
31 functionality of Perl, but cannot take advantage of Perl extensions.
32 It is used to generate several files needed to build the complete Perl
33 and various extensions. Once you've finished installing Perl, you can
34 delete this image.
35 Most of the complete Perl resides in the shareable image PerlShr.Exe,
37 which provides a core to which the Perl executable image and all Perl
38 extensions are linked. You should place this image in Sys$Share, or
39 define the logical name PerlShr to translate to the full file specifi‐
40 cation of this image. It should be world readable. (Remember that if
41 a user has execute only access to PerlShr, VMS will treat it as if it
42 were a privileged shareable image, and will therefore require all down‐
43 stream shareable images to be INSTALLed, etc.)
44 Finally, Perl.Exe is an executable image containing the main entry
46 point for Perl, as well as some initialization code. It should be
47 placed in a public directory, and made world executable. In order to
48 run Perl with command line arguments, you should define a foreign com‐
49 mand to invoke this image.
50 Perl Extensions
52 Perl extensions are packages which provide both XS and Perl code to add
54 new functionality to perl. (XS is a meta-language which simplifies
55 writing C code which interacts with Perl, see perlxs for more details.)
56 The Perl code for an extension is treated like any other library module
57 - it's made available in your script through the appropriate "use" or
58 "require" statement, and usually defines a Perl package containing the
59 extension.
60 The portion of the extension provided by the XS code may be connected
62 to the rest of Perl in either of two ways. In the static configura‐
63 tion, the object code for the extension is linked directly into Perl‐
64 Shr.Exe, and is initialized whenever Perl is invoked. In the dynamic
65 configuration, the extension's machine code is placed into a separate
66 shareable image, which is mapped by Perl's DynaLoader when the exten‐
67 sion is "use"d or "require"d in your script. This allows you to main‐
68 tain the extension as a separate entity, at the cost of keeping track
69 of the additional shareable image. Most extensions can be set up as
70 either static or dynamic.
71 The source code for an extension usually resides in its own directory.
73 At least three files are generally provided: Extshortname.xs (where
74 Extshortname is the portion of the extension's name following the last
75 "::"), containing the XS code, Extshortname.pm, the Perl library module
76 for the extension, and Makefile.PL, a Perl script which uses the "Make‐
77 Maker" library modules supplied with Perl to generate a Descrip.MMS
78 file for the extension.
79 Installing static extensions
81 Since static extensions are incorporated directly into PerlShr.Exe,
83 you'll have to rebuild Perl to incorporate a new extension. You should
84 edit the main Descrip.MMS or Makefile you use to build Perl, adding the
85 extension's name to the "ext" macro, and the extension's object file to
86 the "extobj" macro. You'll also need to build the extension's object
87 file, either by adding dependencies to the main Descrip.MMS, or using a
88 separate Descrip.MMS for the extension. Then, rebuild PerlShr.Exe to
89 incorporate the new code.
90 Finally, you'll need to copy the extension's Perl library module to the
92 [.Extname] subdirectory under one of the directories in @INC, where
93 Extname is the name of the extension, with all "::" replaced by "."
94 (e.g. the library module for extension Foo::Bar would be copied to a
95 [.Foo.Bar] subdirectory).
96 Installing dynamic extensions
98 In general, the distributed kit for a Perl extension includes a file
100 named Makefile.PL, which is a Perl program which is used to create a
101 Descrip.MMS file which can be used to build and install the files
102 required by the extension. The kit should be unpacked into a directory
103 tree not under the main Perl source directory, and the procedure for
104 building the extension is simply
105 $ perl Makefile.PL ! Create Descrip.MMS
107 $ mmk ! Build necessary files
108 $ mmk test ! Run test code, if supplied
109 $ mmk install ! Install into public Perl tree
110 N.B. The procedure by which extensions are built and tested creates
112 several levels (at least 4) under the directory in which the exten‐
113 sion's source files live. For this reason if you are running a version
114 of VMS prior to V7.1 you shouldn't nest the source directory too deeply
115 in your directory structure lest you exceed RMS' maximum of 8 levels of
116 subdirectory in a filespec. (You can use rooted logical names to get
117 another 8 levels of nesting, if you can't place the files near the top
118 of the physical directory structure.)
119 VMS support for this process in the current release of Perl is suffi‐
121 cient to handle most extensions. However, it does not yet recognize
122 extra libraries required to build shareable images which are part of an
123 extension, so these must be added to the linker options file for the
124 extension by hand. For instance, if the PGPLOT extension to Perl
125 requires the PGPLOTSHR.EXE shareable image in order to properly link
126 the Perl extension, then the line "PGPLOTSHR/Share" must be added to
127 the linker options file PGPLOT.Opt produced during the build process
128 for the Perl extension.
129 By default, the shareable image for an extension is placed in the
131 [.lib.site_perl.autoArch.Extname] directory of the installed Perl
132 directory tree (where Arch is VMS_VAX or VMS_AXP, and Extname is the
133 name of the extension, with each "::" translated to "."). (See the
134 MakeMaker documentation for more details on installation options for
135 extensions.) However, it can be manually placed in any of several
136 locations:
137 · the [.Lib.Auto.Arch$PVersExtname] subdirectory of one of the direc‐
139 tories in @INC (where PVers is the version of Perl you're using, as
140 supplied in $], with '.' converted to '_'), or
141 · one of the directories in @INC, or
143 · a directory which the extensions Perl library module passes to the
145 DynaLoader when asking it to map the shareable image, or
146 · Sys$Share or Sys$Library.
148 If the shareable image isn't in any of these places, you'll need to
150 define a logical name Extshortname, where Extshortname is the portion
151 of the extension's name after the last "::", which translates to the
152 full file specification of the shareable image.
153
155 Syntax
156 We have tried to make Perl aware of both VMS-style and Unix- style file
158 specifications wherever possible. You may use either style, or both,
159 on the command line and in scripts, but you may not combine the two
160 styles within a single file specification. VMS Perl interprets Unix
161 pathnames in much the same way as the CRTL (e.g. the first component of
162 an absolute path is read as the device name for the VMS file specifica‐
163 tion). There are a set of functions provided in the "VMS::Filespec"
164 package for explicit interconversion between VMS and Unix syntax; its
165 documentation provides more details.
166 Filenames are, of course, still case-insensitive. For consistency,
168 most Perl routines return filespecs using lower case letters only,
169 regardless of the case used in the arguments passed to them. (This is
170 true only when running under VMS; Perl respects the case-sensitivity
171 of OSs like Unix.)
172 We've tried to minimize the dependence of Perl library modules on Unix
174 syntax, but you may find that some of these, as well as some scripts
175 written for Unix systems, will require that you use Unix syntax, since
176 they will assume that '/' is the directory separator, etc. If you find
177 instances of this in the Perl distribution itself, please let us know,
178 so we can try to work around them.
179 Wildcard expansion
181 File specifications containing wildcards are allowed both on the com‐
183 mand line and within Perl globs (e.g. "<*.c>"). If the wildcard file‐
184 spec uses VMS syntax, the resultant filespecs will follow VMS syntax;
185 if a Unix-style filespec is passed in, Unix-style filespecs will be
186 returned. Similar to the behavior of wildcard globbing for a Unix
187 shell, one can escape command line wildcards with double quotation
188 marks """ around a perl program command line argument. However, owing
189 to the stripping of """ characters carried out by the C handling of
190 argv you will need to escape a construct such as this one (in a direc‐
191 tory containing the files PERL.C, PERL.EXE, PERL.H, and PERL.OBJ):
192 $ perl -e "print join(' ',@ARGV)" perl.*
194 perl.c perl.exe perl.h perl.obj
195 in the following triple quoted manner:
197 $ perl -e "print join(' ',@ARGV)" """perl.*"""
199 perl.*
200 In both the case of unquoted command line arguments or in calls to
202 "glob()" VMS wildcard expansion is performed. (csh-style wildcard
203 expansion is available if you use "File::Glob::glob".) If the wildcard
204 filespec contains a device or directory specification, then the resul‐
205 tant filespecs will also contain a device and directory; otherwise,
206 device and directory information are removed. VMS-style resultant
207 filespecs will contain a full device and directory, while Unix-style
208 resultant filespecs will contain only as much of a directory path as
209 was present in the input filespec. For example, if your default direc‐
210 tory is Perl_Root:[000000], the expansion of "[.t]*.*" will yield file‐
211 specs like "perl_root:[t]base.dir", while the expansion of "t/*/*"
212 will yield filespecs like "t/base.dir". (This is done to match the
213 behavior of glob expansion performed by Unix shells.)
214 Similarly, the resultant filespec will contain the file version only if
216 one was present in the input filespec.
217 Pipes
219 Input and output pipes to Perl filehandles are supported; the "file
221 name" is passed to lib$spawn() for asynchronous execution. You should
222 be careful to close any pipes you have opened in a Perl script, lest
223 you leave any "orphaned" subprocesses around when Perl exits.
224 You may also use backticks to invoke a DCL subprocess, whose output is
226 used as the return value of the expression. The string between the
227 backticks is handled as if it were the argument to the "system" opera‐
228 tor (see below). In this case, Perl will wait for the subprocess to
229 complete before continuing.
230 The mailbox (MBX) that perl can create to communicate with a pipe
232 defaults to a buffer size of 512. The default buffer size is
233 adjustable via the logical name PERL_MBX_SIZE provided that the value
234 falls between 128 and the SYSGEN parameter MAXBUF inclusive. For exam‐
235 ple, to double the MBX size from the default within a Perl program, use
236 "$ENV{'PERL_MBX_SIZE'} = 1024;" and then open and use pipe constructs.
237 An alternative would be to issue the command:
238 $ Define PERL_MBX_SIZE 1024
240 before running your wide record pipe program. A larger value may
242 improve performance at the expense of the BYTLM UAF quota.
243
245 The PERL5LIB and PERLLIB logical names work as documented in perl,
246 except that the element separator is '⎪' instead of ':'. The directory
247 specifications may use either VMS or Unix syntax.
248
250 I/O redirection and backgrounding
251 Perl for VMS supports redirection of input and output on the command
253 line, using a subset of Bourne shell syntax:
254 · "<file" reads stdin from "file",
256 · ">file" writes stdout to "file",
258 · ">>file" appends stdout to "file",
260 · "2>file" writes stderr to "file",
262 · "2>>file" appends stderr to "file", and
264 · "2>&1" redirects stderr to stdout.
266 In addition, output may be piped to a subprocess, using the character
268 '⎪'. Anything after this character on the command line is passed to a
269 subprocess for execution; the subprocess takes the output of Perl as
270 its input.
271 Finally, if the command line ends with '&', the entire command is run
273 in the background as an asynchronous subprocess.
274 Command line switches
276 The following command line switches behave differently under VMS than
278 described in perlrun. Note also that in order to pass uppercase
279 switches to Perl, you need to enclose them in double-quotes on the com‐
280 mand line, since the CRTL downcases all unquoted strings.
281 -i If the "-i" switch is present but no extension for a backup copy is
283 given, then inplace editing creates a new version of a file; the
284 existing copy is not deleted. (Note that if an extension is given,
285 an existing file is renamed to the backup file, as is the case
286 under other operating systems, so it does not remain as a previous
287 version under the original filename.)
288 -S If the "-S" or "-"S"" switch is present and the script name does
290 not contain a directory, then Perl translates the logical name
291 DCL$PATH as a searchlist, using each translation as a directory in
292 which to look for the script. In addition, if no file type is
293 specified, Perl looks in each directory for a file matching the
294 name specified, with a blank type, a type of .pl, and a type of
295 .com, in that order.
296 -u The "-u" switch causes the VMS debugger to be invoked after the
298 Perl program is compiled, but before it has run. It does not cre‐
299 ate a core dump file.
300
302 As of the time this document was last revised, the following Perl func‐
303 tions were implemented in the VMS port of Perl (functions marked with *
304 are discussed in more detail below):
305 file tests*, abs, alarm, atan, backticks*, binmode*, bless,
307 caller, chdir, chmod, chown, chomp, chop, chr,
308 close, closedir, cos, crypt*, defined, delete,
309 die, do, dump*, each, endpwent, eof, eval, exec*,
310 exists, exit, exp, fileno, getc, getlogin, getppid,
311 getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
312 grep, hex, import, index, int, join, keys, kill*,
313 last, lc, lcfirst, length, local, localtime, log, m//,
314 map, mkdir, my, next, no, oct, open, opendir, ord, pack,
315 pipe, pop, pos, print, printf, push, q//, qq//, qw//,
316 qx//*, quotemeta, rand, read, readdir, redo, ref, rename,
317 require, reset, return, reverse, rewinddir, rindex,
318 rmdir, s///, scalar, seek, seekdir, select(internal),
319 select (system call)*, setpwent, shift, sin, sleep,
320 sort, splice, split, sprintf, sqrt, srand, stat,
321 study, substr, sysread, system*, syswrite, tell,
322 telldir, tie, time, times*, tr///, uc, ucfirst, umask,
323 undef, unlink*, unpack, untie, unshift, use, utime*,
324 values, vec, wait, waitpid*, wantarray, warn, write, y///
325 The following functions were not implemented in the VMS port, and call‐
327 ing them produces a fatal error (usually) or undefined behavior
328 (rarely, we hope):
329 chroot, dbmclose, dbmopen, flock, fork*,
331 getpgrp, getpriority, getgrent, getgrgid,
332 getgrnam, setgrent, endgrent, ioctl, link, lstat,
333 msgctl, msgget, msgsend, msgrcv, readlink, semctl,
334 semget, semop, setpgrp, setpriority, shmctl, shmget,
335 shmread, shmwrite, socketpair, symlink, syscall
336 The following functions are available on Perls compiled with Dec C 5.2
338 or greater and running VMS 7.0 or greater:
339 truncate
341 The following functions are available on Perls built on VMS 7.2 or
343 greater:
344 fcntl (without locking)
346 The following functions may or may not be implemented, depending on
348 what type of socket support you've built into your copy of Perl:
349 accept, bind, connect, getpeername,
351 gethostbyname, getnetbyname, getprotobyname,
352 getservbyname, gethostbyaddr, getnetbyaddr,
353 getprotobynumber, getservbyport, gethostent,
354 getnetent, getprotoent, getservent, sethostent,
355 setnetent, setprotoent, setservent, endhostent,
356 endnetent, endprotoent, endservent, getsockname,
357 getsockopt, listen, recv, select(system call)*,
358 send, setsockopt, shutdown, socket
359 File tests
361 The tests "-b", "-B", "-c", "-C", "-d", "-e", "-f", "-o", "-M",
362 "-s", "-S", "-t", "-T", and "-z" work as advertised. The return
363 values for "-r", "-w", and "-x" tell you whether you can actually
364 access the file; this may not reflect the UIC-based file protec‐
365 tions. Since real and effective UIC don't differ under VMS, "-O",
366 "-R", "-W", and "-X" are equivalent to "-o", "-r", "-w", and "-x".
367 Similarly, several other tests, including "-A", "-g", "-k", "-l",
368 "-p", and "-u", aren't particularly meaningful under VMS, and the
369 values returned by these tests reflect whatever your CRTL "stat()"
370 routine does to the equivalent bits in the st_mode field. Finally,
371 "-d" returns true if passed a device specification without an
372 explicit directory (e.g. "DUA1:"), as well as if passed a direc‐
373 tory.
374 Note: Some sites have reported problems when using the file-access
376 tests ("-r", "-w", and "-x") on files accessed via DEC's DFS.
377 Specifically, since DFS does not currently provide access to the
378 extended file header of files on remote volumes, attempts to exam‐
379 ine the ACL fail, and the file tests will return false, with $!
380 indicating that the file does not exist. You can use "stat" on
381 these files, since that checks UIC-based protection only, and then
382 manually check the appropriate bits, as defined by your C com‐
383 piler's stat.h, in the mode value it returns, if you need an
384 approximation of the file's protections.
385 backticks
387 Backticks create a subprocess, and pass the enclosed string to it
388 for execution as a DCL command. Since the subprocess is created
389 directly via "lib$spawn()", any valid DCL command string may be
390 specified.
391 binmode FILEHANDLE
393 The "binmode" operator will attempt to insure that no translation
394 of carriage control occurs on input from or output to this filehan‐
395 dle. Since this involves reopening the file and then restoring its
396 file position indicator, if this function returns FALSE, the under‐
397 lying filehandle may no longer point to an open file, or may point
398 to a different position in the file than before "binmode" was
399 called.
400 Note that "binmode" is generally not necessary when using normal
402 filehandles; it is provided so that you can control I/O to existing
403 record-structured files when necessary. You can also use the "vms‐
404 fopen" function in the VMS::Stdio extension to gain finer control
405 of I/O to files and devices with different record structures.
406 crypt PLAINTEXT, USER
408 The "crypt" operator uses the "sys$hash_password" system service to
409 generate the hashed representation of PLAINTEXT. If USER is a
410 valid username, the algorithm and salt values are taken from that
411 user's UAF record. If it is not, then the preferred algorithm and
412 a salt of 0 are used. The quadword encrypted value is returned as
413 an 8-character string.
414 The value returned by "crypt" may be compared against the encrypted
416 password from the UAF returned by the "getpw*" functions, in order
417 to authenticate users. If you're going to do this, remember that
418 the encrypted password in the UAF was generated using uppercase
419 username and password strings; you'll have to upcase the arguments
420 to "crypt" to insure that you'll get the proper value:
421 sub validate_passwd {
423 my($user,$passwd) = @_;
424 my($pwdhash);
425 if ( !($pwdhash = (getpwnam($user))[1]) ⎪⎪
426 $pwdhash ne crypt("\U$passwd","\U$name") ) {
427 intruder_alert($name);
428 }
429 return 1;
430 }
431 dump
433 Rather than causing Perl to abort and dump core, the "dump" opera‐
434 tor invokes the VMS debugger. If you continue to execute the Perl
435 program under the debugger, control will be transferred to the
436 label specified as the argument to "dump", or, if no label was
437 specified, back to the beginning of the program. All other state
438 of the program (e.g. values of variables, open file handles) are
439 not affected by calling "dump".
440 exec LIST
442 A call to "exec" will cause Perl to exit, and to invoke the command
443 given as an argument to "exec" via "lib$do_command". If the argu‐
444 ment begins with '@' or '$' (other than as part of a filespec),
445 then it is executed as a DCL command. Otherwise, the first token
446 on the command line is treated as the filespec of an image to run,
447 and an attempt is made to invoke it (using .Exe and the process
448 defaults to expand the filespec) and pass the rest of "exec"'s
449 argument to it as parameters. If the token has no file type, and
450 matches a file with null type, then an attempt is made to determine
451 whether the file is an executable image which should be invoked
452 using "MCR" or a text file which should be passed to DCL as a com‐
453 mand procedure.
454 fork
456 While in principle the "fork" operator could be implemented via
457 (and with the same rather severe limitations as) the CRTL "vfork()"
458 routine, and while some internal support to do just that is in
459 place, the implementation has never been completed, making "fork"
460 currently unavailable. A true kernel "fork()" is expected in a
461 future version of VMS, and the pseudo-fork based on interpreter
462 threads may be available in a future version of Perl on VMS (see
463 perlfork). In the meantime, use "system", backticks, or piped
464 filehandles to create subprocesses.
465 getpwent
467 getpwnam
468 getpwuid
469 These operators obtain the information described in perlfunc, if
470 you have the privileges necessary to retrieve the named user's UAF
471 information via "sys$getuai". If not, then only the $name, $uid,
472 and $gid items are returned. The $dir item contains the login
473 directory in VMS syntax, while the $comment item contains the login
474 directory in Unix syntax. The $gcos item contains the owner field
475 from the UAF record. The $quota item is not used.
476 gmtime
478 The "gmtime" operator will function properly if you have a working
479 CRTL "gmtime()" routine, or if the logical name SYS$TIMEZONE_DIF‐
480 FERENTIAL is defined as the number of seconds which must be added
481 to UTC to yield local time. (This logical name is defined automat‐
482 ically if you are running a version of VMS with built-in UTC sup‐
483 port.) If neither of these cases is true, a warning message is
484 printed, and "undef" is returned.
485 kill
487 In most cases, "kill" is implemented via the CRTL's "kill()" func‐
488 tion, so it will behave according to that function's documentation.
489 If you send a SIGKILL, however, the $DELPRC system service is
490 called directly. This insures that the target process is actually
491 deleted, if at all possible. (The CRTL's "kill()" function is
492 presently implemented via $FORCEX, which is ignored by supervisor-
493 mode images like DCL.)
494 Also, negative signal values don't do anything special under VMS;
496 they're just converted to the corresponding positive value.
497 qx//
499 See the entry on "backticks" above.
500 select (system call)
502 If Perl was not built with socket support, the system call version
503 of "select" is not available at all. If socket support is present,
504 then the system call version of "select" functions only for file
505 descriptors attached to sockets. It will not provide information
506 about regular files or pipes, since the CRTL "select()" routine
507 does not provide this functionality.
508 stat EXPR
510 Since VMS keeps track of files according to a different scheme than
511 Unix, it's not really possible to represent the file's ID in the
512 "st_dev" and "st_ino" fields of a "struct stat". Perl tries its
513 best, though, and the values it uses are pretty unlikely to be the
514 same for two different files. We can't guarantee this, though, so
515 caveat scriptor.
516 system LIST
518 The "system" operator creates a subprocess, and passes its argu‐
519 ments to the subprocess for execution as a DCL command. Since the
520 subprocess is created directly via "lib$spawn()", any valid DCL
521 command string may be specified. If the string begins with '@', it
522 is treated as a DCL command unconditionally. Otherwise, if the
523 first token contains a character used as a delimiter in file speci‐
524 fication (e.g. ":" or "]"), an attempt is made to expand it using
525 a default type of .Exe and the process defaults, and if successful,
526 the resulting file is invoked via "MCR". This allows you to invoke
527 an image directly simply by passing the file specification to "sys‐
528 tem", a common Unixish idiom. If the token has no file type, and
529 matches a file with null type, then an attempt is made to determine
530 whether the file is an executable image which should be invoked
531 using "MCR" or a text file which should be passed to DCL as a com‐
532 mand procedure.
533 If LIST consists of the empty string, "system" spawns an interac‐
535 tive DCL subprocess, in the same fashion as typing SPAWN at the DCL
536 prompt.
537 Perl waits for the subprocess to complete before continuing execu‐
539 tion in the current process. As described in perlfunc, the return
540 value of "system" is a fake "status" which follows POSIX semantics
541 unless the pragma "use vmsish 'status'" is in effect; see the
542 description of $? in this document for more detail.
543 time
545 The value returned by "time" is the offset in seconds from
546 01-JAN-1970 00:00:00 (just like the CRTL's times() routine), in
547 order to make life easier for code coming in from the POSIX/Unix
548 world.
549 times
551 The array returned by the "times" operator is divided up according
552 to the same rules the CRTL "times()" routine. Therefore, the "sys‐
553 tem time" elements will always be 0, since there is no difference
554 between "user time" and "system" time under VMS, and the time accu‐
555 mulated by a subprocess may or may not appear separately in the
556 "child time" field, depending on whether times keeps track of sub‐
557 processes separately. Note especially that the VAXCRTL (at least)
558 keeps track only of subprocesses spawned using fork and exec; it
559 will not accumulate the times of subprocesses spawned via pipes,
560 system, or backticks.
561 unlink LIST
563 "unlink" will delete the highest version of a file only; in order
564 to delete all versions, you need to say
565 1 while unlink LIST;
567 You may need to make this change to scripts written for a Unix sys‐
569 tem which expect that after a call to "unlink", no files with the
570 names passed to "unlink" will exist. (Note: This can be changed at
571 compile time; if you "use Config" and $Config{'d_unlink_all_ver‐
572 sions'} is "define", then "unlink" will delete all versions of a
573 file on the first call.)
574 "unlink" will delete a file if at all possible, even if it requires
576 changing file protection (though it won't try to change the protec‐
577 tion of the parent directory). You can tell whether you've got
578 explicit delete access to a file by using the "VMS::Filespec::can‐
579 delete" operator. For instance, in order to delete only files to
580 which you have delete access, you could say something like
581 sub safe_unlink {
583 my($file,$num);
584 foreach $file (@_) {
585 next unless VMS::Filespec::candelete($file);
586 $num += unlink $file;
587 }
588 $num;
589 }
590 (or you could just use "VMS::Stdio::remove", if you've installed
592 the VMS::Stdio extension distributed with Perl). If "unlink" has to
593 change the file protection to delete the file, and you interrupt it
594 in midstream, the file may be left intact, but with a changed ACL
595 allowing you delete access.
596 utime LIST
598 Since ODS-2, the VMS file structure for disk files, does not keep
599 track of access times, this operator changes only the modification
600 time of the file (VMS revision date).
601 waitpid PID,FLAGS
603 If PID is a subprocess started by a piped "open()" (see open),
604 "waitpid" will wait for that subprocess, and return its final sta‐
605 tus value in $?. If PID is a subprocess created in some other way
606 (e.g. SPAWNed before Perl was invoked), "waitpid" will simply
607 check once per second whether the process has completed, and return
608 when it has. (If PID specifies a process that isn't a subprocess
609 of the current process, and you invoked Perl with the "-w" switch,
610 a warning will be issued.)
611 Returns PID on success, -1 on error. The FLAGS argument is ignored
613 in all cases.
614
616 The following VMS-specific information applies to the indicated "spe‐
617 cial" Perl variables, in addition to the general information in perl‐
618 var. Where there is a conflict, this information takes precedence.
619 %ENV
621 The operation of the %ENV array depends on the translation of the
622 logical name PERL_ENV_TABLES. If defined, it should be a search
623 list, each element of which specifies a location for %ENV elements.
624 If you tell Perl to read or set the element "$ENV{"name"}", then
625 Perl uses the translations of PERL_ENV_TABLES as follows:
626 CRTL_ENV
628 This string tells Perl to consult the CRTL's internal "environ"
629 array of key-value pairs, using name as the key. In most
630 cases, this contains only a few keys, but if Perl was invoked
631 via the C "exec[lv]e()" function, as is the case for CGI pro‐
632 cessing by some HTTP servers, then the "environ" array may have
633 been populated by the calling program.
634 CLISYM_[LOCAL]
636 A string beginning with "CLISYM_"tells Perl to consult the
637 CLI's symbol tables, using name as the name of the symbol.
638 When reading an element of %ENV, the local symbol table is
639 scanned first, followed by the global symbol table.. The char‐
640 acters following "CLISYM_" are significant when an element of
641 %ENV is set or deleted: if the complete string is
642 "CLISYM_LOCAL", the change is made in the local symbol table;
643 otherwise the global symbol table is changed.
644 Any other string
646 If an element of PERL_ENV_TABLES translates to any other
647 string, that string is used as the name of a logical name ta‐
648 ble, which is consulted using name as the logical name. The
649 normal search order of access modes is used.
650 PERL_ENV_TABLES is translated once when Perl starts up; any changes
652 you make while Perl is running do not affect the behavior of %ENV.
653 If PERL_ENV_TABLES is not defined, then Perl defaults to consulting
654 first the logical name tables specified by LNM$FILE_DEV, and then
655 the CRTL "environ" array.
656 In all operations on %ENV, the key string is treated as if it were
658 entirely uppercase, regardless of the case actually specified in
659 the Perl expression.
660 When an element of %ENV is read, the locations to which
662 PERL_ENV_TABLES points are checked in order, and the value obtained
663 from the first successful lookup is returned. If the name of the
664 %ENV element contains a semi-colon, it and any characters after it
665 are removed. These are ignored when the CRTL "environ" array or a
666 CLI symbol table is consulted. However, the name is looked up in a
667 logical name table, the suffix after the semi-colon is treated as
668 the translation index to be used for the lookup. This lets you
669 look up successive values for search list logical names. For
670 instance, if you say
671 $ Define STORY once,upon,a,time,there,was
673 $ perl -e "for ($i = 0; $i <= 6; $i++) " -
674 _$ -e "{ print $ENV{'story;'.$i},' '}"
675 Perl will print "ONCE UPON A TIME THERE WAS", assuming, of course,
677 that PERL_ENV_TABLES is set up so that the logical name "story" is
678 found, rather than a CLI symbol or CRTL "environ" element with the
679 same name.
680 When an element of %ENV is set to a defined string, the correspond‐
682 ing definition is made in the location to which the first transla‐
683 tion of PERL_ENV_TABLES points. If this causes a logical name to
684 be created, it is defined in supervisor mode. (The same is done if
685 an existing logical name was defined in executive or kernel mode;
686 an existing user or supervisor mode logical name is reset to the
687 new value.) If the value is an empty string, the logical name's
688 translation is defined as a single NUL (ASCII 00) character, since
689 a logical name cannot translate to a zero-length string. (This
690 restriction does not apply to CLI symbols or CRTL "environ" values;
691 they are set to the empty string.) An element of the CRTL "envi‐
692 ron" array can be set only if your copy of Perl knows about the
693 CRTL's "setenv()" function. (This is present only in some versions
694 of the DECCRTL; check $Config{d_setenv} to see whether your copy of
695 Perl was built with a CRTL that has this function.)
696 When an element of %ENV is set to "undef", the element is looked up
698 as if it were being read, and if it is found, it is deleted. (An
699 item "deleted" from the CRTL "environ" array is set to the empty
700 string; this can only be done if your copy of Perl knows about the
701 CRTL "setenv()" function.) Using "delete" to remove an element
702 from %ENV has a similar effect, but after the element is deleted,
703 another attempt is made to look up the element, so an inner-mode
704 logical name or a name in another location will replace the logical
705 name just deleted. In either case, only the first value found
706 searching PERL_ENV_TABLES is altered. It is not possible at
707 present to define a search list logical name via %ENV.
708 The element $ENV{DEFAULT} is special: when read, it returns Perl's
710 current default device and directory, and when set, it resets them,
711 regardless of the definition of PERL_ENV_TABLES. It cannot be
712 cleared or deleted; attempts to do so are silently ignored.
713 Note that if you want to pass on any elements of the C-local envi‐
715 ron array to a subprocess which isn't started by fork/exec, or
716 isn't running a C program, you can "promote" them to logical names
717 in the current process, which will then be inherited by all subpro‐
718 cesses, by saying
719 foreach my $key (qw[C-local keys you want promoted]) {
721 my $temp = $ENV{$key}; # read from C-local array
722 $ENV{$key} = $temp; # and define as logical name
723 }
724 (You can't just say $ENV{$key} = $ENV{$key}, since the Perl opti‐
726 mizer is smart enough to elide the expression.)
727 Don't try to clear %ENV by saying "%ENV = ();", it will throw a
729 fatal error. This is equivalent to doing the following from DCL:
730 DELETE/LOGICAL *
732 You can imagine how bad things would be if, for example, the
734 SYS$MANAGER or SYS$SYSTEM logicals were deleted.
735 At present, the first time you iterate over %ENV using "keys", or
737 "values", you will incur a time penalty as all logical names are
738 read, in order to fully populate %ENV. Subsequent iterations will
739 not reread logical names, so they won't be as slow, but they also
740 won't reflect any changes to logical name tables caused by other
741 programs.
742 You do need to be careful with the logicals representing process-
744 permanent files, such as "SYS$INPUT" and "SYS$OUTPUT". The trans‐
745 lations for these logicals are prepended with a two-byte binary
746 value (0x1B 0x00) that needs to be stripped off if you want to use
747 it. (In previous versions of Perl it wasn't possible to get the
748 values of these logicals, as the null byte acted as an end-of-
749 string marker)
750 $! The string value of $! is that returned by the CRTL's strerror()
752 function, so it will include the VMS message for VMS-specific
753 errors. The numeric value of $! is the value of "errno", except if
754 errno is EVMSERR, in which case $! contains the value of
755 vaxc$errno. Setting $! always sets errno to the value specified.
756 If this value is EVMSERR, it also sets vaxc$errno to 4 (NO‐
757 NAME-F-NOMSG), so that the string value of $! won't reflect the VMS
758 error message from before $! was set.
759 $^E This variable provides direct access to VMS status values in
761 vaxc$errno, which are often more specific than the generic Unix-
762 style error messages in $!. Its numeric value is the value of
763 vaxc$errno, and its string value is the corresponding VMS message
764 string, as retrieved by sys$getmsg(). Setting $^E sets vaxc$errno
765 to the value specified.
766 $? The "status value" returned in $? is synthesized from the actual
768 exit status of the subprocess in a way that approximates POSIX
769 wait(5) semantics, in order to allow Perl programs to portably test
770 for successful completion of subprocesses. The low order 8 bits of
771 $? are always 0 under VMS, since the termination status of a
772 process may or may not have been generated by an exception. The
773 next 8 bits are derived from the severity portion of the subpro‐
774 cess' exit status: if the severity was success or informational,
775 these bits are all 0; if the severity was warning, they contain a
776 value of 1; if the severity was error or fatal error, they contain
777 the actual severity bits, which turns out to be a value of 2 for
778 error and 4 for fatal error.
779 As a result, $? will always be zero if the subprocess' exit status
781 indicated successful completion, and non-zero if a warning or error
782 occurred. Conversely, when setting $? in an END block, an attempt
783 is made to convert the POSIX value into a native status intelligi‐
784 ble to the operating system upon exiting Perl. What this boils
785 down to is that setting $? to zero results in the generic success
786 value SS$_NORMAL, and setting $? to a non-zero value results in the
787 generic failure status SS$_ABORT. See also "exit" in perlport.
788 The pragma "use vmsish 'status'" makes $? reflect the actual VMS
790 exit status instead of the default emulation of POSIX status
791 described above. This pragma also disables the conversion of non-
792 zero values to SS$_ABORT when setting $? in an END block (but zero
793 will still be converted to SS$_NORMAL).
794 $⎪ Setting $⎪ for an I/O stream causes data to be flushed all the way
796 to disk on each write (i.e. not just to the underlying RMS buffers
797 for a file). In other words, it's equivalent to calling fflush()
798 and fsync() from C.
799
801 SDBM_File
802 SDBM_File works properly on VMS. It has, however, one minor difference.
804 The database directory file created has a .sdbm_dir extension rather
805 than a .dir extension. .dir files are VMS filesystem directory files,
806 and using them for other purposes could cause unacceptable problems.
807
809 This document was last updated on 01-May-2002, for Perl 5, patchlevel
810 8.
811
813 Charles Bailey bailey@cor.newman.upenn.edu Craig Berry craig‐
814 berry@mac.com Dan Sugalski dan@sidhe.org
815perl v5.8.8 2006-01-07 PERLVMS(1)