1# vim: syntax=pod 2 3This document is written in pod format hence there are punctuation 4characters in odd places. You can read more 5about pod in pod/perlpod.pod or the short summary in the INSTALL file. 6 7=head1 NAME 8 9perlos390 - building and installing Perl for z/OS (previously called OS/390) 10 11=head1 SYNOPSIS 12 13This document will help you Configure, build, test and install Perl 14on z/OS Unix System Services. 15 16=head1 DESCRIPTION 17 18This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and 19should work fine with z/OS 2.5. 20It may work on other versions or releases, but those are 21the ones it has been tested on. 22 23The native character set for z/OS is EBCDIC, but it can also run in ASCII mode. 24Perl can support either, but you have to compile it explicitly for one or the 25other. You could have both an ASCII perl, and an EBCDIC perl on the same 26machine. If you use ASCII mode and an ASCII perl, the Encode module shipped 27with perl can be used to translate files from various EBCDIC code pages for 28handling by perl, and then back on output 29 30This document describes how to build a 64-bit Dynamic Perl, either ASCII or 31EBCDIC. You can interactively choose other configurations, as well as many 32other options in the Configure script that is run as part of the build 33process. You may need to carry out some system configuration tasks before 34running Configure, as detailed below. 35 36=head2 Tools 37 38You will want to get GNU make 4.1 or later. GNU make can be downloaded from a 39port that Rocket Software provides. You will need the z/OS c99 compiler from 40IBM (though xlc in c99 mode without optimization turned on works in EBCDIC). 41 42If you want the latest development version of Perl, you will need git. 43You can use git on another platform and transfer the result via sftp or ftp to 44z/OS. But there is a z/OS native git client port available through Rocket 45Software. 46 47You may also need the gunzip client port that Rocket Software provides to unzip 48any zipped tarball you upload to z/OS. 49 50=head2 Building a 64-bit Dynamic ASCII Perl 51 52For building from an official stable release of Perl, go to 53L<https://www.perl.org/get.html> and choose any one of the 54"Download latest stable source" buttons. This will get you a tarball. The 55name of that tarball will be something like 'perl-V.R.M,tar,gz', where V.R.M is 56the version/release/modification of the perl you are downloading. Do 57 58 gunzip perl-V.R.M.tar.gz 59 60Then one of: 61 62 tar -xvf perl-V.R.M.tar 63 64 pax -r -f perl-V.R.M.tar 65 66Either of these will create the source directory. You can rename it to 67whatever you like; for these instructions, 'perl' is assumed to be the name. 68 69If instead you want the latest unstable development release, using the native 70git on z/OS, clone Perl: 71 72 git clone https://github.com/Perl/perl5.git perl 73 74Either way, once you have a 'perl' directory containing the source, cd into it, 75and tag all the code as ASCII: 76 77 cd perl 78 chtag -R -h -t -cISO8859-1 * 79 80Configure the build environment as 64-bit, Dynamic, ASCII, development, 81deploying it to F</usr/local/perl/ascii>: 82 83 export PATH=$PWD:$PATH 84 export LIBPATH=$PWD:$PATH 85 ./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \ 86 -Duse64bitall -Dusedl 87 88If you are building from a stable source, you don't need "-Dusedevel". 89(If you run Configure without options, it will interactively ask you about 90every possible option based on its probing of what's available on your 91particular machine, so you can choose as you go along.) 92 93Run GNU make to build Perl 94 95 make 96 97Run tests to ensure Perl is working correctly. Currently, there are about a 98dozen failing tests out of nearly 2500 99 100 make test_harness 101 102Install Perl into F</usr/local/perl/ascii>: 103 104 make install 105 106=head2 Building a 64-bit Dynamic EBCDIC Perl 107 108You will need a working perl on some box with connectivity to the destination 109machine. On z/OS, it could be an ASCII perl, or a previous EBCDIC one. 110Many machines will already have a pre-built perl already running, or one can 111easily be downloaded from L<https://www.perl.org/get.html>. 112 113Follow the directions above in "Building a 64-bit Dynamic ASCII Perl" as far as 114getting a populated 'perl' directory. Then come back here to proceed. 115 116The downloaded perl will need to be converted to 1047 EBCDIC. To do this: 117 118 cd perl 119 Porting/makerel -e 120 121If the Porting/makerel step fails with an error that it can not issue the tar 122command, proceed to issue the command interactively, where V.R.M is the 123version/release/modification of Perl you are uploading: 124 125 cd ../ 126 tar cf - --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz 127 128Use sftp to upload the zipped tar file to z/OS: 129 130 sftp <your system> 131 cd /tmp 132 put perl-V.R.M.tar.gz 133 134Unzip and untar the zipped tar file on z/OS: 135 136 cd /tmp 137 gunzip perl-V.R.M.tar.gz 138 139Then one of: 140 141 tar -xvf perl-V.R.M.tar 142 143 pax -r -f perl-V.R.M.tar 144 145You now have the source code for the EBCDIC Perl on z/OS and can proceed to 146build it. This is analagous to how you would build the code for ASCII, but 147note: you B<should not> tag the code but instead leave it untagged. 148 149Configure the build environment as 64-bit, Dynamic, native, development, 150deploying it to F</usr/local/perl/ebcdic>: 151 152 export PATH=$PWD:$PATH 153 export LIBPATH=$PWD:$PATH 154 ./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \ 155 -Duse64bitall -Dusedl 156 157If you are building from a stable source, you don't need "-Dusedevel". 158(If you run Configure without options, it will interactively ask you about 159every possible option based on its probing of what's available on your 160particular machine, so you can choose as you go along.) 161 162Run GNU make to build Perl 163 164 make 165 166Run tests to ensure Perl is working correctly. 167 168 make test_harness 169 170You might also want to have GNU groff for OS/390 installed before 171running the "make install" step for Perl. 172 173Install Perl into F</usr/local/perl/ebcdic>: 174 175 make install 176 177EBCDIC Perl is still a work in progress. All the core code works as far as we 178know, but various modules you might want to download from CPAN do not. The 179failures range from very minor to catastrophic. Many of them are simply bugs 180in the tests, with the module actually working properly. This happens because, 181for example, the test is coded to expect a certain character ASCII code point; 182when it gets the EBCDIC value back instead, it complains. But the code 183actually worked. Other potential failures that aren't really failures stem 184from checksums coming out differently, since C<A>, for example, has a different 185bit representation between the character sets. A test that is expecting the 186ASCII value will show failure, even if the module is working perfectly. Also 187in sorting, uppercase letters come before lowercase letters on ASCII systems; 188the reverse on EBCDIC. 189 190Some CPAN modules come bundled with the downloaded perl. And a few of those 191have yet to be fixed to pass on EBCDIC platforms. As a result they are skipped 192when you run 'make test'. The current list is: 193 194 Archive::Tar 195 Config::Perl::V 196 CPAN::Meta 197 CPAN::Meta::YAML 198 Digest::MD5 199 Digest::SHA 200 Encode 201 ExtUtils::MakeMaker 202 ExtUtils::Manifest 203 HTTP::Tiny 204 IO::Compress 205 IPC::Cmd 206 JSON::PP 207 libnet 208 MIME::Base64 209 Module::Metadata 210 PerlIO::via-QuotedPrint 211 Pod::Checker 212 podlators 213 Pod::Simple 214 Socket 215 Test::Harness 216 217See also F<hints/os390.sh> for other potential gotchas. 218 219=head2 Setup and utilities for Perl on OS/390 220 221This may also be a good time to ensure that your F</etc/protocol> file 222and either your F</etc/resolv.conf> or F</etc/hosts> files are in place. 223The IBM document that describes such USS system setup issues is 224"z/OS UNIX System Services Planning" 225 226For successful testing you may need to turn on the sticky bit for your 227world readable /tmp directory if you have not already done so (see man chmod). 228 229=head2 Useful files for trouble-shooting 230 231If your configuration is failing, read hints/os390.sh 232This file provides z/OS specific options to direct the build process. 233 234=head3 Shell 235 236A message of the form: 237 238 (I see you are using the Korn shell. Some ksh's blow up on Configure, 239 mainly on older exotic systems. If yours does, try the Bourne shell 240 instead.) 241 242is nothing to worry about at all. 243 244=head3 Dynamic loading 245 246Dynamic loading is required if you want to use XS modules from CPAN (like 247DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from 248CPAN with newer versions (like Encode) without rebuilding all of the perl 249binary. 250 251The instructions above will create a dynamic Perl. If you do not want to 252use dynamic loading, remove the -Dusedl option. 253See the comments in hints/os390.sh for more information on dynamic loading. 254 255=head3 Optimizing 256 257Optimization has not been turned on yet. There may be issues if Perl 258is optimized. 259 260=head2 Build Anomalies with Perl on OS/390 261 262"Out of memory!" messages during the build of Perl are most often fixed 263by re building the GNU make utility for OS/390 from a source code kit. 264 265Within USS your F</etc/profile> or F<$HOME/.profile> may limit your ulimit 266settings. Check that the following command returns reasonable values: 267 268 ulimit -a 269 270To conserve memory you should have your compiler modules loaded into the 271Link Pack Area (LPA/ELPA) rather than in a link list or step lib. 272 273If the compiler complains of syntax errors during the build of the 274Socket extension then be sure to fix the syntax error in the system 275header /usr/include/sys/socket.h. 276 277=head2 Testing Anomalies with Perl on OS/390 278 279The "make test" step runs a Perl Verification Procedure, usually before 280installation. You might encounter STDERR messages even during a successful 281run of "make test". Here is a guide to some of the more commonly seen 282anomalies: 283 284=head3 Out of Memory (31-bit only) 285 286Out of memory problems should not be an issue, unless you are attempting to build 287a 31-bit Perl. 288 289If you _are_ building a 31-bit Perl, the constrained environment may mean you 290need to change memory options for Perl. 291In addition to the comments 292above on memory limitations it is also worth checking for _CEE_RUNOPTS 293in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31-bit only 294to set CEE run options, but the environment variable wins. 295 296The 31-bit C code asks for: 297 298 #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON)) 299 300The important parts of that are the second argument (the increment) to HEAP, 301and allowing the stack to be "Above the (16M) line". If the heap 302increment is too small then when perl (for example loading unicode/Name.pl) tries 303to create a "big" (400K+) string it cannot fit in a single segment 304and you get "Out of Memory!" - even if there is still plenty of memory 305available. 306 307A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()> 308to get memory, and C<sbrk()> is limited to the first allocation so in this 309case something like: 310 311 HEAP(8M,500K,ANYWHERE,KEEP,8K,4K) 312 313is needed to get through the test suite. 314 315=head2 Usage Hints for Perl on z/OS 316 317When using Perl on z/OS please keep in mind that the EBCDIC and ASCII 318character sets are different. See L<perlebcdic> for more on such character 319set issues. Perl builtin functions that may behave differently under 320EBCDIC are also mentioned in the perlport.pod document. 321 322If you are having trouble with square brackets then consider switching your 323rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for 324working with Perl on USS. 325 326=head2 Modules and Extensions for Perl on z/OS (Static Only) 327 328Pure Perl (that is non XS) modules may be installed via the usual: 329 330 perl Makefile.PL 331 make 332 make test 333 make install 334 335If you built perl with dynamic loading capability then that would also 336be the way to build XS based extensions. However, if you built perl with 337static linking you can still build XS based extensions for z/OS 338but you will need to follow the instructions in ExtUtils::MakeMaker for 339building statically linked perl binaries. In the simplest configurations 340building a static perl + XS extension boils down to: 341 342 perl Makefile.PL 343 make 344 make perl 345 make test 346 make install 347 make -f Makefile.aperl inst_perl MAP_TARGET=perl 348 349=head2 Running Perl on z/OS 350 351To run the 64-bit Dynamic Perl environment, update your PATH and LIBPATH 352to include the location you installed Perl into, and then run the perl you 353installed as perlV.R.M where V/R/M is the Version/Release/Modification level 354of the current development level. 355If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to 356set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl 357source code you run is tagged appropriately as ASCII or EBCDIC using 358"chtag -t -c<CCSID>": 359 360=over 361 362=item For ASCII Only: 363 364 export _BPXK_AUTOCVT=ON 365 export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)" 366 export _TAG_REDIR_ERR="txt" 367 export _TAG_REDIR_IN="txt" 368 export _TAG_REDIR_OUT="txt" 369 370=item For ASCII or EBCDIC: 371 372 export PATH=/usr/local/perl/ascii:$PATH 373 export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH 374 perlV.R.M args 375 376=back 377 378If tcsh is your login shell then use the setenv command. 379 380=head1 AUTHORS 381 382David Fiander and Peter Prymmer with thanks to Dennis Longnecker 383and William Raffloer for valuable reports, LPAR and PTF feedback. 384Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00. 385Thanks to Ignasi Roca for pointing out the floating point problems. 386Thanks to John Goodyear for dynamic loading help. 387 388Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64-bit and 389ASCII/EBCDIC Bi-Modal support 390 391=head1 OTHER SITES 392 393L<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools 394for building various z/OS Perl configurations and has some useful tools in the 395'bin' directory you may want to use for building z/OS Perl yourself. 396 397=head1 HISTORY 398 399Updated 24 December 2021 to enable initial ASCII support 400 401Updated 03 October 2019 for perl-5.33.3+ 402 403Updated 28 November 2001 for broken URLs. 404 405Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'. 406 407Updated 24 January 2001 to mention dynamic loading. 408 409Updated 15 January 2001 for the 5.7.1 release of Perl. 410 411Updated 12 November 2000 for the 5.7.1 release of Perl. 412 413This document was podified for the 5.005_03 release of Perl 11 March 1999. 414 415This document was originally written by David Fiander for the 5.005 416release of Perl. 417 418=cut 419 420