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