[inseparable changes from patch to perl 5.004_04]perl-5.004_04

[editor's note: this one imported like a charm!]

 TESTS  -

Subject: Improve pragma/locale test 102 - and don't fail, just warn
From: Jarkko Hietaniemi <jhi@anna.in-berlin.de>
Files: t/pragma/locale.t

Subject: Invalid test output in t/op/taint.t in trial 1
From: Dan Sugalski <sugalsd@lbcc.cc.or.us>
Files: t/op/taint.t

    t/op/taint.t prints out invalid ok messages for tests it skips.
    Rather than printing "ok 136" it prints "136 ok".
    
    p5p-msgid: 3.0.3.32.19970919160918.00857a50@stargate.lbcc.cc.or.us

 UTILITIES  -

Subject: Perldoc tiny patch to avoid $0
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: utils/perldoc.PL
Msg-ID: 199709122141.RAA16846@monk.mps.ohio-state.edu

    (applied based on p5p patch as commit 0b166b6635cf199f072db516b2a523ee659394d5)

Subject: h2ph broken in 5.004_02
From: David Mazieres <dm@reeducation-labor.lcs.mit.edu>
Files: utils/h2ph.PL
Msg-ID: 199708201700.KAA02621@www.chapin.edu

    (applied based on p5p patch as commit 4a8e146e38ec2045f1f817a7cb578e1b1f80f39f)

Subject: add key_t caddr_t to h2ph
From: Tony Sanders <sanders@bsdi.com>
Files: eg/sysvipc/ipcsem utils/h2ph.PL
Msg-ID: 199708272301.RAA12803@austin.bsdi.com

    (applied based on p5p patch as commit 0806a92ffc3a74ca70aa81051cdf2a306cd0a8af)

Subject: perldoc search ., lib and blib/* if -f 'Makefile.PL'
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

    Subject: perldoc finds wrong pod2man
    
    (from perldoc source)
    
        # We must look both in @INC for library modules and in PATH
        # for executables, like h2xs or perldoc itself.
    
    Unfortunately, searching PATH for installed perl executables like
    pod2man is INCORRECT.  perldoc should start by searching the
    directory it was executed from, which might not be in the PATH
    at all.
    
    Credited: Joseph "Moof-in'" Hall <joseph@cscaper.com>
    
    p5p-msgid: 199708251732.KAA19299@gadget.cscaper.com

Subject: 5.004m4t1: perlbug: NIS domainname gets into wrong places
From: Andreas J. Koenig <koenig@anna.mind.de>
Files: utils/perlbug.PL
Msg-ID: sfcg1qy38as.fsf@anna.in-berlin.de

    (applied based on p5p patch as commit 41f926b844140b7f7eaa9302113e45df3a9f9ff4)

Subject: add better local patch info to perlbug
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perlbug.PL

Subject: perldoc - suggest modules if requested module not found
From: Anthony David <adavid@netinfo.com.au>
Files: utils/perldoc.PL

    private-msgid: 3439CD83.6969@netinfo.com.au

Subject: perldoc mail::foo tries to read binary /usr/ucb/mail
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

    Subject: perldoc weirdness
    
    perldoc mail::imap yields:
    
    {joseph}:79% perldoc mail::foo
    can't open /usr/ucb/mail: Permission denied at ./pod2man line 362.
    
    Credited: Joseph "Moof-in'" Hall <joseph@cscaper.com>
    
    p5p-msgid: 199710082014.NAA00808@gadget.cscaper.com

Subject: perldoc -f setpwent (for example) returns no descriptive text
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

Subject: perldoc diffs: don't search auto - much faster
From: "Joseph N. Hall" <joseph@5sigma.com>
Files: utils/perldoc.PL
Msg-ID: MailDrop1.2d7dPPC.971012211957@screechy.cscaper.com

    (applied based on p5p patch as commit 62b753c6ae4ab9bf22fbb6ec7ceac820bcef8fe4)

1 files changed, 380 insertions, 0 deletions

diff --git a/README.vms b/README.vms
index 9a6a712f4a..4b8c29d345 100644
--- a/README.vms
+++ b/README.vms
@@ -1,3 +1,383 @@
+Last Revised 11-September-1997 by Dan Sugalski <sugalsd@lbcc.cc.or.us>
+Originally by Charles Bailey <bailey@newman.upenn.edu>
+
+* Intro
+
+The VMS port of Perl is as functionally complete as any other Perl port
+(and as complete as the ports on some Unix systems). The Perl binaries
+provide all the Perl system calls that are either available under VMS or
+reasonably emulated. There are some incompatibilites in process handling
+(e.g the fork/exec model for creating subprocesses doesn't do what you
+might expect under Unix), mainly because VMS and Unix handle processes and
+sub-processes very differently.
+
+There are still some unimplemented system functions, and of coursse we
+could use modules implementing useful VMS system services, so if you'd like
+to lend a hand we'd love to have you. Join the Perl Porting Team Now!
+
+The current sources and build procedures have been tested on a VAX using
+VaxC and Dec C, and on an AXP using Dec C. If you run into problems with
+other compilers, please let us know.
+
+There are issues with varions versions of Dec C, so if you're not running a
+relatively modern version, check the Dec C issues section later on in this
+document.
+
+* Other required software
+
+In addition to VMS, you'll need:
+        1) A C compiler. Dec C for AXP, or VAX C, Dec C, or gcc for the
+           VAX.
+        2) A make tool. Dec's MMS (v2.6 or later), or MadGoat's free MMS
+           analog MMK (available from ftp.madgoat.com/madgoat) both work
+           just fine. Gnu Make might work, but it's been so long since
+           anyone's tested it that we're not sure. MMK's free, though, so
+           go ahead and use that.
+
+
+If you want to include socket support, you'll need a TCP stack and either
+Dec C, or socket libraries. See the Socket Support topic for more details.
+
+* Compiling Perl
+
+>From the top level of the Perl source directory, do this:
+
+MMS/DESCRIP=[.VMS]DESCRIP.MMS
+
+If you're on an Alpha, add /Macro=("__AXP__=1","decc=1")
+If you're using Dec C as your C compiler (you are on all alphas), add
+/Macro=("decc=1")
+If Vac C is your default C compiler and you want to use Dec C, add
+/Macro=("CC=CC/DECC") (Don't forget the /macro=("decc=1")
+If Dec C is your default C compiler and you want to use Vax C, add
+/Macro=("CC=CC/VAXC")
+If you want Socket support and are using the SOCKETSHR socket library, add
+/Macro=("SOCKETSHR_SOCKETS=1")
+If you want Socket support and are using the Dec C RTL socket interface
+(You must be using Dec C for this), add /Macro=("DECC_SOCKETS=1")
+
+If you have multiple /macro= items, combine them together in one /Macro=()
+switch, with all the options inside the parentheses separated by commas.
+
+Samples:
+
+VMS AXP, with Socketshr sockets:
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("decc=1","__AXP__=1","SOCKETSHR_SOCKETS=1")
+
+VMS AXP with no sockets
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("decc=1","__AXP__=1")
+
+VMS AXP with the Dec C RTL sockets
+
+$MMS/DESCRIP=[.VMS]/Macro=("decc=1","__AXP__=1","DECC_SOCKETS=1")
+
+VMS VAX with default system compiler, no sockets
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS
+
+VMS VAX with Dec C compiler, no sockets
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1")
+
+VMS VAX with Dec C compiler, Dec C RTL sockets
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1","DECC_SOCKETS=1")
+
+VMS VAX with Dec C compiler, Socketshr sockets
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1","SOCKETSHR_SOCKETS=1")
+
+Using Dec C is recommended over Vax C. The compiler is newer, and
+supported. (Vax C was decommisioned around 1993) Various older versions had
+some gotchas, so if you're using a version older than 5.2, check the Dec C
+Issues section.
+
+We'll also point out that Dec C will get you at least a ten-fold increase
+in line-oriented IO over Vax C. The optimizer is amazingly better, too. If
+you can use Dec C, then you *really*, *really* should.
+
+
+Once you issue your MMS command, sit back and wait. Perl should build and
+link without a problem. If it doesn't, check the Gotchas to watch out for
+section. If that doesn't help, send some mail to the VMSPERL mailing list.
+Instructions are in the Mailing Lists section.
+
+* Testing Perl
+
+Once Perl has built cleanly, you need to test it to make sure things work.
+This step is very important--there are always things that can go wrong
+somehow and get you a dysfunctional Perl.
+
+Testing is very easy, though, as there's a full test suite in the perl
+distribution. To run the tests, enter the *exact* MMS line you used to
+compile Perl and add the word "test" to the end, like this:
+
+Compile Command:
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
+
+Test Command:
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") test
+
+MMS will run all the tests. This may take some time, as there are a lot of
+tests. If any tests fail, there will be a note made on-screen. At the end
+of all the tests, a summary of the tests, the number passed and failed, and
+the time taken will be displayed.
+
+If any tests fail, it means something's wrong with Perl. If the test suite
+hangs (some tests can take upwards of two or three minutes, or more if
+you're on an especially slow machine, depending on you machine speed, so
+don't be hasty), then the test *after* the last one displayed failed. Don't
+install Perl unless you're confident that you're OK. Regardless of how
+confident you are, make a bug report to the VMSPerl mailing list.
+
+If one or more tests fail, you can get more info on the failure by issuing
+this command sequence:
+
+$ SET DEFAULT [.T]
+$ @[-.VMS]TEST .typ -v [.subdir]test.T
+
+where ".typ" is the file type of the Perl images you just built (if you
+didn't do anything special, use .EXE), and "[.subdir]test.T" is the test
+that failed. For example, with a normal Perl build, if the test indicated
+that [.op]time failed, then you'd do this:
+
+$ SET DEFAULT [.T]
+$ @[-.VMS]TEST .EXE -v [.OP]TIME.T
+
+When you send in a bug report for failed tests, please include the output
+from this command, which is run from the main source directory:
+
+MCR []MINIPERL "-V"
+
+Note that "-V" really is a capital V in double quotes. This will dump out a
+couple of screens worth of config info, and can help us diagnose the problem.
+
+* Cleaning up and starting fresh
+
+If you need to recompile from scratch, you have to make sure you clean up
+first. There's a procedure to do it--enter the *exact* MMS line you used to
+compile and add "realclean" at the end, like this:
+
+Compile Command:
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
+
+Cleanup Command:
+
+$MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") realclean
+
+If you don't do this, things may behave erratically. They might not, too,
+so it's best to be sure and do it.
+
+* Installing Perl
+
+There are several steps you need to take to get Perl installed and
+running. At some point we'll have a working install in DESCRIP.MMS, but for
+right now the procedure's manual, and goes like this.
+
+1) Create a directory somewhere and define the concealed logical PERL_ROOT
+to point to it. For example, DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.]
+
+2) Copy perl.exe into PERL_ROOT:[000000]
+
+3) Copy everything in [.LIB] and [.UTILS] (including all the
+subdirectories!) to PERL_ROOT:[LIB] and PERL_ROOT:[UTILS].
+
+4) Either copy PERLSHR.EXE to SYS$SHARE, or to somewhere globally accessble
+and define the logical PERLSHR to point to it (DEFINE PERLSHR
+PERL_ROOT:[000000]PERLSHR.EXE or something like that). The PerlShr image
+should have W:RE protections on it. (Just W:E triggers increased security in
+the image activator. Not a huge problem, but Perl will need to have any
+other shared image it accesses INSTALLed. It's a huge pain, so don't unless
+you know what you're doing)
+
+5) Either define the symbol PERL somewhere, such as
+SYS$MANAGER:SYLOGIN.COM, to be "PERL :== $PERL_ROOT:[000000]PERL.EXE", or
+install Perl into DCLTABLES.EXE )Check out the section "Installing Perl
+into DCLTABLES" for more info), or put the image in a directory that's in
+your DCL$PATH (if you're using VMS 6.2 or higher).
+
+6) Optionally define the command PERLDOC as 
+PERLDOC :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -T
+
+7) Optionally define the command PERLBUG (the Perl bug report generator) as
+PERLBUG :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM"
+
+* Installing Perl into DCLTABLES
+
+Courtesy of Brad  Hughes:
+
+Put the following, modified to reflect where your .exe is, in PERL.CLD:
+
+define verb perl
+image perl_root:[exe]perl.exe
+cliflags (foreign)
+
+and then
+
+$ set command perl /table=sys$common:[syslib]dcltables.exe -
+ /output=sys$common:[syslib]dcltables.exe
+$ install replace sys$common:[syslib]dcltables.exe
+
+and you don't need perl :== $perl_root:[exe]perl.exe.
+
+* Changing compile-time things
+
+Most of the user-definable features of Perl are enabled or disabled in
+[.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may
+end up being the wrong thing for you. Make sure you understand what you're
+doing, since changes here can get you a busted perl.
+
+Odds are that there's nothing here to change, unless you're on a version of
+VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct
+values will still be chosen, most likely. Poking around here should be
+unnecessary.
+
+The one exception is the various *DIR install locations. Changing those
+requires changes in genconfig.pl as well. Be really careful if you need to
+change these,a s they can cause some fairly subtle problems.
+
+* Extra things in the Perl distribution
+
+In addition to the standard stuff that gets installed, there are two
+optional extensions, DCLSYM and STDIO, that are handy. Instructions for
+these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO],
+respectively.
+
+* Socket Support
+
+Perl includes a number of functions for IP sockets, which are available if
+you choose to compile Perl with socket support. (See the section Compiling
+Perl for more info on selecting a socket stack) Since IP networking is an
+optional addition to VMS, there are several different IP stacks
+available. How well integrated they are into the system depends on the
+stack, your version of VMS, and the version of your C compiler.
+
+The most portable solution uses the SOCKETSHR library. In combination with
+either UCX or NetLib, this supports all the major TCP stacks (Multinet,
+Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with
+all the compilers on both VAX and Alpha. The socket interface is also
+consistent across versions of VMS and C compilers. It has a problem with
+UDP sockets when used with Multinet, though, so you should be aware of
+that.
+
+The other solution available is to use the socket routines built into Dec
+C. Which routines are available depend on the version of VMS you're
+running, and require proper UCX emulation by your TCP/IP vendor.
+Relatively current versions of Multinet, TCPWare, Pathway, and UCX all
+provide the required libraries--check your manuals or release notes to see
+if your version is new enough.
+
+* Reporting Bugs
+
+If you come across what you think might be a bug in Perl, please report
+it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
+the process of creating a bug report. This script includes details of your
+installation, and is very handy. Completed bug reports should go to
+PERLBUG@PERL.COM.
+
+* Gotchas to watch out for
+
+Probably the single biggest gotcha in compiling Perl is giving the wrong
+switches to MMS/MMK when you build. If Perl's building oddly, double-check
+your switches. If you're on a VAX, be sure to add a /Macro=("decc=1") if
+you're using Dec C, and if you're on an alpha and using MMS, you'll need a
+/Macro=("__AXP__=1")
+
+The next big gotcha is directory depth. Perl can create directories four
+and five levels deep during the build, so you don't have to be too deep to
+start to hit the RMS 8 level point. It's best to do a
+$DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]"  (note the
+trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl
+modules can be just as bad (or worse), so watch out for them, too.
+
+Finally, the third thing that bites people is leftover pieces from a failed
+build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean"
+before you rebuild.
+
+* Dec C issues
+
+Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec
+C 5.x or higher, with current patches if anym you're fine) of the DECCRTL
+contained a few bugs which affect Perl performance:
+    - Newlines are lost on I/O through pipes, causing lines to run together.
+      This shows up as RMS RTB errors when reading from a pipe.  You can
+      work around this by having one process write data to a file, and
+      then having the other read the file, instead of the pipe.  This is
+      fixed in version 4 of DECC.
+    - The modf() routine returns a non-integral value for some values above
+      INT_MAX; the Perl "int" operator will return a non-integral value in
+      these cases.  This is fixed in version 4 of DECC.
+    - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine
+      changes the process default device and directory permanently, even
+      though the call specified that the change should not persist after
+      Perl exited.  This is fixed by DEC CSC patch AXPACRT04_061.
+
+* Mailing Lists
+
+There are several mailing lists available to the Perl porter. For VMS
+specific issues (including both Perl questions and installation problems)
+there is the VMSPERL mailing list. It's usually a low-volume (10-12
+messages a week) mailing list.
+
+The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail
+message with just the words SUBSCRIBE VMSPERL in the body of the message.
+
+The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail
+sent there gets echoed to all subscribers of the list.
+
+The Perl5-Porters list is for anyone involved in porting Perl to a
+platform. This includes you, if you want to participate. It's a high-volume
+list (60-100 messages a day during active development times), so be sure
+you want to be there. The subscription address is
+Perl5-Porters-request@perl.org. Send a message with just the word SUBSCRIBE
+in the body. The posting address is Perl5-Porters@perl.org.
+
+* Acknowledgements
+
+A real big thanks needs to go to Charles Bailey
+<bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004
+running on VMS. Without him, nothing the rest of us have done would be at
+all important.
+
+There are, of course, far too many people involved in the porting and testing
+of Perl to mention everyone who deserves it, so please forgive us if we've
+missed someone.  That said, special thanks are due to the following:
+  Tim Adye <T.J.Adye@rl.ac.uk>
+     for the VMS emulations of getpw*()
+  David Denholm <denholm@conmat.phys.soton.ac.uk>
+     for extensive testing and provision of pipe and SocketShr code,
+  Mark Pizzolato <mark@infocomm.com>
+     for the getredirection() code
+  Rich Salz <rsalz@bbn.com>
+     for readdir() and related routines
+  Peter Prymmer <pvhp@lns62.lns.cornell.edu)
+     for extensive testing, as well as development work on
+     configuration and documentation for VMS Perl,
+  Dan Sugalski <sugalsd@stargate.lbcc.cc.or.us>
+     for extensive contributions to recent version support,
+     development of VMS-specific extensions, and dissemination
+     of information about VMS Perl,
+  the Stanford Synchrotron Radiation Laboratory and the
+     Laboratory of Nuclear Studies at Cornell University for
+     the the opportunity to test and develop for the AXP,
+and to the entire VMSperl group for useful advice and suggestions.  In
+addition the perl5-porters deserve credit for their creativity and
+willingness to work with the VMS newcomers.  Finally, the greatest debt of
+gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which
+have made our sleepless nights possible.
+
+Thanks,
+The VMSperl group
+
+
+---------------------------------------------------------------------------
+[Here's the pre-5.004_04 version of README.vms, for the record.]
+
 Last revised: 19-Jan-1996 by Charles Bailey  bailey@genetics.upenn.edu
 
 The VMS port of Perl is still under development.  At this time, the Perl