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