diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlos390.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlos390.1 | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlos390.1 b/upstream/mageia-cauldron/man1/perlos390.1 new file mode 100644 index 00000000..ac742398 --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlos390.1 @@ -0,0 +1,506 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLOS390 1" +.TH PERLOS390 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlos390 \- building and installing Perl for z/OS (previously called OS/390) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +This document will help you Configure, build, test and install Perl +on z/OS Unix System Services. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and +should work fine with z/OS 2.5. +It may work on other versions or releases, but those are +the ones it has been tested on. +.PP +The native character set for z/OS is EBCDIC, but it can also run in ASCII mode. +Perl can support either, but you have to compile it explicitly for one or the +other. You could have both an ASCII perl, and an EBCDIC perl on the same +machine. If you use ASCII mode and an ASCII perl, the Encode module shipped +with perl can be used to translate files from various EBCDIC code pages for +handling by perl, and then back on output +.PP +This document describes how to build a 64\-bit Dynamic Perl, either ASCII or +EBCDIC. You can interactively choose other configurations, as well as many +other options in the Configure script that is run as part of the build +process. You may need to carry out some system configuration tasks before +running Configure, as detailed below. +.SS Tools +.IX Subsection "Tools" +You will want to get GNU make 4.1 or later. GNU make can be downloaded from a +port that Rocket Software provides. You will need the z/OS c99 compiler from +IBM (though xlc in c99 mode without optimization turned on works in EBCDIC). +.PP +If you want the latest development version of Perl, you will need git. +You can use git on another platform and transfer the result via sftp or ftp to +z/OS. But there is a z/OS native git client port available through Rocket +Software. +.PP +You may also need the gunzip client port that Rocket Software provides to unzip +any zipped tarball you upload to z/OS. +.SS "Building a 64\-bit Dynamic ASCII Perl" +.IX Subsection "Building a 64-bit Dynamic ASCII Perl" +For building from an official stable release of Perl, go to +<https://www.perl.org/get.html> and choose any one of the +"Download latest stable source" buttons. This will get you a tarball. The +name of that tarball will be something like 'perl\-V.R.M,tar,gz', where V.R.M is +the version/release/modification of the perl you are downloading. Do +.PP +.Vb 1 +\& gunzip perl\-V.R.M.tar.gz +.Ve +.PP +Then one of: +.PP +.Vb 1 +\& tar \-xvf perl\-V.R.M.tar +\& +\& pax \-r \-f perl\-V.R.M.tar +.Ve +.PP +Either of these will create the source directory. You can rename it to +whatever you like; for these instructions, 'perl' is assumed to be the name. +.PP +If instead you want the latest unstable development release, using the native +git on z/OS, clone Perl: +.PP +.Vb 1 +\& git clone https://github.com/Perl/perl5.git perl +.Ve +.PP +Either way, once you have a 'perl' directory containing the source, cd into it, +and tag all the code as ASCII: +.PP +.Vb 2 +\& cd perl +\& chtag \-R \-h \-t \-cISO8859\-1 * +.Ve +.PP +Configure the build environment as 64\-bit, Dynamic, ASCII, development, +deploying it to \fI/usr/local/perl/ascii\fR: +.PP +.Vb 4 +\& export PATH=$PWD:$PATH +\& export LIBPATH=$PWD:$PATH +\& ./Configure \-Dprefix=/usr/local/perl/ascii \-des \-Dusedevel \e +\& \-Duse64bitall \-Dusedl +.Ve +.PP +If you are building from a stable source, you don't need "\-Dusedevel". +(If you run Configure without options, it will interactively ask you about +every possible option based on its probing of what's available on your +particular machine, so you can choose as you go along.) +.PP +Run GNU make to build Perl +.PP +.Vb 1 +\& make +.Ve +.PP +Run tests to ensure Perl is working correctly. Currently, there are about a +dozen failing tests out of nearly 2500 +.PP +.Vb 1 +\& make test_harness +.Ve +.PP +Install Perl into \fI/usr/local/perl/ascii\fR: +.PP +.Vb 1 +\& make install +.Ve +.SS "Building a 64\-bit Dynamic EBCDIC Perl" +.IX Subsection "Building a 64-bit Dynamic EBCDIC Perl" +You will need a working perl on some box with connectivity to the destination +machine. On z/OS, it could be an ASCII perl, or a previous EBCDIC one. +Many machines will already have a pre-built perl already running, or one can +easily be downloaded from <https://www.perl.org/get.html>. +.PP +Follow the directions above in "Building a 64\-bit Dynamic ASCII Perl" as far as +getting a populated 'perl' directory. Then come back here to proceed. +.PP +The downloaded perl will need to be converted to 1047 EBCDIC. To do this: +.PP +.Vb 2 +\& cd perl +\& Porting/makerel \-e +.Ve +.PP +If the Porting/makerel step fails with an error that it can not issue the tar +command, proceed to issue the command interactively, where V.R.M is the +version/release/modification of Perl you are uploading: +.PP +.Vb 2 +\& cd ../ +\& tar cf \- \-\-format=ustar perl\-V.R.M | gzip \-\-best > perl\-V.R.M.tar.gz +.Ve +.PP +Use sftp to upload the zipped tar file to z/OS: +.PP +.Vb 3 +\& sftp <your system> +\& cd /tmp +\& put perl\-V.R.M.tar.gz +.Ve +.PP +Unzip and untar the zipped tar file on z/OS: +.PP +.Vb 2 +\& cd /tmp +\& gunzip perl\-V.R.M.tar.gz +.Ve +.PP +Then one of: +.PP +.Vb 1 +\& tar \-xvf perl\-V.R.M.tar +\& +\& pax \-r \-f perl\-V.R.M.tar +.Ve +.PP +You now have the source code for the EBCDIC Perl on z/OS and can proceed to +build it. This is analagous to how you would build the code for ASCII, but +note: you \fBshould not\fR tag the code but instead leave it untagged. +.PP +Configure the build environment as 64\-bit, Dynamic, native, development, +deploying it to \fI/usr/local/perl/ebcdic\fR: +.PP +.Vb 4 +\& export PATH=$PWD:$PATH +\& export LIBPATH=$PWD:$PATH +\& ./Configure \-Dprefix=/usr/local/perl/ebcdic \-des \-Dusedevel \e +\& \-Duse64bitall \-Dusedl +.Ve +.PP +If you are building from a stable source, you don't need "\-Dusedevel". +(If you run Configure without options, it will interactively ask you about +every possible option based on its probing of what's available on your +particular machine, so you can choose as you go along.) +.PP +Run GNU make to build Perl +.PP +.Vb 1 +\& make +.Ve +.PP +Run tests to ensure Perl is working correctly. +.PP +.Vb 1 +\& make test_harness +.Ve +.PP +You might also want to have GNU groff for OS/390 installed before +running the "make install" step for Perl. +.PP +Install Perl into \fI/usr/local/perl/ebcdic\fR: +.PP +.Vb 1 +\& make install +.Ve +.PP +EBCDIC Perl is still a work in progress. All the core code works as far as we +know, but various modules you might want to download from CPAN do not. The +failures range from very minor to catastrophic. Many of them are simply bugs +in the tests, with the module actually working properly. This happens because, +for example, the test is coded to expect a certain character ASCII code point; +when it gets the EBCDIC value back instead, it complains. But the code +actually worked. Other potential failures that aren't really failures stem +from checksums coming out differently, since \f(CW\*(C`A\*(C'\fR, for example, has a different +bit representation between the character sets. A test that is expecting the +ASCII value will show failure, even if the module is working perfectly. Also +in sorting, uppercase letters come before lowercase letters on ASCII systems; +the reverse on EBCDIC. +.PP +Some CPAN modules come bundled with the downloaded perl. And a few of those +have yet to be fixed to pass on EBCDIC platforms. As a result they are skipped +when you run 'make test'. The current list is: +.PP +.Vb 10 +\& Archive::Tar +\& Config::Perl::V +\& CPAN::Meta +\& CPAN::Meta::YAML +\& Digest::MD5 +\& Digest::SHA +\& Encode +\& ExtUtils::MakeMaker +\& ExtUtils::Manifest +\& HTTP::Tiny +\& IO::Compress +\& IPC::Cmd +\& JSON::PP +\& libnet +\& MIME::Base64 +\& Module::Metadata +\& PerlIO::via\-QuotedPrint +\& Pod::Checker +\& podlators +\& Pod::Simple +\& Socket +\& Test::Harness +.Ve +.PP +See also \fIhints/os390.sh\fR for other potential gotchas. +.SS "Setup and utilities for Perl on OS/390" +.IX Subsection "Setup and utilities for Perl on OS/390" +This may also be a good time to ensure that your \fI/etc/protocol\fR file +and either your \fI/etc/resolv.conf\fR or \fI/etc/hosts\fR files are in place. +The IBM document that describes such USS system setup issues is +"z/OS UNIX System Services Planning" +.PP +For successful testing you may need to turn on the sticky bit for your +world readable /tmp directory if you have not already done so (see man chmod). +.SS "Useful files for trouble-shooting" +.IX Subsection "Useful files for trouble-shooting" +If your configuration is failing, read hints/os390.sh +This file provides z/OS specific options to direct the build process. +.PP +\fIShell\fR +.IX Subsection "Shell" +.PP +A message of the form: +.PP +.Vb 3 +\& (I see you are using the Korn shell. Some ksh\*(Aqs blow up on Configure, +\& mainly on older exotic systems. If yours does, try the Bourne shell +\& instead.) +.Ve +.PP +is nothing to worry about at all. +.PP +\fIDynamic loading\fR +.IX Subsection "Dynamic loading" +.PP +Dynamic loading is required if you want to use XS modules from CPAN (like +DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from +CPAN with newer versions (like Encode) without rebuilding all of the perl +binary. +.PP +The instructions above will create a dynamic Perl. If you do not want to +use dynamic loading, remove the \-Dusedl option. +See the comments in hints/os390.sh for more information on dynamic loading. +.PP +\fIOptimizing\fR +.IX Subsection "Optimizing" +.PP +Optimization has not been turned on yet. There may be issues if Perl +is optimized. +.SS "Build Anomalies with Perl on OS/390" +.IX Subsection "Build Anomalies with Perl on OS/390" +"Out of memory!" messages during the build of Perl are most often fixed +by re building the GNU make utility for OS/390 from a source code kit. +.PP +Within USS your \fI/etc/profile\fR or \fR\f(CI$HOME\fR\fI/.profile\fR may limit your ulimit +settings. Check that the following command returns reasonable values: +.PP +.Vb 1 +\& ulimit \-a +.Ve +.PP +To conserve memory you should have your compiler modules loaded into the +Link Pack Area (LPA/ELPA) rather than in a link list or step lib. +.PP +If the compiler complains of syntax errors during the build of the +Socket extension then be sure to fix the syntax error in the system +header /usr/include/sys/socket.h. +.SS "Testing Anomalies with Perl on OS/390" +.IX Subsection "Testing Anomalies with Perl on OS/390" +The "make test" step runs a Perl Verification Procedure, usually before +installation. You might encounter STDERR messages even during a successful +run of "make test". Here is a guide to some of the more commonly seen +anomalies: +.PP +\fIOut of Memory (31\-bit only)\fR +.IX Subsection "Out of Memory (31-bit only)" +.PP +Out of memory problems should not be an issue, unless you are attempting to build +a 31\-bit Perl. +.PP +If you _are_ building a 31\-bit Perl, the constrained environment may mean you +need to change memory options for Perl. +In addition to the comments +above on memory limitations it is also worth checking for _CEE_RUNOPTS +in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31\-bit only +to set CEE run options, but the environment variable wins. +.PP +The 31\-bit C code asks for: +.PP +.Vb 1 +\& #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON)) +.Ve +.PP +The important parts of that are the second argument (the increment) to HEAP, +and allowing the stack to be "Above the (16M) line". If the heap +increment is too small then when perl (for example loading unicode/Name.pl) tries +to create a "big" (400K+) string it cannot fit in a single segment +and you get "Out of Memory!" \- even if there is still plenty of memory +available. +.PP +A related issue is use with perl's malloc. Perl's malloc uses \f(CWsbrk()\fR +to get memory, and \f(CWsbrk()\fR is limited to the first allocation so in this +case something like: +.PP +.Vb 1 +\& HEAP(8M,500K,ANYWHERE,KEEP,8K,4K) +.Ve +.PP +is needed to get through the test suite. +.SS "Usage Hints for Perl on z/OS" +.IX Subsection "Usage Hints for Perl on z/OS" +When using Perl on z/OS please keep in mind that the EBCDIC and ASCII +character sets are different. See perlebcdic for more on such character +set issues. Perl builtin functions that may behave differently under +EBCDIC are also mentioned in the perlport.pod document. +.PP +If you are having trouble with square brackets then consider switching your +rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for +working with Perl on USS. +.SS "Modules and Extensions for Perl on z/OS (Static Only)" +.IX Subsection "Modules and Extensions for Perl on z/OS (Static Only)" +Pure Perl (that is non XS) modules may be installed via the usual: +.PP +.Vb 4 +\& perl Makefile.PL +\& make +\& make test +\& make install +.Ve +.PP +If you built perl with dynamic loading capability then that would also +be the way to build XS based extensions. However, if you built perl with +static linking you can still build XS based extensions for z/OS +but you will need to follow the instructions in ExtUtils::MakeMaker for +building statically linked perl binaries. In the simplest configurations +building a static perl + XS extension boils down to: +.PP +.Vb 6 +\& perl Makefile.PL +\& make +\& make perl +\& make test +\& make install +\& make \-f Makefile.aperl inst_perl MAP_TARGET=perl +.Ve +.SS "Running Perl on z/OS" +.IX Subsection "Running Perl on z/OS" +To run the 64\-bit Dynamic Perl environment, update your PATH and LIBPATH +to include the location you installed Perl into, and then run the perl you +installed as perlV.R.M where V/R/M is the Version/Release/Modification level +of the current development level. +If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to +set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl +source code you run is tagged appropriately as ASCII or EBCDIC using +"chtag \-t \-c<CCSID>": +.IP "For ASCII Only:" 4 +.IX Item "For ASCII Only:" +.Vb 5 +\& export _BPXK_AUTOCVT=ON +\& export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)" +\& export _TAG_REDIR_ERR="txt" +\& export _TAG_REDIR_IN="txt" +\& export _TAG_REDIR_OUT="txt" +.Ve +.IP "For ASCII or EBCDIC:" 4 +.IX Item "For ASCII or EBCDIC:" +.Vb 3 +\& export PATH=/usr/local/perl/ascii:$PATH +\& export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH +\& perlV.R.M args +.Ve +.PP +If tcsh is your login shell then use the setenv command. +.SH AUTHORS +.IX Header "AUTHORS" +David Fiander and Peter Prymmer with thanks to Dennis Longnecker +and William Raffloer for valuable reports, LPAR and PTF feedback. +Thanks to Mike MacIsaac and Egon Terwedow for SG24\-5944\-00. +Thanks to Ignasi Roca for pointing out the floating point problems. +Thanks to John Goodyear for dynamic loading help. +.PP +Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64\-bit and +ASCII/EBCDIC Bi-Modal support +.SH "OTHER SITES" +.IX Header "OTHER SITES" +<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools +for building various z/OS Perl configurations and has some useful tools in the +\&'bin' directory you may want to use for building z/OS Perl yourself. +.SH HISTORY +.IX Header "HISTORY" +Updated 24 December 2021 to enable initial ASCII support +.PP +Updated 03 October 2019 for perl\-5.33.3+ +.PP +Updated 28 November 2001 for broken URLs. +.PP +Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'. +.PP +Updated 24 January 2001 to mention dynamic loading. +.PP +Updated 15 January 2001 for the 5.7.1 release of Perl. +.PP +Updated 12 November 2000 for the 5.7.1 release of Perl. +.PP +This document was podified for the 5.005_03 release of Perl 11 March 1999. +.PP +This document was originally written by David Fiander for the 5.005 +release of Perl. |