This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update p5p list archive links
[perl5.git] / README.bs2000
index a0128fd..77aa461 100644 (file)
@@ -1,11 +1,14 @@
 This document is written in pod format hence there are punctuation
-characters in in odd places.  Do not worry, you've apparently got the
+characters in odd places.  Do not worry, you've apparently got the
 ASCII->EBCDIC translation worked out correctly.  You can read more
 about pod in pod/perlpod.pod or the short summary in the INSTALL file.
 
 =head1 NAME
 
-README.posix-bc - building and installing Perl for BS2000 POSIX.
+perlbs2000 - building and installing Perl for BS2000.
+
+B<This document needs to be updated, but we don't know what it should say.
+Please email comments to L<perlbug@perl.org|mailto:perlbug@perl.org>.>
 
 =head1 SYNOPSIS
 
@@ -15,24 +18,25 @@ on BS2000 in the POSIX subsystem.
 =head1 DESCRIPTION
 
 This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
-V3.1A.  It may work on other versions, but that's the one we've tested
-it on.
+V3.1A or later.  It may work on other versions, but we started porting
+and testing it with 3.1A and are currently using Version V4.0A.
 
 You may need the following GNU programs in order to install perl:
 
-=head2 gzip
+=head2 gzip on BS2000
 
 We used version 1.2.4, which could be installed out of the box with
 one failure during 'make check'.
 
-=head2 bison
+=head2 bison on BS2000
 
 The yacc coming with BS2000 POSIX didn't work for us.  So we had to
 use bison.  We had to make a few changes to perl in order to use the
 pure (reentrant) parser of bison.  We used version 1.25, but we had to
-add a few changes due to EBCDIC.
+add a few changes due to EBCDIC.  See below for more details
+concerning yacc.
 
-=head2 Unpacking
+=head2 Unpacking Perl Distribution on BS2000
 
 To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
 filesystem (we used the mountpoint /usr/local/ascii for this).  Now
@@ -54,11 +58,12 @@ cd /usr/local/src
 IO_CONVERSION=YES
 cp -r /usr/local/ascii/perl5.005_02 ./
 
-=head2 Compiling
+=head2 Compiling Perl on BS2000
 
-There is a "hints" file for posix-bc that specifies the correct values
-for most things.  The major problem is (of course) the EBCDIC character
-set.  We have german EBCDIC version.
+There is a "hints" file for BS2000 called hints.posix-bc (because
+posix-bc is the OS name given by `uname`) that specifies the correct
+values for most things.  The major problem is (of course) the EBCDIC
+character set.  We have german EBCDIC version.
 
 Because of our problems with the native yacc we used GNU bison to
 generate a pure (=reentrant) parser for perly.y.  So our yacc is
@@ -100,7 +105,7 @@ ln -s /usr/bin/yacc /usr/local/bin/byacc
 We build perl using GNU make.  We tried the native make once and it
 worked too.
 
-=head2 Testing
+=head2 Testing Perl on BS2000
 
 We still got a few errors during C<make test>.  Some of them are the
 result of using bison.  Bison prints I<parser error> instead of I<syntax
@@ -118,13 +123,13 @@ lib/complex.........FAILED tests 267, 487
 lib/dumper..........FAILED tests 43, 45
 Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.
 
-=head2 Install
+=head2 Installing Perl on BS2000
 
 We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
 installing the documentation.
 
 
-=head2 Using Perl
+=head2 Using Perl in the Posix-Shell of BS2000
 
 BS2000 POSIX doesn't support the shebang notation
 (C<#!/usr/local/bin/perl>), so you have to use the following lines
@@ -134,7 +139,29 @@ instead:
     eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
         if $running_under_some_shell;
 
-=head2 Floating point anomalies
+=head2 Using Perl in "native" BS2000
+
+We don't have much experience with this yet, but try the following:
+
+Copy your Perl executable to a BS2000 LLM using bs2cp:
+
+C<bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'>
+
+Now you can start it with the following (SDF) command:
+
+C</START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV>
+
+First you get the BS2000 commandline prompt ('*').  Here you may enter
+your parameters, e.g. C<-e 'print "Hello World!\\n";'> (note the
+double backslash!) or C<-w> and the name of your Perl script.
+Filenames starting with C</> are searched in the Posix filesystem,
+others are searched in the BS2000 filesystem.  You may even use
+wildcards if you put a C<%> in front of your filename (e.g. C<-w
+checkfiles.pl %*.c>).  Read your C/C++ manual for additional
+possibilities of the commandline prompt (look for
+PARAMETER-PROMPTING).
+
+=head2 Floating point anomalies on BS2000
 
 There appears to be a bug in the floating point implementation on BS2000 POSIX
 systems such that calling int() on the product of a number and a small
@@ -150,6 +177,40 @@ Perl code:
 Although one would expect the quantities $y and $z to be the same and equal
 to 100000 they will differ and instead will be 0 and 100000 respectively.
 
+=head2 Using PerlIO and different encodings on ASCII and EBCDIC partitions
+
+Since version 5.8 Perl uses the new PerlIO on BS2000.  This enables
+you using different encodings per IO channel.  For example you may use
+
+    use Encode;
+    open($f, ">:encoding(ascii)", "test.ascii");
+    print $f "Hello World!\n";
+    open($f, ">:encoding(posix-bc)", "test.ebcdic");
+    print $f "Hello World!\n";
+    open($f, ">:encoding(latin1)", "test.latin1");
+    print $f "Hello World!\n";
+    open($f, ">:encoding(utf8)", "test.utf8");
+    print $f "Hello World!\n";
+
+to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO
+Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
+this example identical to normal EBCDIC).  See the documentation of
+Encode::PerlIO for details.
+
+As the PerlIO layer uses raw IO internally, all this totally ignores
+the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
+environment variable.  If you want to get the old behavior, that the
+BS2000 IO functions determine conversion depending on the filesystem
+PerlIO still is your friend.  You use IO_CONVERSION as usual and tell
+Perl, that it should use the native IO layer:
+
+    export IO_CONVERSION=YES
+    export PERLIO=stdio
+
+Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
+partitions.  See the documentation of PerlIO (without C<Encode::>!)
+for further possibilities.
+
 =head1 AUTHORS
 
 Thomas Dorner
@@ -160,13 +221,17 @@ L<INSTALL>, L<perlport>.
 
 =head2 Mailing list
 
-The Perl Institute (http://www.perl.org/) maintains a perl-mvs mailing
-list of interest to all folks building and/or using perl on EBCDIC
-platforms.  To subscribe, send a message of:
+If you are interested in the z/OS (formerly known as OS/390)
+and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
+To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
+
+See also:
+
+    https://lists.perl.org/list/perl-mvs.html
 
-    subscribe perl-mvs
+There are web archives of the mailing list at:
 
-to majordomo@perl.org.
+    https://www.nntp.perl.org/group/perl.mvs/
 
 =head1 HISTORY