[Summary view] [Print] [Text view]

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