We hope these notes will save you from confusion and lost
sleep when writing Perl scripts on VMS. If you find we've
missed something you think should appear here, please don't
-hesitate to drop a line to vmsperl@genetics.upenn.edu.
+hesitate to drop a line to vmsperl@perl.org.
=head1 Installation
Perl extensions are packages which provide both XS and Perl code
to add new functionality to perl. (XS is a meta-language which
simplifies writing C code which interacts with Perl, see
-L<perlapi> for more details.) The Perl code for an
+L<perlxs> for more details.) The Perl code for an
extension is treated like any other library module - it's
made available in your script through the appropriate
C<use> or C<require> statement, and usually defines a Perl
I<N.B.> The procedure by which extensions are built and
tested creates several levels (at least 4) under the
directory in which the extension's source files live.
-For this reason, you shouldn't nest the source directory
-too deeply in your directory structure, lest you eccedd RMS'
+For this reason if you are running a version of VMS prior
+to V7.1 you shouldn't nest the source directory
+too deeply in your directory structure lest you exceed RMS'
maximum of 8 levels of subdirectory in a filespec. (You
can use rooted logical names to get another 8 levels of
nesting, if you can't place the files near the top of
be added to the linker options file F<PGPLOT.Opt> produced
during the build process for the Perl extension.
-By default, the shareable image for an extension is placed
-in the F<[.Lib.Auto.>I<Arch>.I<Extname>F<]> directory of the
+By default, the shareable image for an extension is placed in
+the F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the
installed Perl directory tree (where I<Arch> is F<VMS_VAX> or
-F<VMS_AXP>, followed by the Perl version number, and I<Extname>
-is the name of the extension, with each C<::> translated to C<.>).
+F<VMS_AXP>, and I<Extname> is the name of the extension, with
+each C<::> translated to C<.>). (See the MakeMaker documentation
+for more details on installation options for extensions.)
However, it can be manually placed in any of several locations:
- - the F<[.Lib.Auto.>I<Extname>F<]> subdirectory of one of
- the directories in C<@INC>, or
- - one of the directories in C<@INC>, or
- - a directory which the extensions Perl library module
- passes to the DynaLoader when asking it to map
- the shareable image, or
- - F<Sys$Share> or F<Sys$Library>.
+
+=over 4
+
+=item *
+
+the F<[.Lib.Auto.>I<Arch>I<$PVers>I<Extname>F<]> subdirectory
+of one of the directories in C<@INC> (where I<PVers>
+is the version of Perl you're using, as supplied in C<$]>,
+with '.' converted to '_'), or
+
+=item *
+
+one of the directories in C<@INC>, or
+
+=item *
+
+a directory which the extensions Perl library module
+passes to the DynaLoader when asking it to map
+the shareable image, or
+
+=item *
+
+F<Sys$Share> or F<Sys$Library>.
+
+=back
+
If the shareable image isn't in any of these places, you'll need
to define a logical name I<Extshortname>, where I<Extshortname>
is the portion of the extension's name after the last C<::>, which
We have tried to make Perl aware of both VMS-style and Unix-
style file specifications wherever possible. You may use
either style, or both, on the command line and in scripts,
-but you may not combine the two styles within a single fle
+but you may not combine the two styles within a single file
specification. VMS Perl interprets Unix pathnames in much
the same way as the CRTL (I<e.g.> the first component of
an absolute path is read as the device name for the
=head2 Wildcard expansion
File specifications containing wildcards are allowed both on
-the command line and within Perl globs (e.g. <CE<lt>*.cE<gt>>). If
+the command line and within Perl globs (e.g. C<E<lt>*.cE<gt>>). If
the wildcard filespec uses VMS syntax, the resultant
filespecs will follow VMS syntax; if a Unix-style filespec is
passed in, Unix-style filespecs will be returned.
+Similar to the behavior of wildcard globbing for a Unix shell,
+one can escape command line wildcards with double quotation
+marks C<"> around a perl program command line argument. However,
+owing to the stripping of C<"> characters carried out by the C
+handling of argv you will need to escape a construct such as
+this one (in a directory containing the files F<PERL.C>, F<PERL.EXE>,
+F<PERL.H>, and F<PERL.OBJ>):
+
+ $ perl -e "print join(' ',@ARGV)" perl.*
+ perl.c perl.exe perl.h perl.obj
+
+in the following triple quoted manner:
+ $ perl -e "print join(' ',@ARGV)" """perl.*"""
+ perl.*
+
+In both the case of unquoted command line arguments or in calls
+to C<glob()> VMS wildcard expansion is performed. (csh-style
+wildcard expansion is available if you use C<File::Glob::glob>.)
If the wildcard filespec contains a device or directory
specification, then the resultant filespecs will also contain
a device and directory; otherwise, device and directory
You may also use backticks to invoke a DCL subprocess, whose
output is used as the return value of the expression. The
-string between the backticks is passed directly to lib$spawn
-as the command to execute. In this case, Perl will wait for
-the subprocess to complete before continuing.
+string between the backticks is handled as if it were the
+argument to the C<system> operator (see below). In this case,
+Perl will wait for the subprocess to complete before continuing.
+
+The mailbox (MBX) that perl can create to communicate with a pipe
+defaults to a buffer size of 512. The default buffer size is
+adjustable via the logical name PERL_MBX_SIZE provided that the
+value falls between 128 and the SYSGEN parameter MAXBUF inclusive.
+For example, to double the MBX size from the default within
+a Perl program, use C<$ENV{'PERL_MBX_SIZE'} = 1024;> and then
+open and use pipe constructs. An alternative would be to issue
+the command:
+
+ $ Define PERL_MBX_SIZE 1024
+
+before running your wide record pipe program. A larger value may
+improve performance at the expense of the BYTLM UAF quota.
=head1 PERL5LIB and PERLLIB
-The PERL5LIB and PERLLIB logical names work as documented L<perl>,
+The PERL5LIB and PERLLIB logical names work as documented in L<perl>,
except that the element separator is '|' instead of ':'. The
directory specifications may use either VMS or Unix syntax.
Perl for VMS supports redirection of input and output on the
command line, using a subset of Bourne shell syntax:
- <F<file> reads stdin from F<file>,
- >F<file> writes stdout to F<file>,
- >>F<file> appends stdout to F<file>,
- 2>F<file> writes stderr to F<file>, and
- 2>>F<file> appends stderr to F<file>.
+
+=over 4
+
+=item *
+
+C<E<lt>file> reads stdin from C<file>,
+
+=item *
+
+C<E<gt>file> writes stdout to C<file>,
+
+=item *
+
+C<E<gt>E<gt>file> appends stdout to C<file>,
+
+=item *
+
+C<2E<gt>file> writes stderr to C<file>,
+
+=item *
+
+C<2E<gt>E<gt>file> appends stderr to C<file>, and
+
+=item *
+
+C<< 2>&1 >> redirects stderr to stdout.
+
+=back
In addition, output may be piped to a subprocess, using the
character '|'. Anything after this character on the command
them in double-quotes on the command line, since the CRTL
downcases all unquoted strings.
+=over 4
+
+=item -i
+
+If the C<-i> switch is present but no extension for a backup
+copy is given, then inplace editing creates a new version of
+a file; the existing copy is not deleted. (Note that if
+an extension is given, an existing file is renamed to the backup
+file, as is the case under other operating systems, so it does
+not remain as a previous version under the original filename.)
+
=item -S
-If the C<-S> switch is present I<and> the script name does
-not contain a directory, then Perl translates the logical
-name DCL$PATH as a searchlist, using each translation as
-a directory in which to look for the script. In addition,
+If the C<"-S"> or C<-"S"> switch is present I<and> the script
+name does not contain a directory, then Perl translates the
+logical name DCL$PATH as a searchlist, using each translation
+as a directory in which to look for the script. In addition,
if no file type is specified, Perl looks in each directory
for a file matching the name specified, with a blank type,
a type of F<.pl>, and a type of F<.com>, in that order.
after the Perl program is compiled, but before it has
run. It does not create a core dump file.
+=back
+
=head1 Perl functions
As of the time this document was last revised, the following
Perl functions were implemented in the VMS port of Perl
(functions marked with * are discussed in more detail below):
- file tests*, abs, alarm, atan, binmode*, bless,
+ file tests*, abs, alarm, atan, backticks*, binmode*, bless,
caller, chdir, chmod, chown, chomp, chop, chr,
close, closedir, cos, crypt*, defined, delete,
die, do, dump*, each, endpwent, eof, eval, exec*,
- exists, exit, exp, fileno, fork*, getc, getlogin,
+ exists, exit, exp, fileno, getc, getlogin, getppid,
getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
grep, hex, import, index, int, join, keys, kill*,
last, lc, lcfirst, length, local, localtime, log, m//,
map, mkdir, my, next, no, oct, open, opendir, ord, pack,
pipe, pop, pos, print, printf, push, q//, qq//, qw//,
- qx//, quotemeta, rand, read, readdir, redo, ref, rename,
+ qx//*, quotemeta, rand, read, readdir, redo, ref, rename,
require, reset, return, reverse, rewinddir, rindex,
rmdir, s///, scalar, seek, seekdir, select(internal),
select (system call)*, setpwent, shift, sin, sleep,
and calling them produces a fatal error (usually) or
undefined behavior (rarely, we hope):
- chroot, dbmclose, dbmopen, fcntl, flock,
- getpgrp, getppid, getpriority, getgrent, getgrgid,
+ chroot, dbmclose, dbmopen, flock, fork*,
+ getpgrp, getpriority, getgrent, getgrgid,
getgrnam, setgrent, endgrent, ioctl, link, lstat,
msgctl, msgget, msgsend, msgrcv, readlink, semctl,
semget, semop, setpgrp, setpriority, shmctl, shmget,
- shmread, shmwrite, socketpair, symlink, syscall, truncate
+ shmread, shmwrite, socketpair, symlink, syscall
+
+The following functions are available on Perls compiled with Dec C
+5.2 or greater and running VMS 7.0 or greater:
+
+ truncate
+
+The following functions are available on Perls built on VMS 7.2 or
+greater:
+
+ fcntl (without locking)
The following functions may or may not be implemented,
depending on what type of socket support you've built into
getsockopt, listen, recv, select(system call)*,
send, setsockopt, shutdown, socket
+=over 4
=item File tests
your C compiler's F<stat.h>, in the mode value it returns, if you
need an approximation of the file's protections.
+=item backticks
+
+Backticks create a subprocess, and pass the enclosed string
+to it for execution as a DCL command. Since the subprocess is
+created directly via C<lib$spawn()>, any valid DCL command string
+may be specified.
+
=item binmode FILEHANDLE
The C<binmode> operator will attempt to insure that no translation
password strings; you'll have to upcase the arguments to
C<crypt> to insure that you'll get the proper value:
- sub validate_passwd {
- my($user,$passwd) = @_;
- my($pwdhash);
- if ( !($pwdhash = (getpwnam($user))[1]) ||
- $pwdhash ne crypt("\U$passwd","\U$name") ) {
- intruder_alert($name);
+ sub validate_passwd {
+ my($user,$passwd) = @_;
+ my($pwdhash);
+ if ( !($pwdhash = (getpwnam($user))[1]) ||
+ $pwdhash ne crypt("\U$passwd","\U$name") ) {
+ intruder_alert($name);
+ }
+ return 1;
}
- return 1;
- }
=item dump
=item exec LIST
-The C<exec> operator behaves in one of two different ways.
-If called after a call to C<fork>, it will invoke the CRTL
-C<execv()> routine, passing its arguments to the subprocess
-created by C<fork> for execution. In this case, it is
-subject to all limitations that affect C<execv()>. (In
-particular, this usually means that the command executed in
-the subprocess must be an image compiled from C source code,
-and that your options for passing file descriptors and signal
-handlers to the subprocess are limited.)
-
-If the call to C<exec> does not follow a call to C<fork>, it
-will cause Perl to exit, and to invoke the command given as
-an argument to C<exec> via C<lib$do_command>. If the argument
-begins with a '$' (other than as part of a filespec), then it
-is executed as a DCL command. Otherwise, the first token on
-the command line is treated as the filespec of an image to
-run, and an attempt is made to invoke it (using F<.Exe> and
-the process defaults to expand the filespec) and pass the
-rest of C<exec>'s argument to it as parameters.
-
-You can use C<exec> in both ways within the same script, as
-long as you call C<fork> and C<exec> in pairs. Perl
-keeps track of how many times C<fork> and C<exec> have been
-called, and will call the CRTL C<execv()> routine if there have
-previously been more calls to C<fork> than to C<exec>.
+A call to C<exec> will cause Perl to exit, and to invoke the command
+given as an argument to C<exec> via C<lib$do_command>. If the
+argument begins with '@' or '$' (other than as part of a filespec),
+then it is executed as a DCL command. Otherwise, the first token on
+the command line is treated as the filespec of an image to run, and
+an attempt is made to invoke it (using F<.Exe> and the process
+defaults to expand the filespec) and pass the rest of C<exec>'s
+argument to it as parameters. If the token has no file type, and
+matches a file with null type, then an attempt is made to determine
+whether the file is an executable image which should be invoked
+using C<MCR> or a text file which should be passed to DCL as a
+command procedure.
=item fork
-The C<fork> operator works in the same way as the CRTL
-C<vfork()> routine, which is quite different under VMS than
-under Unix. Specifically, while C<fork> returns 0 after it
-is called and the subprocess PID after C<exec> is called, in
-both cases the thread of execution is within the parent
-process, so there is no opportunity to perform operations in
-the subprocess before calling C<exec>.
-
-In general, the use of C<fork> and C<exec> to create
-subprocess is not recommended under VMS; wherever possible,
-use the C<system> operator or piped filehandles instead.
+While in principle the C<fork> operator could be implemented via
+(and with the same rather severe limitations as) the CRTL C<vfork()>
+routine, and while some internal support to do just that is in
+place, the implementation has never been completed, making C<fork>
+currently unavailable. A true kernel C<fork()> is expected in a
+future version of VMS, and the pseudo-fork based on interpreter
+threads may be available in a future version of Perl on VMS (see
+L<perlfork>). In the meantime, use C<system>, backticks, or piped
+filehandles to create subprocesses.
=item getpwent
=item kill
-In most cases, C<kill> kill is implemented via the CRTL's C<kill()>
+In most cases, C<kill> is implemented via the CRTL's C<kill()>
function, so it will behave according to that function's
documentation. If you send a SIGKILL, however, the $DELPRC system
-service is is called directly. This insures that the target
+service is called directly. This insures that the target
process is actually deleted, if at all possible. (The CRTL's C<kill()>
function is presently implemented via $FORCEX, which is ignored by
supervisor-mode images like DCL.)
Also, negative signal values don't do anything special under
VMS; they're just converted to the corresponding positive value.
+=item qx//
+
+See the entry on C<backticks> above.
+
=item select (system call)
If Perl was not built with socket support, the system call
The C<system> operator creates a subprocess, and passes its
arguments to the subprocess for execution as a DCL command.
Since the subprocess is created directly via C<lib$spawn()>, any
-valid DCL command string may be specified. If LIST consists
-of the empty string, C<system> spawns an interactive DCL subprocess,
-in the same fashion as typiing B<SPAWN> at the DCL prompt.
+valid DCL command string may be specified. If the string begins with
+'@', it is treated as a DCL command unconditionally. Otherwise, if
+the first token contains a character used as a delimiter in file
+specification (e.g. C<:> or C<]>), an attempt is made to expand it
+using a default type of F<.Exe> and the process defaults, and if
+successful, the resulting file is invoked via C<MCR>. This allows you
+to invoke an image directly simply by passing the file specification
+to C<system>, a common Unixish idiom. If the token has no file type,
+and matches a file with null type, then an attempt is made to
+determine whether the file is an executable image which should be
+invoked using C<MCR> or a text file which should be passed to DCL
+as a command procedure.
+
+If LIST consists of the empty string, C<system> spawns an
+interactive DCL subprocess, in the same fashion as typing
+B<SPAWN> at the DCL prompt.
+
Perl waits for the subprocess to complete before continuing
-execution in the current process.
+execution in the current process. As described in L<perlfunc>,
+the return value of C<system> is a fake "status" which follows
+POSIX semantics unless the pragma C<use vmsish 'status'> is in
+effect; see the description of C<$?> in this document for more
+detail.
=item time
according to the same rules the CRTL C<times()> routine.
Therefore, the "system time" elements will always be 0, since
there is no difference between "user time" and "system" time
-under VMS, and the time accumulated by subprocess may or may
+under VMS, and the time accumulated by a subprocess may or may
not appear separately in the "child time" field, depending on
whether L<times> keeps track of subprocesses separately. Note
especially that the VAXCRTL (at least) keeps track only of
subprocesses spawned using L<fork> and L<exec>; it will not
-accumulate the times of suprocesses spawned via pipes, L<system>,
+accumulate the times of subprocesses spawned via pipes, L<system>,
or backticks.
=item unlink LIST
C<unlink> will delete the highest version of a file only; in
order to delete all versions, you need to say
- 1 while (unlink LIST);
+
+ 1 while unlink LIST;
+
You may need to make this change to scripts written for a
Unix system which expect that after a call to C<unlink>,
no files with the names passed to C<unlink> will exist.
=item waitpid PID,FLAGS
-If PID is a subprocess started by a piped L<open>, C<waitpid>
-will wait for that subprocess, and return its final
-status value. If PID is a subprocess created in some other way
-(e.g. SPAWNed before Perl was invoked), or is not a subprocess of
-the current process, C<waitpid> will check once per second whether
-the process has completed, and when it has, will return 0. (If PID
-specifies a process that isn't a subprocess of the current process,
+If PID is a subprocess started by a piped C<open()> (see L<open>),
+C<waitpid> will wait for that subprocess, and return its final status
+value in C<$?>. If PID is a subprocess created in some other way (e.g.
+SPAWNed before Perl was invoked), C<waitpid> will simply check once per
+second whether the process has completed, and return when it has. (If
+PID specifies a process that isn't a subprocess of the current process,
and you invoked Perl with the C<-w> switch, a warning will be issued.)
-The FLAGS argument is ignored in all cases.
+Returns PID on success, -1 on error. The FLAGS argument is ignored
+in all cases.
+
+=back
=head1 Perl variables
+The following VMS-specific information applies to the indicated
+"special" Perl variables, in addition to the general information
+in L<perlvar>. Where there is a conflict, this information
+takes precedence.
+
+=over 4
+
=item %ENV
-Reading the elements of the %ENV array returns the
-translation of the logical name specified by the key,
-according to the normal search order of access modes and
-logical name tables. If you append a semicolon to the
-logical name, followed by an integer, that integer is
-used as the translation index for the logical name,
-so that you can look up successive values for search
-list logical names. For instance, if you say
+The operation of the C<%ENV> array depends on the translation
+of the logical name F<PERL_ENV_TABLES>. If defined, it should
+be a search list, each element of which specifies a location
+for C<%ENV> elements. If you tell Perl to read or set the
+element C<$ENV{>I<name>C<}>, then Perl uses the translations of
+F<PERL_ENV_TABLES> as follows:
- $ Define STORY once,upon,a,time,there,was
- $ perl -e "for ($i = 0; $i <= 6; $i++) " -
- _$ -e "{ print $ENV{'foo'.$i},' '}"
-
-Perl will print C<ONCE UPON A TIME THERE WAS>.
-
-The %ENV keys C<home>, C<path>,C<term>, and C<user>
-return the CRTL "environment variables" of the same
-names, if these logical names are not defined. The
-key C<default> returns the current default device
-and directory specification, regardless of whether
-there is a logical name DEFAULT defined..
-
-Setting an element of %ENV defines a supervisor-mode logical
-name in the process logical name table. C<Undef>ing or
-C<delete>ing an element of %ENV deletes the equivalent user-
-mode or supervisor-mode logical name from the process logical
-name table. If you use C<undef>, the %ENV element remains
-empty. If you use C<delete>, another attempt is made at
-logical name translation after the deletion, so an inner-mode
-logical name or a name in another logical name table will
-replace the logical name just deleted. It is not possible
-at present to define a search list logical name via %ENV.
+=over 4
+
+=item CRTL_ENV
+
+This string tells Perl to consult the CRTL's internal C<environ>
+array of key-value pairs, using I<name> as the key. In most cases,
+this contains only a few keys, but if Perl was invoked via the C
+C<exec[lv]e()> function, as is the case for CGI processing by some
+HTTP servers, then the C<environ> array may have been populated by
+the calling program.
+
+=item CLISYM_[LOCAL]
+
+A string beginning with C<CLISYM_>tells Perl to consult the CLI's
+symbol tables, using I<name> as the name of the symbol. When reading
+an element of C<%ENV>, the local symbol table is scanned first, followed
+by the global symbol table.. The characters following C<CLISYM_> are
+significant when an element of C<%ENV> is set or deleted: if the
+complete string is C<CLISYM_LOCAL>, the change is made in the local
+symbol table; otherwise the global symbol table is changed.
+
+=item Any other string
+
+If an element of F<PERL_ENV_TABLES> translates to any other string,
+that string is used as the name of a logical name table, which is
+consulted using I<name> as the logical name. The normal search
+order of access modes is used.
+
+=back
+
+F<PERL_ENV_TABLES> is translated once when Perl starts up; any changes
+you make while Perl is running do not affect the behavior of C<%ENV>.
+If F<PERL_ENV_TABLES> is not defined, then Perl defaults to consulting
+first the logical name tables specified by F<LNM$FILE_DEV>, and then
+the CRTL C<environ> array.
In all operations on %ENV, the key string is treated as if it
were entirely uppercase, regardless of the case actually
specified in the Perl expression.
-=item $?
+When an element of C<%ENV> is read, the locations to which
+F<PERL_ENV_TABLES> points are checked in order, and the value
+obtained from the first successful lookup is returned. If the
+name of the C<%ENV> element contains a semi-colon, it and
+any characters after it are removed. These are ignored when
+the CRTL C<environ> array or a CLI symbol table is consulted.
+However, the name is looked up in a logical name table, the
+suffix after the semi-colon is treated as the translation index
+to be used for the lookup. This lets you look up successive values
+for search list logical names. For instance, if you say
+
+ $ Define STORY once,upon,a,time,there,was
+ $ perl -e "for ($i = 0; $i <= 6; $i++) " -
+ _$ -e "{ print $ENV{'story;'.$i},' '}"
+
+Perl will print C<ONCE UPON A TIME THERE WAS>, assuming, of course,
+that F<PERL_ENV_TABLES> is set up so that the logical name C<story>
+is found, rather than a CLI symbol or CRTL C<environ> element with
+the same name.
+
+When an element of C<%ENV> is set to a defined string, the
+corresponding definition is made in the location to which the
+first translation of F<PERL_ENV_TABLES> points. If this causes a
+logical name to be created, it is defined in supervisor mode.
+(The same is done if an existing logical name was defined in
+executive or kernel mode; an existing user or supervisor mode
+logical name is reset to the new value.) If the value is an empty
+string, the logical name's translation is defined as a single NUL
+(ASCII 00) character, since a logical name cannot translate to a
+zero-length string. (This restriction does not apply to CLI symbols
+or CRTL C<environ> values; they are set to the empty string.)
+An element of the CRTL C<environ> array can be set only if your
+copy of Perl knows about the CRTL's C<setenv()> function. (This is
+present only in some versions of the DECCRTL; check C<$Config{d_setenv}>
+to see whether your copy of Perl was built with a CRTL that has this
+function.)
+
+When an element of C<%ENV> is set to C<undef>,
+the element is looked up as if it were being read, and if it is
+found, it is deleted. (An item "deleted" from the CRTL C<environ>
+array is set to the empty string; this can only be done if your
+copy of Perl knows about the CRTL C<setenv()> function.) Using
+C<delete> to remove an element from C<%ENV> has a similar effect,
+but after the element is deleted, another attempt is made to
+look up the element, so an inner-mode logical name or a name in
+another location will replace the logical name just deleted.
+In either case, only the first value found searching PERL_ENV_TABLES
+is altered. It is not possible at present to define a search list
+logical name via %ENV.
+
+The element C<$ENV{DEFAULT}> is special: when read, it returns
+Perl's current default device and directory, and when set, it
+resets them, regardless of the definition of F<PERL_ENV_TABLES>.
+It cannot be cleared or deleted; attempts to do so are silently
+ignored.
+
+Note that if you want to pass on any elements of the
+C-local environ array to a subprocess which isn't
+started by fork/exec, or isn't running a C program, you
+can "promote" them to logical names in the current
+process, which will then be inherited by all subprocesses,
+by saying
+
+ foreach my $key (qw[C-local keys you want promoted]) {
+ my $temp = $ENV{$key}; # read from C-local array
+ $ENV{$key} = $temp; # and define as logical name
+ }
+
+(You can't just say C<$ENV{$key} = $ENV{$key}>, since the
+Perl optimizer is smart enough to elide the expression.)
+
+Don't try to clear C<%ENV> by saying C<%ENV = ();>, it will throw
+a fatal error. This is equivalent to doing the following from DCL:
+
+ DELETE/LOGICAL *
+
+You can imagine how bad things would be if, for example, the SYS$MANAGER
+or SYS$SYSTEM logicals were deleted.
-Since VMS status values are 32 bits wide, the value of C<$?>
-is simply the final status value of the last subprocess to
-complete. This differs from the behavior of C<$?> under Unix,
-and under VMS' POSIX environment, in that the low-order 8 bits
-of C<$?> do not specify whether the process terminated normally
-or due to a signal, and you do not need to shift C<$?> 8 bits
-to the right in order to find the process' exit status.
+At present, the first time you iterate over %ENV using
+C<keys>, or C<values>, you will incur a time penalty as all
+logical names are read, in order to fully populate %ENV.
+Subsequent iterations will not reread logical names, so they
+won't be as slow, but they also won't reflect any changes
+to logical name tables caused by other programs.
+
+You do need to be careful with the logicals representing process-permanent
+files, such as C<SYS$INPUT> and C<SYS$OUTPUT>. The translations for these
+logicals are prepended with a two-byte binary value (0x1B 0x00) that needs to be
+stripped off if you want to use it. (In previous versions of Perl it wasn't
+possible to get the values of these logicals, as the null byte acted as an
+end-of-string marker)
=item $!
corresponding VMS message string, as retrieved by sys$getmsg().
Setting C<$^E> sets vaxc$errno to the value specified.
+=item $?
+
+The "status value" returned in C<$?> is synthesized from the
+actual exit status of the subprocess in a way that approximates
+POSIX wait(5) semantics, in order to allow Perl programs to
+portably test for successful completion of subprocesses. The
+low order 8 bits of C<$?> are always 0 under VMS, since the
+termination status of a process may or may not have been
+generated by an exception. The next 8 bits are derived from
+the severity portion of the subprocess' exit status: if the
+severity was success or informational, these bits are all 0;
+if the severity was warning, they contain a value of 1; if the
+severity was error or fatal error, they contain the actual
+severity bits, which turns out to be a value of 2 for error
+and 4 for fatal error.
+
+As a result, C<$?> will always be zero if the subprocess' exit
+status indicated successful completion, and non-zero if a
+warning or error occurred. Conversely, when setting C<$?> in
+an END block, an attempt is made to convert the POSIX value
+into a native status intelligible to the operating system upon
+exiting Perl. What this boils down to is that setting C<$?>
+to zero results in the generic success value SS$_NORMAL, and
+setting C<$?> to a non-zero value results in the generic
+failure status SS$_ABORT. See also L<perlport/exit>.
+
+The pragma C<use vmsish 'status'> makes C<$?> reflect the actual
+VMS exit status instead of the default emulation of POSIX status
+described above. This pragma also disables the conversion of
+non-zero values to SS$_ABORT when setting C<$?> in an END
+block (but zero will still be converted to SS$_NORMAL).
+
=item $|
Setting C<$|> for an I/O stream causes data to be flushed
the underlying RMS buffers for a file). In other words,
it's equivalent to calling fflush() and fsync() from C.
+=back
+
+=head1 Standard modules with VMS-specific differences
+
+=head2 SDBM_File
+
+SDBM_File works properly on VMS. It has, however, one minor
+difference. The database directory file created has a F<.sdbm_dir>
+extension rather than a F<.dir> extension. F<.dir> files are VMS filesystem
+directory files, and using them for other purposes could cause unacceptable
+problems.
+
=head1 Revision date
-This document was last updated on 28-Feb-1996, for Perl 5,
-patchlevel 2.
+This document was last updated on 01-May-2002, for Perl 5,
+patchlevel 8.
=head1 AUTHOR
-Charles Bailey bailey@genetics.upenn.edu
-
+Charles Bailey bailey@cor.newman.upenn.edu
+Craig Berry craigberry@mac.com
+Dan Sugalski dan@sidhe.org
projects / p5sagit/p5-mst-13.2.git / blobdiff