better VMS docs for $?, exit(), and system()

Message-Id: <5.1.0.14.0.20010807155648.01ba3c98@exchi01>

p4raw-id: //depot/perl@11610

1 files changed, 21 insertions, 8 deletions

diff --git a/vms/perlvms.pod b/vms/perlvms.pod
index 4db64d4666..080c03d335 100644
--- a/vms/perlvms.pod
+++ b/vms/perlvms.pod
@@ -17,7 +17,7 @@ subdirectory of the Perl distribution.
 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@newman.upenn.edu.
+hesitate to drop a line to vmsperl@perl.org.
 
 =head1 Installation
 
@@ -486,7 +486,7 @@ 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, 
+subprocesses is not recommended under VMS; wherever possible, 
 use the C<system> operator or piped filehandles instead.
 
 =item getpwent
@@ -841,14 +841,26 @@ 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;
-otherwise, they contain the severity value shifted left one bit.
+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.  
+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.
+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 $|
 
@@ -871,10 +883,11 @@ problems.
 
 =head1 Revision date
 
-This document was last updated on 26-Feb-2000, for Perl 5, 
-patchlevel 6.
+This document was last updated on 7-Aug-2001, for Perl 5, 
+patchlevel 8.
 
 =head1 AUTHOR
 
 Charles Bailey  <bailey@cor.newman.upenn.edu>
+Craig Berry  <craigberry@mac.com>
 Dan Sugalski  <dan@sidhe.org>