| 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@perl.org. |
| 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 if you are running a version of VMS prior |
| 125 | to V7.1 you shouldn't nest the source directory |
| 126 | too deeply in your directory structure lest you exceed RMS' |
| 127 | maximum of 8 levels of subdirectory in a filespec. (You |
| 128 | can use rooted logical names to get another 8 levels of |
| 129 | nesting, if you can't place the files near the top of |
| 130 | the physical directory structure.) |
| 131 | |
| 132 | VMS support for this process in the current release of Perl |
| 133 | is sufficient to handle most extensions. However, it does |
| 134 | not yet recognize extra libraries required to build shareable |
| 135 | images which are part of an extension, so these must be added |
| 136 | to the linker options file for the extension by hand. For |
| 137 | instance, if the F<PGPLOT> extension to Perl requires the |
| 138 | F<PGPLOTSHR.EXE> shareable image in order to properly link |
| 139 | the Perl extension, then the line C<PGPLOTSHR/Share> must |
| 140 | be added to the linker options file F<PGPLOT.Opt> produced |
| 141 | during the build process for the Perl extension. |
| 142 | |
| 143 | By default, the shareable image for an extension is placed in |
| 144 | the F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the |
| 145 | installed Perl directory tree (where I<Arch> is F<VMS_VAX> or |
| 146 | F<VMS_AXP>, and I<Extname> is the name of the extension, with |
| 147 | each C<::> translated to C<.>). (See the MakeMaker documentation |
| 148 | for more details on installation options for extensions.) |
| 149 | However, it can be manually placed in any of several locations: |
| 150 | |
| 151 | =over 4 |
| 152 | |
| 153 | =item * |
| 154 | |
| 155 | the F<[.Lib.Auto.>I<Arch>I<$PVers>I<Extname>F<]> subdirectory |
| 156 | of one of the directories in C<@INC> (where I<PVers> |
| 157 | is the version of Perl you're using, as supplied in C<$]>, |
| 158 | with '.' converted to '_'), or |
| 159 | |
| 160 | =item * |
| 161 | |
| 162 | one of the directories in C<@INC>, or |
| 163 | |
| 164 | =item * |
| 165 | |
| 166 | a directory which the extensions Perl library module |
| 167 | passes to the DynaLoader when asking it to map |
| 168 | the shareable image, or |
| 169 | |
| 170 | =item * |
| 171 | |
| 172 | F<Sys$Share> or F<Sys$Library>. |
| 173 | |
| 174 | =back |
| 175 | |
| 176 | If the shareable image isn't in any of these places, you'll need |
| 177 | to define a logical name I<Extshortname>, where I<Extshortname> |
| 178 | is the portion of the extension's name after the last C<::>, which |
| 179 | translates to the full file specification of the shareable image. |
| 180 | |
| 181 | =head1 File specifications |
| 182 | |
| 183 | =head2 Syntax |
| 184 | |
| 185 | We have tried to make Perl aware of both VMS-style and Unix-style file |
| 186 | specifications wherever possible. You may use either style, or both, |
| 187 | on the command line and in scripts, but you may not combine the two |
| 188 | styles within a single file specification. VMS Perl interprets Unix |
| 189 | pathnames in much the same way as the CRTL (I<e.g.> the first component |
| 190 | of an absolute path is read as the device name for the VMS file |
| 191 | specification). There are a set of functions provided in the |
| 192 | C<VMS::Filespec> package for explicit interconversion between VMS and |
| 193 | Unix syntax; its documentation provides more details. |
| 194 | |
| 195 | We've tried to minimize the dependence of Perl library |
| 196 | modules on Unix syntax, but you may find that some of these, |
| 197 | as well as some scripts written for Unix systems, will |
| 198 | require that you use Unix syntax, since they will assume that |
| 199 | '/' is the directory separator, I<etc.> If you find instances |
| 200 | of this in the Perl distribution itself, please let us know, |
| 201 | so we can try to work around them. |
| 202 | |
| 203 | Also when working on Perl programs on VMS, if you need a syntax |
| 204 | in a specific operating system format, then you need either to |
| 205 | check the appropriate DECC$ feature logical, or call a conversion |
| 206 | routine to force it to that format. |
| 207 | |
| 208 | The feature logical name DECC$FILENAME_UNIX_REPORT modifies traditional |
| 209 | Perl behavior in the conversion of file specifications from Unix to VMS |
| 210 | format in order to follow the extended character handling rules now |
| 211 | expected by the CRTL. Specifically, when this feature is in effect, the |
| 212 | C<./.../> in a Unix path is now translated to C<[.^.^.^.]> instead of |
| 213 | the traditional VMS C<[...]>. To be compatible with what MakeMaker |
| 214 | expects, if a VMS path cannot be translated to a Unix path, it is |
| 215 | passed through unchanged, so C<unixify("[...]")> will return C<[...]>. |
| 216 | |
| 217 | The handling of extended characters is largely complete in the |
| 218 | VMS-specific C infrastructure of Perl, but more work is still needed to |
| 219 | fully support extended syntax filenames in several core modules. In |
| 220 | particular, at this writing PathTools has only partial support for |
| 221 | directories containing some extended characters. |
| 222 | |
| 223 | There are several ambiguous cases where a conversion routine cannot |
| 224 | determine whether an input filename is in Unix format or in VMS format, |
| 225 | since now both VMS and Unix file specifications may have characters in |
| 226 | them that could be mistaken for syntax delimiters of the other type. So |
| 227 | some pathnames simply cannot be used in a mode that allows either type |
| 228 | of pathname to be present. Perl will tend to assume that an ambiguous |
| 229 | filename is in Unix format. |
| 230 | |
| 231 | Allowing "." as a version delimiter is simply incompatible with |
| 232 | determining whether a pathname is in VMS format or in Unix format with |
| 233 | extended file syntax. There is no way to know whether "perl-5.8.6" is a |
| 234 | Unix "perl-5.8.6" or a VMS "perl-5.8;6" when passing it to unixify() or |
| 235 | vmsify(). |
| 236 | |
| 237 | The DECC$FILENAME_UNIX_REPORT logical name controls how Perl interprets |
| 238 | filenames to the extent that Perl uses the CRTL internally for many |
| 239 | purposes, and attempts to follow CRTL conventions for reporting |
| 240 | filenames. The DECC$FILENAME_UNIX_ONLY feature differs in that it |
| 241 | expects all filenames passed to the C run-time to be already in Unix |
| 242 | format. This feature is not yet supported in Perl since Perl uses |
| 243 | traditional OpenVMS file specifications internally and in the test |
| 244 | harness, and it is not yet clear whether this mode will be useful or |
| 245 | useable. The feature logical name DECC$POSIX_COMPLIANT_PATHNAMES is new |
| 246 | with the RMS Symbolic Link SDK and included with OpenVMS v8.3, but is |
| 247 | not yet supported in Perl. |
| 248 | |
| 249 | =head2 Filename Case |
| 250 | |
| 251 | Perl follows VMS defaults and override settings in preserving (or not |
| 252 | preserving) filename case. Case is not preserved on ODS-2 formatted |
| 253 | volumes on any architecture. On ODS-5 volumes, filenames may be case |
| 254 | preserved depending on process and feature settings. Perl now honors |
| 255 | DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE on those systems where |
| 256 | the CRTL supports these features. When these features are not enabled |
| 257 | or the CRTL does not support them, Perl follows the traditional CRTL |
| 258 | behavior of downcasing command-line arguments and returning file |
| 259 | specifications in lower case only. |
| 260 | |
| 261 | I<N. B.> It is very easy to get tripped up using a mixture of other |
| 262 | programs, external utilities, and Perl scripts that are in varying |
| 263 | states of being able to handle case preservation. For example, a file |
| 264 | created by an older version of an archive utility or a build utility |
| 265 | such as MMK or MMS may generate a filename in all upper case even on an |
| 266 | ODS-5 volume. If this filename is later retrieved by a Perl script or |
| 267 | module in a case preserving environment, that upper case name may not |
| 268 | match the mixed-case or lower-case exceptions of the Perl code. Your |
| 269 | best bet is to follow an all-or-nothing approach to case preservation: |
| 270 | either don't use it at all, or make sure your entire toolchain and |
| 271 | application environment support and use it. |
| 272 | |
| 273 | OpenVMS Alpha v7.3-1 and later and all version of OpenVMS I64 support |
| 274 | case sensitivity as a process setting (see C<SET PROCESS |
| 275 | /CASE_LOOKUP=SENSITIVE>). Perl does not currently support case |
| 276 | sensitivity on VMS, but it may in the future, so Perl programs should |
| 277 | use the C<< File::Spec->case_tolerant >> method to determine the state, and |
| 278 | not the C<$^O> variable. |
| 279 | |
| 280 | =head2 Symbolic Links |
| 281 | |
| 282 | When built on an ODS-5 volume with symbolic links enabled, Perl by |
| 283 | default supports symbolic links when the requisite support is available |
| 284 | in the filesystem and CRTL (generally 64-bit OpenVMS v8.3 and later). |
| 285 | There are a number of limitations and caveats to be aware of when |
| 286 | working with symbolic links on VMS. Most notably, the target of a valid |
| 287 | symbolic link must be expressed as a Unix-style path and it must exist |
| 288 | on a volume visible from your POSIX root (see the C<SHOW ROOT> command |
| 289 | in DCL help). For further details on symbolic link capabilities and |
| 290 | requirements, see chapter 12 of the CRTL manual that ships with OpenVMS |
| 291 | v8.3 or later. |
| 292 | |
| 293 | =head2 Wildcard expansion |
| 294 | |
| 295 | File specifications containing wildcards are allowed both on |
| 296 | the command line and within Perl globs (e.g. C<E<lt>*.cE<gt>>). If |
| 297 | the wildcard filespec uses VMS syntax, the resultant |
| 298 | filespecs will follow VMS syntax; if a Unix-style filespec is |
| 299 | passed in, Unix-style filespecs will be returned. |
| 300 | Similar to the behavior of wildcard globbing for a Unix shell, |
| 301 | one can escape command line wildcards with double quotation |
| 302 | marks C<"> around a perl program command line argument. However, |
| 303 | owing to the stripping of C<"> characters carried out by the C |
| 304 | handling of argv you will need to escape a construct such as |
| 305 | this one (in a directory containing the files F<PERL.C>, F<PERL.EXE>, |
| 306 | F<PERL.H>, and F<PERL.OBJ>): |
| 307 | |
| 308 | $ perl -e "print join(' ',@ARGV)" perl.* |
| 309 | perl.c perl.exe perl.h perl.obj |
| 310 | |
| 311 | in the following triple quoted manner: |
| 312 | |
| 313 | $ perl -e "print join(' ',@ARGV)" """perl.*""" |
| 314 | perl.* |
| 315 | |
| 316 | In both the case of unquoted command line arguments or in calls |
| 317 | to C<glob()> VMS wildcard expansion is performed. (csh-style |
| 318 | wildcard expansion is available if you use C<File::Glob::glob>.) |
| 319 | If the wildcard filespec contains a device or directory |
| 320 | specification, then the resultant filespecs will also contain |
| 321 | a device and directory; otherwise, device and directory |
| 322 | information are removed. VMS-style resultant filespecs will |
| 323 | contain a full device and directory, while Unix-style |
| 324 | resultant filespecs will contain only as much of a directory |
| 325 | path as was present in the input filespec. For example, if |
| 326 | your default directory is Perl_Root:[000000], the expansion |
| 327 | of C<[.t]*.*> will yield filespecs like |
| 328 | "perl_root:[t]base.dir", while the expansion of C<t/*/*> will |
| 329 | yield filespecs like "t/base.dir". (This is done to match |
| 330 | the behavior of glob expansion performed by Unix shells.) |
| 331 | |
| 332 | Similarly, the resultant filespec will contain the file version |
| 333 | only if one was present in the input filespec. |
| 334 | |
| 335 | |
| 336 | =head2 Pipes |
| 337 | |
| 338 | Input and output pipes to Perl filehandles are supported; the |
| 339 | "file name" is passed to lib$spawn() for asynchronous |
| 340 | execution. You should be careful to close any pipes you have |
| 341 | opened in a Perl script, lest you leave any "orphaned" |
| 342 | subprocesses around when Perl exits. |
| 343 | |
| 344 | You may also use backticks to invoke a DCL subprocess, whose |
| 345 | output is used as the return value of the expression. The |
| 346 | string between the backticks is handled as if it were the |
| 347 | argument to the C<system> operator (see below). In this case, |
| 348 | Perl will wait for the subprocess to complete before continuing. |
| 349 | |
| 350 | The mailbox (MBX) that perl can create to communicate with a pipe |
| 351 | defaults to a buffer size of 8192 on 64-bit systems, 512 on VAX. The |
| 352 | default buffer size is adjustable via the logical name PERL_MBX_SIZE |
| 353 | provided that the value falls between 128 and the SYSGEN parameter |
| 354 | MAXBUF inclusive. For example, to set the mailbox size to 32767 use |
| 355 | C<$ENV{'PERL_MBX_SIZE'} = 32767;> and then open and use pipe constructs. |
| 356 | An alternative would be to issue the command: |
| 357 | |
| 358 | $ Define PERL_MBX_SIZE 32767 |
| 359 | |
| 360 | before running your wide record pipe program. A larger value may |
| 361 | improve performance at the expense of the BYTLM UAF quota. |
| 362 | |
| 363 | =head1 PERL5LIB and PERLLIB |
| 364 | |
| 365 | The PERL5LIB and PERLLIB logical names work as documented in L<perl>, |
| 366 | except that the element separator is '|' instead of ':'. The |
| 367 | directory specifications may use either VMS or Unix syntax. |
| 368 | |
| 369 | =head1 The Perl Forked Debugger |
| 370 | |
| 371 | The Perl forked debugger places the debugger commands and output in a |
| 372 | separate X-11 terminal window so that commands and output from multiple |
| 373 | processes are not mixed together. |
| 374 | |
| 375 | Perl on VMS supports an emulation of the forked debugger when Perl is |
| 376 | run on a VMS system that has X11 support installed. |
| 377 | |
| 378 | To use the forked debugger, you need to have the default display set to an |
| 379 | X-11 Server and some environment variables set that Unix expects. |
| 380 | |
| 381 | The forked debugger requires the environment variable C<TERM> to be C<xterm>, |
| 382 | and the environment variable C<DISPLAY> to exist. C<xterm> must be in |
| 383 | lower case. |
| 384 | |
| 385 | $define TERM "xterm" |
| 386 | |
| 387 | $define DISPLAY "hostname:0.0" |
| 388 | |
| 389 | Currently the value of C<DISPLAY> is ignored. It is recommended that it be set |
| 390 | to be the hostname of the display, the server and screen in Unix notation. In |
| 391 | the future the value of DISPLAY may be honored by Perl instead of using the |
| 392 | default display. |
| 393 | |
| 394 | It may be helpful to always use the forked debugger so that script I/O is |
| 395 | separated from debugger I/O. You can force the debugger to be forked by |
| 396 | assigning a value to the logical name <PERLDB_PIDS> that is not a process |
| 397 | identification number. |
| 398 | |
| 399 | $define PERLDB_PIDS XXXX |
| 400 | |
| 401 | |
| 402 | =head1 PERL_VMS_EXCEPTION_DEBUG |
| 403 | |
| 404 | The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause the VMS |
| 405 | debugger to be invoked if a fatal exception that is not otherwise |
| 406 | handled is raised. The purpose of this is to allow debugging of |
| 407 | internal Perl problems that would cause such a condition. |
| 408 | |
| 409 | This allows the programmer to look at the execution stack and variables to |
| 410 | find out the cause of the exception. As the debugger is being invoked as |
| 411 | the Perl interpreter is about to do a fatal exit, continuing the execution |
| 412 | in debug mode is usually not practical. |
| 413 | |
| 414 | Starting Perl in the VMS debugger may change the program execution |
| 415 | profile in a way that such problems are not reproduced. |
| 416 | |
| 417 | The C<kill> function can be used to test this functionality from within |
| 418 | a program. |
| 419 | |
| 420 | In typical VMS style, only the first letter of the value of this logical |
| 421 | name is actually checked in a case insensitive mode, and it is considered |
| 422 | enabled if it is the value "T","1" or "E". |
| 423 | |
| 424 | This logical name must be defined before Perl is started. |
| 425 | |
| 426 | =head1 Command line |
| 427 | |
| 428 | =head2 I/O redirection and backgrounding |
| 429 | |
| 430 | Perl for VMS supports redirection of input and output on the |
| 431 | command line, using a subset of Bourne shell syntax: |
| 432 | |
| 433 | =over 4 |
| 434 | |
| 435 | =item * |
| 436 | |
| 437 | C<E<lt>file> reads stdin from C<file>, |
| 438 | |
| 439 | =item * |
| 440 | |
| 441 | C<E<gt>file> writes stdout to C<file>, |
| 442 | |
| 443 | =item * |
| 444 | |
| 445 | C<E<gt>E<gt>file> appends stdout to C<file>, |
| 446 | |
| 447 | =item * |
| 448 | |
| 449 | C<2E<gt>file> writes stderr to C<file>, |
| 450 | |
| 451 | =item * |
| 452 | |
| 453 | C<2E<gt>E<gt>file> appends stderr to C<file>, and |
| 454 | |
| 455 | =item * |
| 456 | |
| 457 | C<< 2>&1 >> redirects stderr to stdout. |
| 458 | |
| 459 | =back |
| 460 | |
| 461 | In addition, output may be piped to a subprocess, using the |
| 462 | character '|'. Anything after this character on the command |
| 463 | line is passed to a subprocess for execution; the subprocess |
| 464 | takes the output of Perl as its input. |
| 465 | |
| 466 | Finally, if the command line ends with '&', the entire |
| 467 | command is run in the background as an asynchronous |
| 468 | subprocess. |
| 469 | |
| 470 | =head2 Command line switches |
| 471 | |
| 472 | The following command line switches behave differently under |
| 473 | VMS than described in L<perlrun>. Note also that in order |
| 474 | to pass uppercase switches to Perl, you need to enclose |
| 475 | them in double-quotes on the command line, since the CRTL |
| 476 | downcases all unquoted strings. |
| 477 | |
| 478 | On newer 64 bit versions of OpenVMS, a process setting now |
| 479 | controls if the quoting is needed to preserve the case of |
| 480 | command line arguments. |
| 481 | |
| 482 | =over 4 |
| 483 | |
| 484 | =item -i |
| 485 | |
| 486 | If the C<-i> switch is present but no extension for a backup |
| 487 | copy is given, then inplace editing creates a new version of |
| 488 | a file; the existing copy is not deleted. (Note that if |
| 489 | an extension is given, an existing file is renamed to the backup |
| 490 | file, as is the case under other operating systems, so it does |
| 491 | not remain as a previous version under the original filename.) |
| 492 | |
| 493 | =item -S |
| 494 | |
| 495 | If the C<"-S"> or C<-"S"> switch is present I<and> the script |
| 496 | name does not contain a directory, then Perl translates the |
| 497 | logical name DCL$PATH as a searchlist, using each translation |
| 498 | as a directory in which to look for the script. In addition, |
| 499 | if no file type is specified, Perl looks in each directory |
| 500 | for a file matching the name specified, with a blank type, |
| 501 | a type of F<.pl>, and a type of F<.com>, in that order. |
| 502 | |
| 503 | =item -u |
| 504 | |
| 505 | The C<-u> switch causes the VMS debugger to be invoked |
| 506 | after the Perl program is compiled, but before it has |
| 507 | run. It does not create a core dump file. |
| 508 | |
| 509 | =back |
| 510 | |
| 511 | =head1 Perl functions |
| 512 | |
| 513 | As of the time this document was last revised, the following |
| 514 | Perl functions were implemented in the VMS port of Perl |
| 515 | (functions marked with * are discussed in more detail below): |
| 516 | |
| 517 | file tests*, abs, alarm, atan, backticks*, binmode*, bless, |
| 518 | caller, chdir, chmod, chown, chomp, chop, chr, |
| 519 | close, closedir, cos, crypt*, defined, delete, die, do, dump*, |
| 520 | each, endgrent, endpwent, eof, eval, exec*, exists, exit, exp, |
| 521 | fileno, flock getc, getgrent*, getgrgid*, getgrnam, getlogin, |
| 522 | getppid, getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto, |
| 523 | grep, hex, ioctl, import, index, int, join, keys, kill*, |
| 524 | last, lc, lcfirst, lchown*, length, link*, local, localtime, log, |
| 525 | lstat, m//, map, mkdir, my, next, no, oct, open, opendir, ord, |
| 526 | pack, pipe, pop, pos, print, printf, push, q//, qq//, qw//, |
| 527 | qx//*, quotemeta, rand, read, readdir, readlink*, redo, ref, |
| 528 | rename, require, reset, return, reverse, rewinddir, rindex, |
| 529 | rmdir, s///, scalar, seek, seekdir, select(internal), |
| 530 | select (system call)*, setgrent, setpwent, shift, sin, sleep, |
| 531 | socketpair, sort, splice, split, sprintf, sqrt, srand, stat, |
| 532 | study, substr, symlink*, sysread, system*, syswrite, tell, |
| 533 | telldir, tie, time, times*, tr///, uc, ucfirst, umask, |
| 534 | undef, unlink*, unpack, untie, unshift, use, utime*, |
| 535 | values, vec, wait, waitpid*, wantarray, warn, write, y/// |
| 536 | |
| 537 | The following functions were not implemented in the VMS port, |
| 538 | and calling them produces a fatal error (usually) or |
| 539 | undefined behavior (rarely, we hope): |
| 540 | |
| 541 | chroot, dbmclose, dbmopen, fork*, getpgrp, getpriority, |
| 542 | msgctl, msgget, msgsend, msgrcv, semctl, |
| 543 | semget, semop, setpgrp, setpriority, shmctl, shmget, |
| 544 | shmread, shmwrite, syscall |
| 545 | |
| 546 | The following functions are available on Perls compiled with Dec C |
| 547 | 5.2 or greater and running VMS 7.0 or greater: |
| 548 | |
| 549 | truncate |
| 550 | |
| 551 | The following functions are available on Perls built on VMS 7.2 or |
| 552 | greater: |
| 553 | |
| 554 | fcntl (without locking) |
| 555 | |
| 556 | The following functions may or may not be implemented, |
| 557 | depending on what type of socket support you've built into |
| 558 | your copy of Perl: |
| 559 | |
| 560 | accept, bind, connect, getpeername, |
| 561 | gethostbyname, getnetbyname, getprotobyname, |
| 562 | getservbyname, gethostbyaddr, getnetbyaddr, |
| 563 | getprotobynumber, getservbyport, gethostent, |
| 564 | getnetent, getprotoent, getservent, sethostent, |
| 565 | setnetent, setprotoent, setservent, endhostent, |
| 566 | endnetent, endprotoent, endservent, getsockname, |
| 567 | getsockopt, listen, recv, select(system call)*, |
| 568 | send, setsockopt, shutdown, socket |
| 569 | |
| 570 | The following function is available on Perls built on 64 bit OpenVMS v8.2 |
| 571 | with hard links enabled on an ODS-5 formatted build disk. CRTL support |
| 572 | is in principle available as of OpenVMS v7.3-1, and better configuration |
| 573 | support could detect this. |
| 574 | |
| 575 | link |
| 576 | |
| 577 | The following functions are available on Perls built on 64 bit OpenVMS |
| 578 | v8.2 and later. CRTL support is in principle available as of OpenVMS |
| 579 | v7.3-2, and better configuration support could detect this. |
| 580 | |
| 581 | getgrgid, getgrnam, getpwnam, getpwuid, |
| 582 | setgrent, ttyname |
| 583 | |
| 584 | The following functions are available on Perls built on 64 bit OpenVMS v8.2 |
| 585 | and later. |
| 586 | |
| 587 | statvfs, socketpair |
| 588 | |
| 589 | =over 4 |
| 590 | |
| 591 | =item File tests |
| 592 | |
| 593 | The tests C<-b>, C<-B>, C<-c>, C<-C>, C<-d>, C<-e>, C<-f>, |
| 594 | C<-o>, C<-M>, C<-s>, C<-S>, C<-t>, C<-T>, and C<-z> work as |
| 595 | advertised. The return values for C<-r>, C<-w>, and C<-x> |
| 596 | tell you whether you can actually access the file; this may |
| 597 | not reflect the UIC-based file protections. Since real and |
| 598 | effective UIC don't differ under VMS, C<-O>, C<-R>, C<-W>, |
| 599 | and C<-X> are equivalent to C<-o>, C<-r>, C<-w>, and C<-x>. |
| 600 | Similarly, several other tests, including C<-A>, C<-g>, C<-k>, |
| 601 | C<-l>, C<-p>, and C<-u>, aren't particularly meaningful under |
| 602 | VMS, and the values returned by these tests reflect whatever |
| 603 | your CRTL C<stat()> routine does to the equivalent bits in the |
| 604 | st_mode field. Finally, C<-d> returns true if passed a device |
| 605 | specification without an explicit directory (e.g. C<DUA1:>), as |
| 606 | well as if passed a directory. |
| 607 | |
| 608 | There are DECC feature logical names AND ODS-5 volume attributes that |
| 609 | also control what values are returned for the date fields. |
| 610 | |
| 611 | Note: Some sites have reported problems when using the file-access |
| 612 | tests (C<-r>, C<-w>, and C<-x>) on files accessed via DEC's DFS. |
| 613 | Specifically, since DFS does not currently provide access to the |
| 614 | extended file header of files on remote volumes, attempts to |
| 615 | examine the ACL fail, and the file tests will return false, |
| 616 | with C<$!> indicating that the file does not exist. You can |
| 617 | use C<stat> on these files, since that checks UIC-based protection |
| 618 | only, and then manually check the appropriate bits, as defined by |
| 619 | your C compiler's F<stat.h>, in the mode value it returns, if you |
| 620 | need an approximation of the file's protections. |
| 621 | |
| 622 | =item backticks |
| 623 | |
| 624 | Backticks create a subprocess, and pass the enclosed string |
| 625 | to it for execution as a DCL command. Since the subprocess is |
| 626 | created directly via C<lib$spawn()>, any valid DCL command string |
| 627 | may be specified. |
| 628 | |
| 629 | =item binmode FILEHANDLE |
| 630 | |
| 631 | The C<binmode> operator will attempt to insure that no translation |
| 632 | of carriage control occurs on input from or output to this filehandle. |
| 633 | Since this involves reopening the file and then restoring its |
| 634 | file position indicator, if this function returns FALSE, the |
| 635 | underlying filehandle may no longer point to an open file, or may |
| 636 | point to a different position in the file than before C<binmode> |
| 637 | was called. |
| 638 | |
| 639 | Note that C<binmode> is generally not necessary when using normal |
| 640 | filehandles; it is provided so that you can control I/O to existing |
| 641 | record-structured files when necessary. You can also use the |
| 642 | C<vmsfopen> function in the VMS::Stdio extension to gain finer |
| 643 | control of I/O to files and devices with different record structures. |
| 644 | |
| 645 | =item crypt PLAINTEXT, USER |
| 646 | |
| 647 | The C<crypt> operator uses the C<sys$hash_password> system |
| 648 | service to generate the hashed representation of PLAINTEXT. |
| 649 | If USER is a valid username, the algorithm and salt values |
| 650 | are taken from that user's UAF record. If it is not, then |
| 651 | the preferred algorithm and a salt of 0 are used. The |
| 652 | quadword encrypted value is returned as an 8-character string. |
| 653 | |
| 654 | The value returned by C<crypt> may be compared against |
| 655 | the encrypted password from the UAF returned by the C<getpw*> |
| 656 | functions, in order to authenticate users. If you're |
| 657 | going to do this, remember that the encrypted password in |
| 658 | the UAF was generated using uppercase username and |
| 659 | password strings; you'll have to upcase the arguments to |
| 660 | C<crypt> to insure that you'll get the proper value: |
| 661 | |
| 662 | sub validate_passwd { |
| 663 | my($user,$passwd) = @_; |
| 664 | my($pwdhash); |
| 665 | if ( !($pwdhash = (getpwnam($user))[1]) || |
| 666 | $pwdhash ne crypt("\U$passwd","\U$name") ) { |
| 667 | intruder_alert($name); |
| 668 | } |
| 669 | return 1; |
| 670 | } |
| 671 | |
| 672 | |
| 673 | =item die |
| 674 | |
| 675 | C<die> will force the native VMS exit status to be an SS$_ABORT code |
| 676 | if neither of the $! or $? status values are ones that would cause |
| 677 | the native status to be interpreted as being what VMS classifies as |
| 678 | SEVERE_ERROR severity for DCL error handling. |
| 679 | |
| 680 | When C<PERL_VMS_POSIX_EXIT> is active (see L</"$?"> below), the native VMS exit |
| 681 | status value will have either one of the C<$!> or C<$?> or C<$^E> or |
| 682 | the Unix value 255 encoded into it in a way that the effective original |
| 683 | value can be decoded by other programs written in C, including Perl |
| 684 | and the GNV package. As per the normal non-VMS behavior of C<die> if |
| 685 | either C<$!> or C<$?> are non-zero, one of those values will be |
| 686 | encoded into a native VMS status value. If both of the Unix status |
| 687 | values are 0, and the C<$^E> value is set one of ERROR or SEVERE_ERROR |
| 688 | severity, then the C<$^E> value will be used as the exit code as is. |
| 689 | If none of the above apply, the Unix value of 255 will be encoded into |
| 690 | a native VMS exit status value. |
| 691 | |
| 692 | Please note a significant difference in the behavior of C<die> in |
| 693 | the C<PERL_VMS_POSIX_EXIT> mode is that it does not force a VMS |
| 694 | SEVERE_ERROR status on exit. The Unix exit values of 2 through |
| 695 | 255 will be encoded in VMS status values with severity levels of |
| 696 | SUCCESS. The Unix exit value of 1 will be encoded in a VMS status |
| 697 | value with a severity level of ERROR. This is to be compatible with |
| 698 | how the VMS C library encodes these values. |
| 699 | |
| 700 | The minimum severity level set by C<die> in C<PERL_VMS_POSIX_EXIT> mode |
| 701 | may be changed to be ERROR or higher in the future depending on the |
| 702 | results of testing and further review. |
| 703 | |
| 704 | See L</"$?"> for a description of the encoding of the Unix value to |
| 705 | produce a native VMS status containing it. |
| 706 | |
| 707 | =item dump |
| 708 | |
| 709 | Rather than causing Perl to abort and dump core, the C<dump> |
| 710 | operator invokes the VMS debugger. If you continue to |
| 711 | execute the Perl program under the debugger, control will |
| 712 | be transferred to the label specified as the argument to |
| 713 | C<dump>, or, if no label was specified, back to the |
| 714 | beginning of the program. All other state of the program |
| 715 | (I<e.g.> values of variables, open file handles) are not |
| 716 | affected by calling C<dump>. |
| 717 | |
| 718 | =item exec LIST |
| 719 | |
| 720 | A call to C<exec> will cause Perl to exit, and to invoke the command |
| 721 | given as an argument to C<exec> via C<lib$do_command>. If the |
| 722 | argument begins with '@' or '$' (other than as part of a filespec), |
| 723 | then it is executed as a DCL command. Otherwise, the first token on |
| 724 | the command line is treated as the filespec of an image to run, and |
| 725 | an attempt is made to invoke it (using F<.Exe> and the process |
| 726 | defaults to expand the filespec) and pass the rest of C<exec>'s |
| 727 | argument to it as parameters. If the token has no file type, and |
| 728 | matches a file with null type, then an attempt is made to determine |
| 729 | whether the file is an executable image which should be invoked |
| 730 | using C<MCR> or a text file which should be passed to DCL as a |
| 731 | command procedure. |
| 732 | |
| 733 | =item fork |
| 734 | |
| 735 | While in principle the C<fork> operator could be implemented via |
| 736 | (and with the same rather severe limitations as) the CRTL C<vfork()> |
| 737 | routine, and while some internal support to do just that is in |
| 738 | place, the implementation has never been completed, making C<fork> |
| 739 | currently unavailable. A true kernel C<fork()> is expected in a |
| 740 | future version of VMS, and the pseudo-fork based on interpreter |
| 741 | threads may be available in a future version of Perl on VMS (see |
| 742 | L<perlfork>). In the meantime, use C<system>, backticks, or piped |
| 743 | filehandles to create subprocesses. |
| 744 | |
| 745 | =item getpwent |
| 746 | |
| 747 | =item getpwnam |
| 748 | |
| 749 | =item getpwuid |
| 750 | |
| 751 | These operators obtain the information described in L<perlfunc>, |
| 752 | if you have the privileges necessary to retrieve the named user's |
| 753 | UAF information via C<sys$getuai>. If not, then only the C<$name>, |
| 754 | C<$uid>, and C<$gid> items are returned. The C<$dir> item contains |
| 755 | the login directory in VMS syntax, while the C<$comment> item |
| 756 | contains the login directory in Unix syntax. The C<$gcos> item |
| 757 | contains the owner field from the UAF record. The C<$quota> |
| 758 | item is not used. |
| 759 | |
| 760 | =item gmtime |
| 761 | |
| 762 | The C<gmtime> operator will function properly if you have a |
| 763 | working CRTL C<gmtime()> routine, or if the logical name |
| 764 | SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds |
| 765 | which must be added to UTC to yield local time. (This logical |
| 766 | name is defined automatically if you are running a version of |
| 767 | VMS with built-in UTC support.) If neither of these cases is |
| 768 | true, a warning message is printed, and C<undef> is returned. |
| 769 | |
| 770 | =item kill |
| 771 | |
| 772 | In most cases, C<kill> is implemented via the undocumented system |
| 773 | service C<$SIGPRC>, which has the same calling sequence as C<$FORCEX>, but |
| 774 | throws an exception in the target process rather than forcing it to call |
| 775 | C<$EXIT>. Generally speaking, C<kill> follows the behavior of the |
| 776 | CRTL's C<kill()> function, but unlike that function can be called from |
| 777 | within a signal handler. Also, unlike the C<kill> in some versions of |
| 778 | the CRTL, Perl's C<kill> checks the validity of the signal passed in and |
| 779 | returns an error rather than attempting to send an unrecognized signal. |
| 780 | |
| 781 | Also, negative signal values don't do anything special under |
| 782 | VMS; they're just converted to the corresponding positive value. |
| 783 | |
| 784 | =item qx// |
| 785 | |
| 786 | See the entry on C<backticks> above. |
| 787 | |
| 788 | =item select (system call) |
| 789 | |
| 790 | If Perl was not built with socket support, the system call |
| 791 | version of C<select> is not available at all. If socket |
| 792 | support is present, then the system call version of |
| 793 | C<select> functions only for file descriptors attached |
| 794 | to sockets. It will not provide information about regular |
| 795 | files or pipes, since the CRTL C<select()> routine does not |
| 796 | provide this functionality. |
| 797 | |
| 798 | =item stat EXPR |
| 799 | |
| 800 | Since VMS keeps track of files according to a different scheme |
| 801 | than Unix, it's not really possible to represent the file's ID |
| 802 | in the C<st_dev> and C<st_ino> fields of a C<struct stat>. Perl |
| 803 | tries its best, though, and the values it uses are pretty unlikely |
| 804 | to be the same for two different files. We can't guarantee this, |
| 805 | though, so caveat scriptor. |
| 806 | |
| 807 | =item system LIST |
| 808 | |
| 809 | The C<system> operator creates a subprocess, and passes its |
| 810 | arguments to the subprocess for execution as a DCL command. |
| 811 | Since the subprocess is created directly via C<lib$spawn()>, any |
| 812 | valid DCL command string may be specified. If the string begins with |
| 813 | '@', it is treated as a DCL command unconditionally. Otherwise, if |
| 814 | the first token contains a character used as a delimiter in file |
| 815 | specification (e.g. C<:> or C<]>), an attempt is made to expand it |
| 816 | using a default type of F<.Exe> and the process defaults, and if |
| 817 | successful, the resulting file is invoked via C<MCR>. This allows you |
| 818 | to invoke an image directly simply by passing the file specification |
| 819 | to C<system>, a common Unixish idiom. If the token has no file type, |
| 820 | and matches a file with null type, then an attempt is made to |
| 821 | determine whether the file is an executable image which should be |
| 822 | invoked using C<MCR> or a text file which should be passed to DCL |
| 823 | as a command procedure. |
| 824 | |
| 825 | If LIST consists of the empty string, C<system> spawns an |
| 826 | interactive DCL subprocess, in the same fashion as typing |
| 827 | B<SPAWN> at the DCL prompt. |
| 828 | |
| 829 | Perl waits for the subprocess to complete before continuing |
| 830 | execution in the current process. As described in L<perlfunc>, |
| 831 | the return value of C<system> is a fake "status" which follows |
| 832 | POSIX semantics unless the pragma C<use vmsish 'status'> is in |
| 833 | effect; see the description of C<$?> in this document for more |
| 834 | detail. |
| 835 | |
| 836 | =item time |
| 837 | |
| 838 | The value returned by C<time> is the offset in seconds from |
| 839 | 01-JAN-1970 00:00:00 (just like the CRTL's times() routine), in order |
| 840 | to make life easier for code coming in from the POSIX/Unix world. |
| 841 | |
| 842 | =item times |
| 843 | |
| 844 | The array returned by the C<times> operator is divided up |
| 845 | according to the same rules the CRTL C<times()> routine. |
| 846 | Therefore, the "system time" elements will always be 0, since |
| 847 | there is no difference between "user time" and "system" time |
| 848 | under VMS, and the time accumulated by a subprocess may or may |
| 849 | not appear separately in the "child time" field, depending on |
| 850 | whether C<times()> keeps track of subprocesses separately. Note |
| 851 | especially that the VAXCRTL (at least) keeps track only of |
| 852 | subprocesses spawned using C<fork()> and C<exec()>; it will not |
| 853 | accumulate the times of subprocesses spawned via pipes, C<system()>, |
| 854 | or backticks. |
| 855 | |
| 856 | =item unlink LIST |
| 857 | |
| 858 | C<unlink> will delete the highest version of a file only; in |
| 859 | order to delete all versions, you need to say |
| 860 | |
| 861 | 1 while unlink LIST; |
| 862 | |
| 863 | You may need to make this change to scripts written for a |
| 864 | Unix system which expect that after a call to C<unlink>, |
| 865 | no files with the names passed to C<unlink> will exist. |
| 866 | (Note: This can be changed at compile time; if you |
| 867 | C<use Config> and C<$Config{'d_unlink_all_versions'}> is |
| 868 | C<define>, then C<unlink> will delete all versions of a |
| 869 | file on the first call.) |
| 870 | |
| 871 | C<unlink> will delete a file if at all possible, even if it |
| 872 | requires changing file protection (though it won't try to |
| 873 | change the protection of the parent directory). You can tell |
| 874 | whether you've got explicit delete access to a file by using the |
| 875 | C<VMS::Filespec::candelete> operator. For instance, in order |
| 876 | to delete only files to which you have delete access, you could |
| 877 | say something like |
| 878 | |
| 879 | sub safe_unlink { |
| 880 | my($file,$num); |
| 881 | foreach $file (@_) { |
| 882 | next unless VMS::Filespec::candelete($file); |
| 883 | $num += unlink $file; |
| 884 | } |
| 885 | $num; |
| 886 | } |
| 887 | |
| 888 | (or you could just use C<VMS::Stdio::remove>, if you've installed |
| 889 | the VMS::Stdio extension distributed with Perl). If C<unlink> has to |
| 890 | change the file protection to delete the file, and you interrupt it |
| 891 | in midstream, the file may be left intact, but with a changed ACL |
| 892 | allowing you delete access. |
| 893 | |
| 894 | This behavior of C<unlink> is to be compatible with POSIX behavior |
| 895 | and not traditional VMS behavior. |
| 896 | |
| 897 | =item utime LIST |
| 898 | |
| 899 | This operator changes only the modification time of the file (VMS |
| 900 | revision date) on ODS-2 volumes and ODS-5 volumes without access |
| 901 | dates enabled. On ODS-5 volumes with access dates enabled, the |
| 902 | true access time is modified. |
| 903 | |
| 904 | =item waitpid PID,FLAGS |
| 905 | |
| 906 | If PID is a subprocess started by a piped C<open()> (see L<open>), |
| 907 | C<waitpid> will wait for that subprocess, and return its final status |
| 908 | value in C<$?>. If PID is a subprocess created in some other way (e.g. |
| 909 | SPAWNed before Perl was invoked), C<waitpid> will simply check once per |
| 910 | second whether the process has completed, and return when it has. (If |
| 911 | PID specifies a process that isn't a subprocess of the current process, |
| 912 | and you invoked Perl with the C<-w> switch, a warning will be issued.) |
| 913 | |
| 914 | Returns PID on success, -1 on error. The FLAGS argument is ignored |
| 915 | in all cases. |
| 916 | |
| 917 | =back |
| 918 | |
| 919 | =head1 Perl variables |
| 920 | |
| 921 | The following VMS-specific information applies to the indicated |
| 922 | "special" Perl variables, in addition to the general information |
| 923 | in L<perlvar>. Where there is a conflict, this information |
| 924 | takes precedence. |
| 925 | |
| 926 | =over 4 |
| 927 | |
| 928 | =item %ENV |
| 929 | |
| 930 | The operation of the C<%ENV> array depends on the translation |
| 931 | of the logical name F<PERL_ENV_TABLES>. If defined, it should |
| 932 | be a search list, each element of which specifies a location |
| 933 | for C<%ENV> elements. If you tell Perl to read or set the |
| 934 | element C<$ENV{>I<name>C<}>, then Perl uses the translations of |
| 935 | F<PERL_ENV_TABLES> as follows: |
| 936 | |
| 937 | =over 4 |
| 938 | |
| 939 | =item CRTL_ENV |
| 940 | |
| 941 | This string tells Perl to consult the CRTL's internal C<environ> |
| 942 | array of key-value pairs, using I<name> as the key. In most cases, |
| 943 | this contains only a few keys, but if Perl was invoked via the C |
| 944 | C<exec[lv]e()> function, as is the case for CGI processing by some |
| 945 | HTTP servers, then the C<environ> array may have been populated by |
| 946 | the calling program. |
| 947 | |
| 948 | =item CLISYM_[LOCAL] |
| 949 | |
| 950 | A string beginning with C<CLISYM_>tells Perl to consult the CLI's |
| 951 | symbol tables, using I<name> as the name of the symbol. When reading |
| 952 | an element of C<%ENV>, the local symbol table is scanned first, followed |
| 953 | by the global symbol table.. The characters following C<CLISYM_> are |
| 954 | significant when an element of C<%ENV> is set or deleted: if the |
| 955 | complete string is C<CLISYM_LOCAL>, the change is made in the local |
| 956 | symbol table; otherwise the global symbol table is changed. |
| 957 | |
| 958 | =item Any other string |
| 959 | |
| 960 | If an element of F<PERL_ENV_TABLES> translates to any other string, |
| 961 | that string is used as the name of a logical name table, which is |
| 962 | consulted using I<name> as the logical name. The normal search |
| 963 | order of access modes is used. |
| 964 | |
| 965 | =back |
| 966 | |
| 967 | F<PERL_ENV_TABLES> is translated once when Perl starts up; any changes |
| 968 | you make while Perl is running do not affect the behavior of C<%ENV>. |
| 969 | If F<PERL_ENV_TABLES> is not defined, then Perl defaults to consulting |
| 970 | first the logical name tables specified by F<LNM$FILE_DEV>, and then |
| 971 | the CRTL C<environ> array. |
| 972 | |
| 973 | In all operations on %ENV, the key string is treated as if it |
| 974 | were entirely uppercase, regardless of the case actually |
| 975 | specified in the Perl expression. |
| 976 | |
| 977 | When an element of C<%ENV> is read, the locations to which |
| 978 | F<PERL_ENV_TABLES> points are checked in order, and the value |
| 979 | obtained from the first successful lookup is returned. If the |
| 980 | name of the C<%ENV> element contains a semi-colon, it and |
| 981 | any characters after it are removed. These are ignored when |
| 982 | the CRTL C<environ> array or a CLI symbol table is consulted. |
| 983 | However, the name is looked up in a logical name table, the |
| 984 | suffix after the semi-colon is treated as the translation index |
| 985 | to be used for the lookup. This lets you look up successive values |
| 986 | for search list logical names. For instance, if you say |
| 987 | |
| 988 | $ Define STORY once,upon,a,time,there,was |
| 989 | $ perl -e "for ($i = 0; $i <= 6; $i++) " - |
| 990 | _$ -e "{ print $ENV{'story;'.$i},' '}" |
| 991 | |
| 992 | Perl will print C<ONCE UPON A TIME THERE WAS>, assuming, of course, |
| 993 | that F<PERL_ENV_TABLES> is set up so that the logical name C<story> |
| 994 | is found, rather than a CLI symbol or CRTL C<environ> element with |
| 995 | the same name. |
| 996 | |
| 997 | When an element of C<%ENV> is set to a defined string, the |
| 998 | corresponding definition is made in the location to which the |
| 999 | first translation of F<PERL_ENV_TABLES> points. If this causes a |
| 1000 | logical name to be created, it is defined in supervisor mode. |
| 1001 | (The same is done if an existing logical name was defined in |
| 1002 | executive or kernel mode; an existing user or supervisor mode |
| 1003 | logical name is reset to the new value.) If the value is an empty |
| 1004 | string, the logical name's translation is defined as a single NUL |
| 1005 | (ASCII 00) character, since a logical name cannot translate to a |
| 1006 | zero-length string. (This restriction does not apply to CLI symbols |
| 1007 | or CRTL C<environ> values; they are set to the empty string.) |
| 1008 | An element of the CRTL C<environ> array can be set only if your |
| 1009 | copy of Perl knows about the CRTL's C<setenv()> function. (This is |
| 1010 | present only in some versions of the DECCRTL; check C<$Config{d_setenv}> |
| 1011 | to see whether your copy of Perl was built with a CRTL that has this |
| 1012 | function.) |
| 1013 | |
| 1014 | When an element of C<%ENV> is set to C<undef>, |
| 1015 | the element is looked up as if it were being read, and if it is |
| 1016 | found, it is deleted. (An item "deleted" from the CRTL C<environ> |
| 1017 | array is set to the empty string; this can only be done if your |
| 1018 | copy of Perl knows about the CRTL C<setenv()> function.) Using |
| 1019 | C<delete> to remove an element from C<%ENV> has a similar effect, |
| 1020 | but after the element is deleted, another attempt is made to |
| 1021 | look up the element, so an inner-mode logical name or a name in |
| 1022 | another location will replace the logical name just deleted. |
| 1023 | In either case, only the first value found searching PERL_ENV_TABLES |
| 1024 | is altered. It is not possible at present to define a search list |
| 1025 | logical name via %ENV. |
| 1026 | |
| 1027 | The element C<$ENV{DEFAULT}> is special: when read, it returns |
| 1028 | Perl's current default device and directory, and when set, it |
| 1029 | resets them, regardless of the definition of F<PERL_ENV_TABLES>. |
| 1030 | It cannot be cleared or deleted; attempts to do so are silently |
| 1031 | ignored. |
| 1032 | |
| 1033 | Note that if you want to pass on any elements of the |
| 1034 | C-local environ array to a subprocess which isn't |
| 1035 | started by fork/exec, or isn't running a C program, you |
| 1036 | can "promote" them to logical names in the current |
| 1037 | process, which will then be inherited by all subprocesses, |
| 1038 | by saying |
| 1039 | |
| 1040 | foreach my $key (qw[C-local keys you want promoted]) { |
| 1041 | my $temp = $ENV{$key}; # read from C-local array |
| 1042 | $ENV{$key} = $temp; # and define as logical name |
| 1043 | } |
| 1044 | |
| 1045 | (You can't just say C<$ENV{$key} = $ENV{$key}>, since the |
| 1046 | Perl optimizer is smart enough to elide the expression.) |
| 1047 | |
| 1048 | Don't try to clear C<%ENV> by saying C<%ENV = ();>, it will throw |
| 1049 | a fatal error. This is equivalent to doing the following from DCL: |
| 1050 | |
| 1051 | DELETE/LOGICAL * |
| 1052 | |
| 1053 | You can imagine how bad things would be if, for example, the SYS$MANAGER |
| 1054 | or SYS$SYSTEM logical names were deleted. |
| 1055 | |
| 1056 | At present, the first time you iterate over %ENV using |
| 1057 | C<keys>, or C<values>, you will incur a time penalty as all |
| 1058 | logical names are read, in order to fully populate %ENV. |
| 1059 | Subsequent iterations will not reread logical names, so they |
| 1060 | won't be as slow, but they also won't reflect any changes |
| 1061 | to logical name tables caused by other programs. |
| 1062 | |
| 1063 | You do need to be careful with the logical names representing |
| 1064 | process-permanent files, such as C<SYS$INPUT> and C<SYS$OUTPUT>. |
| 1065 | The translations for these logical names are prepended with a |
| 1066 | two-byte binary value (0x1B 0x00) that needs to be stripped off |
| 1067 | if you want to use it. (In previous versions of Perl it wasn't |
| 1068 | possible to get the values of these logical names, as the null |
| 1069 | byte acted as an end-of-string marker) |
| 1070 | |
| 1071 | =item $! |
| 1072 | |
| 1073 | The string value of C<$!> is that returned by the CRTL's |
| 1074 | strerror() function, so it will include the VMS message for |
| 1075 | VMS-specific errors. The numeric value of C<$!> is the |
| 1076 | value of C<errno>, except if errno is EVMSERR, in which |
| 1077 | case C<$!> contains the value of vaxc$errno. Setting C<$!> |
| 1078 | always sets errno to the value specified. If this value is |
| 1079 | EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so |
| 1080 | that the string value of C<$!> won't reflect the VMS error |
| 1081 | message from before C<$!> was set. |
| 1082 | |
| 1083 | =item $^E |
| 1084 | |
| 1085 | This variable provides direct access to VMS status values |
| 1086 | in vaxc$errno, which are often more specific than the |
| 1087 | generic Unix-style error messages in C<$!>. Its numeric value |
| 1088 | is the value of vaxc$errno, and its string value is the |
| 1089 | corresponding VMS message string, as retrieved by sys$getmsg(). |
| 1090 | Setting C<$^E> sets vaxc$errno to the value specified. |
| 1091 | |
| 1092 | While Perl attempts to keep the vaxc$errno value to be current, if |
| 1093 | errno is not EVMSERR, it may not be from the current operation. |
| 1094 | |
| 1095 | =item $? |
| 1096 | |
| 1097 | The "status value" returned in C<$?> is synthesized from the |
| 1098 | actual exit status of the subprocess in a way that approximates |
| 1099 | POSIX wait(5) semantics, in order to allow Perl programs to |
| 1100 | portably test for successful completion of subprocesses. The |
| 1101 | low order 8 bits of C<$?> are always 0 under VMS, since the |
| 1102 | termination status of a process may or may not have been |
| 1103 | generated by an exception. |
| 1104 | |
| 1105 | The next 8 bits contain the termination status of the program. |
| 1106 | |
| 1107 | If the child process follows the convention of C programs |
| 1108 | compiled with the _POSIX_EXIT macro set, the status value will |
| 1109 | contain the actual value of 0 to 255 returned by that program |
| 1110 | on a normal exit. |
| 1111 | |
| 1112 | With the _POSIX_EXIT macro set, the Unix exit value of zero is |
| 1113 | represented as a VMS native status of 1, and the Unix values |
| 1114 | from 2 to 255 are encoded by the equation: |
| 1115 | |
| 1116 | VMS_status = 0x35a000 + (unix_value * 8) + 1. |
| 1117 | |
| 1118 | And in the special case of Unix value 1 the encoding is: |
| 1119 | |
| 1120 | VMS_status = 0x35a000 + 8 + 2 + 0x10000000. |
| 1121 | |
| 1122 | For other termination statuses, the severity portion of the |
| 1123 | subprocess's exit status is used: if the severity was success or |
| 1124 | informational, these bits are all 0; if the severity was |
| 1125 | warning, they contain a value of 1; if the severity was |
| 1126 | error or fatal error, they contain the actual severity bits, |
| 1127 | which turns out to be a value of 2 for error and 4 for severe_error. |
| 1128 | Fatal is another term for the severe_error status. |
| 1129 | |
| 1130 | As a result, C<$?> will always be zero if the subprocess's exit |
| 1131 | status indicated successful completion, and non-zero if a |
| 1132 | warning or error occurred or a program compliant with encoding |
| 1133 | _POSIX_EXIT values was run and set a status. |
| 1134 | |
| 1135 | How can you tell the difference between a non-zero status that is |
| 1136 | the result of a VMS native error status or an encoded Unix status? |
| 1137 | You can not unless you look at the ${^CHILD_ERROR_NATIVE} value. |
| 1138 | The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value |
| 1139 | and check the severity bits. If the severity bits are equal to 1, |
| 1140 | then if the numeric value for C<$?> is between 2 and 255 or 0, then |
| 1141 | C<$?> accurately reflects a value passed back from a Unix application. |
| 1142 | If C<$?> is 1, and the severity bits indicate a VMS error (2), then |
| 1143 | C<$?> is from a Unix application exit value. |
| 1144 | |
| 1145 | In practice, Perl scripts that call programs that return _POSIX_EXIT |
| 1146 | type status values will be expecting those values, and programs that |
| 1147 | call traditional VMS programs will either be expecting the previous |
| 1148 | behavior or just checking for a non-zero status. |
| 1149 | |
| 1150 | And success is always the value 0 in all behaviors. |
| 1151 | |
| 1152 | When the actual VMS termination status of the child is an error, |
| 1153 | internally the C<$!> value will be set to the closest Unix errno |
| 1154 | value to that error so that Perl scripts that test for error |
| 1155 | messages will see the expected Unix style error message instead |
| 1156 | of a VMS message. |
| 1157 | |
| 1158 | Conversely, when setting C<$?> in an END block, an attempt is made |
| 1159 | to convert the POSIX value into a native status intelligible to |
| 1160 | the operating system upon exiting Perl. What this boils down to |
| 1161 | is that setting C<$?> to zero results in the generic success value |
| 1162 | SS$_NORMAL, and setting C<$?> to a non-zero value results in the |
| 1163 | generic failure status SS$_ABORT. See also L<perlport/exit>. |
| 1164 | |
| 1165 | With the C<PERL_VMS_POSIX_EXIT> logical name defined as "ENABLE", |
| 1166 | setting C<$?> will cause the new value to be encoded into C<$^E> |
| 1167 | so that either the original parent or child exit status values |
| 1168 | 0 to 255 can be automatically recovered by C programs expecting |
| 1169 | _POSIX_EXIT behavior. If both a parent and a child exit value are |
| 1170 | non-zero, then it will be assumed that this is actually a VMS native |
| 1171 | status value to be passed through. The special value of 0xFFFF is |
| 1172 | almost a NOOP as it will cause the current native VMS status in the |
| 1173 | C library to become the current native Perl VMS status, and is handled |
| 1174 | this way as it is known to not be a valid native VMS status value. |
| 1175 | It is recommend that only values in the range of normal Unix parent or |
| 1176 | child status numbers, 0 to 255 are used. |
| 1177 | |
| 1178 | The pragma C<use vmsish 'status'> makes C<$?> reflect the actual |
| 1179 | VMS exit status instead of the default emulation of POSIX status |
| 1180 | described above. This pragma also disables the conversion of |
| 1181 | non-zero values to SS$_ABORT when setting C<$?> in an END |
| 1182 | block (but zero will still be converted to SS$_NORMAL). |
| 1183 | |
| 1184 | Do not use the pragma C<use vmsish 'status'> with C<PERL_VMS_POSIX_EXIT> |
| 1185 | enabled, as they are at times requesting conflicting actions and the |
| 1186 | consequence of ignoring this advice will be undefined to allow future |
| 1187 | improvements in the POSIX exit handling. |
| 1188 | |
| 1189 | In general, with C<PERL_VMS_POSIX_EXIT> enabled, more detailed information |
| 1190 | will be available in the exit status for DCL scripts or other native VMS tools, |
| 1191 | and will give the expected information for Posix programs. It has not been |
| 1192 | made the default in order to preserve backward compatibility. |
| 1193 | |
| 1194 | N.B. Setting C<DECC$FILENAME_UNIX_REPORT> implicitly enables |
| 1195 | C<PERL_VMS_POSIX_EXIT>. |
| 1196 | |
| 1197 | =item $| |
| 1198 | |
| 1199 | Setting C<$|> for an I/O stream causes data to be flushed |
| 1200 | all the way to disk on each write (I<i.e.> not just to |
| 1201 | the underlying RMS buffers for a file). In other words, |
| 1202 | it's equivalent to calling fflush() and fsync() from C. |
| 1203 | |
| 1204 | =back |
| 1205 | |
| 1206 | =head1 Standard modules with VMS-specific differences |
| 1207 | |
| 1208 | =head2 SDBM_File |
| 1209 | |
| 1210 | SDBM_File works properly on VMS. It has, however, one minor |
| 1211 | difference. The database directory file created has a F<.sdbm_dir> |
| 1212 | extension rather than a F<.dir> extension. F<.dir> files are VMS filesystem |
| 1213 | directory files, and using them for other purposes could cause unacceptable |
| 1214 | problems. |
| 1215 | |
| 1216 | =head1 Revision date |
| 1217 | |
| 1218 | Please see the git repository for revision history. |
| 1219 | |
| 1220 | =head1 AUTHOR |
| 1221 | |
| 1222 | Charles Bailey bailey@cor.newman.upenn.edu |
| 1223 | Craig Berry craigberry@mac.com |
| 1224 | Dan Sugalski dan@sidhe.org |
| 1225 | John Malmberg wb8tyw@qsl.net |