3 This document is written in pod format hence there are punctuation
4 characters in odd places. You can read more
5 about pod in pod/perlpod.pod or the short summary in the INSTALL file.
9 perlos390 - building and installing Perl for z/OS (previously called OS/390)
13 This document will help you Configure, build, test and install Perl
14 on z/OS Unix System Services.
18 This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and
19 should work fine with z/OS 2.5.
20 It may work on other versions or releases, but those are
21 the ones it has been tested on.
23 The native character set for z/OS is EBCDIC, but it can also run in ASCII mode.
24 Perl can support either, but you have to compile it explicitly for one or the
25 other. You could have both an ASCII perl, and an EBCDIC perl on the same
26 machine. If you use ASCII mode and an ASCII perl, the Encode module shipped
27 with perl can be used to translate files from various EBCDIC code pages for
28 handling by perl, and then back on output
30 This document describes how to build a 64-bit Dynamic Perl, either ASCII or
31 EBCDIC. You can interactively choose other configurations, as well as many
32 other options in the Configure script that is run as part of the build
33 process. You may need to carry out some system configuration tasks before
34 running Configure, as detailed below.
38 You will want to get GNU make 4.1 or later. GNU make can be downloaded from a
39 port that Rocket Software provides. You will need the z/OS c99 compiler from
40 IBM (though xlc in c99 mode without optimization turned on works in EBCDIC).
42 If you want the latest development version of Perl, you will need git.
43 You can use git on another platform and transfer the result via sftp or ftp to
44 z/OS. But there is a z/OS native git client port available through Rocket
47 You may also need the gunzip client port that Rocket Software provides to unzip
48 any zipped tarball you upload to z/OS.
50 =head2 Building a 64-bit Dynamic ASCII Perl
52 For building from an official stable release of Perl, go to
53 L<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
55 name of that tarball will be something like 'perl-V.R.M,tar,gz', where V.R.M is
56 the version/release/modification of the perl you are downloading. Do
58 gunzip perl-V.R.M.tar.gz
62 tar -xvf perl-V.R.M.tar
64 pax -r -f perl-V.R.M.tar
66 Either of these will create the source directory. You can rename it to
67 whatever you like; for these instructions, 'perl' is assumed to be the name.
69 If instead you want the latest unstable development release, using the native
70 git on z/OS, clone Perl:
72 git clone https://github.com/Perl/perl5.git perl
74 Either way, once you have a 'perl' directory containing the source, cd into it,
75 and tag all the code as ASCII:
78 chtag -R -h -t -cISO8859-1 *
80 Configure the build environment as 64-bit, Dynamic, ASCII, development,
81 deploying it to F</usr/local/perl/ascii>:
83 export PATH=$PWD:$PATH
84 export LIBPATH=$PWD:$PATH
85 ./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \
88 If 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
90 every possible option based on its probing of what's available on your
91 particular machine, so you can choose as you go along.)
93 Run GNU make to build Perl
97 Run tests to ensure Perl is working correctly. Currently, there are about a
98 dozen failing tests out of nearly 2500
102 Install Perl into F</usr/local/perl/ascii>:
106 =head2 Building a 64-bit Dynamic EBCDIC Perl
108 You will need a working perl on some box with connectivity to the destination
109 machine. On z/OS, it could be an ASCII perl, or a previous EBCDIC one.
110 Many machines will already have a pre-built perl already running, or one can
111 easily be downloaded from L<https://www.perl.org/get.html>.
113 Follow the directions above in "Building a 64-bit Dynamic ASCII Perl" as far as
114 getting a populated 'perl' directory. Then come back here to proceed.
116 The downloaded perl will need to be converted to 1047 EBCDIC. To do this:
121 If the Porting/makerel step fails with an error that it can not issue the tar
122 command, proceed to issue the command interactively, where V.R.M is the
123 version/release/modification of Perl you are uploading:
126 tar cf - --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz
128 Use sftp to upload the zipped tar file to z/OS:
132 put perl-V.R.M.tar.gz
134 Unzip and untar the zipped tar file on z/OS:
137 gunzip perl-V.R.M.tar.gz
141 tar -xvf perl-V.R.M.tar
143 pax -r -f perl-V.R.M.tar
145 You now have the source code for the EBCDIC Perl on z/OS and can proceed to
146 build it. This is analagous to how you would build the code for ASCII, but
147 note: you B<should not> tag the code but instead leave it untagged.
149 Configure the build environment as 64-bit, Dynamic, native, development,
150 deploying it to F</usr/local/perl/ebcdic>:
152 export PATH=$PWD:$PATH
153 export LIBPATH=$PWD:$PATH
154 ./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \
155 -Duse64bitall -Dusedl
157 If 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
159 every possible option based on its probing of what's available on your
160 particular machine, so you can choose as you go along.)
162 Run GNU make to build Perl
166 Run tests to ensure Perl is working correctly.
170 You might also want to have GNU groff for OS/390 installed before
171 running the "make install" step for Perl.
173 Install Perl into F</usr/local/perl/ebcdic>:
177 EBCDIC Perl is still a work in progress. All the core code works as far as we
178 know, but various modules you might want to download from CPAN do not. The
179 failures range from very minor to catastrophic. Many of them are simply bugs
180 in the tests, with the module actually working properly. This happens because,
181 for example, the test is coded to expect a certain character ASCII code point;
182 when it gets the EBCDIC value back instead, it complains. But the code
183 actually worked. Other potential failures that aren't really failures stem
184 from checksums coming out differently, since C<A>, for example, has a different
185 bit representation between the character sets. A test that is expecting the
186 ASCII value will show failure, even if the module is working perfectly. Also
187 in sorting, uppercase letters come before lowercase letters on ASCII systems;
188 the reverse on EBCDIC.
190 Some CPAN modules come bundled with the downloaded perl. And a few of those
191 have yet to be fixed to pass on EBCDIC platforms. As a result they are skipped
192 when you run 'make test'. The current list is:
210 PerlIO::via-QuotedPrint
217 See also F<hints/os390.sh> for other potential gotchas.
219 =head2 Setup and utilities for Perl on OS/390
221 This may also be a good time to ensure that your F</etc/protocol> file
222 and either your F</etc/resolv.conf> or F</etc/hosts> files are in place.
223 The IBM document that describes such USS system setup issues is
224 "z/OS UNIX System Services Planning"
226 For successful testing you may need to turn on the sticky bit for your
227 world readable /tmp directory if you have not already done so (see man chmod).
229 =head2 Useful files for trouble-shooting
231 If your configuration is failing, read hints/os390.sh
232 This file provides z/OS specific options to direct the build process.
236 A message of the form:
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
242 is nothing to worry about at all.
244 =head3 Dynamic loading
246 Dynamic loading is required if you want to use XS modules from CPAN (like
247 DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from
248 CPAN with newer versions (like Encode) without rebuilding all of the perl
251 The instructions above will create a dynamic Perl. If you do not want to
252 use dynamic loading, remove the -Dusedl option.
253 See the comments in hints/os390.sh for more information on dynamic loading.
257 Optimization has not been turned on yet. There may be issues if Perl
260 =head2 Build Anomalies with Perl on OS/390
262 "Out of memory!" messages during the build of Perl are most often fixed
263 by re building the GNU make utility for OS/390 from a source code kit.
265 Within USS your F</etc/profile> or F<$HOME/.profile> may limit your ulimit
266 settings. Check that the following command returns reasonable values:
270 To conserve memory you should have your compiler modules loaded into the
271 Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
273 If the compiler complains of syntax errors during the build of the
274 Socket extension then be sure to fix the syntax error in the system
275 header /usr/include/sys/socket.h.
277 =head2 Testing Anomalies with Perl on OS/390
279 The "make test" step runs a Perl Verification Procedure, usually before
280 installation. You might encounter STDERR messages even during a successful
281 run of "make test". Here is a guide to some of the more commonly seen
284 =head3 Out of Memory (31-bit only)
286 Out of memory problems should not be an issue, unless you are attempting to build
289 If you _are_ building a 31-bit Perl, the constrained environment may mean you
290 need to change memory options for Perl.
291 In addition to the comments
292 above on memory limitations it is also worth checking for _CEE_RUNOPTS
293 in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31-bit only
294 to set CEE run options, but the environment variable wins.
296 The 31-bit C code asks for:
298 #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
300 The important parts of that are the second argument (the increment) to HEAP,
301 and allowing the stack to be "Above the (16M) line". If the heap
302 increment is too small then when perl (for example loading unicode/Name.pl) tries
303 to create a "big" (400K+) string it cannot fit in a single segment
304 and you get "Out of Memory!" - even if there is still plenty of memory
307 A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()>
308 to get memory, and C<sbrk()> is limited to the first allocation so in this
311 HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
313 is needed to get through the test suite.
315 =head2 Usage Hints for Perl on z/OS
317 When using Perl on z/OS please keep in mind that the EBCDIC and ASCII
318 character sets are different. See L<perlebcdic> for more on such character
319 set issues. Perl builtin functions that may behave differently under
320 EBCDIC are also mentioned in the perlport.pod document.
322 If you are having trouble with square brackets then consider switching your
323 rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for
324 working with Perl on USS.
326 =head2 Modules and Extensions for Perl on z/OS (Static Only)
328 Pure Perl (that is non XS) modules may be installed via the usual:
335 If you built perl with dynamic loading capability then that would also
336 be the way to build XS based extensions. However, if you built perl with
337 static linking you can still build XS based extensions for z/OS
338 but you will need to follow the instructions in ExtUtils::MakeMaker for
339 building statically linked perl binaries. In the simplest configurations
340 building a static perl + XS extension boils down to:
347 make -f Makefile.aperl inst_perl MAP_TARGET=perl
349 =head2 Running Perl on z/OS
351 To run the 64-bit Dynamic Perl environment, update your PATH and LIBPATH
352 to include the location you installed Perl into, and then run the perl you
353 installed as perlV.R.M where V/R/M is the Version/Release/Modification level
354 of the current development level.
355 If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to
356 set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl
357 source code you run is tagged appropriately as ASCII or EBCDIC using
358 "chtag -t -c<CCSID>":
362 =item For ASCII Only:
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"
370 =item For ASCII or EBCDIC:
372 export PATH=/usr/local/perl/ascii:$PATH
373 export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH
378 If tcsh is your login shell then use the setenv command.
382 David Fiander and Peter Prymmer with thanks to Dennis Longnecker
383 and William Raffloer for valuable reports, LPAR and PTF feedback.
384 Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
385 Thanks to Ignasi Roca for pointing out the floating point problems.
386 Thanks to John Goodyear for dynamic loading help.
388 Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64-bit and
389 ASCII/EBCDIC Bi-Modal support
393 L<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools
394 for 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.
399 Updated 24 December 2021 to enable initial ASCII support
401 Updated 03 October 2019 for perl-5.33.3+
403 Updated 28 November 2001 for broken URLs.
405 Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
407 Updated 24 January 2001 to mention dynamic loading.
409 Updated 15 January 2001 for the 5.7.1 release of Perl.
411 Updated 12 November 2000 for the 5.7.1 release of Perl.
413 This document was podified for the 5.005_03 release of Perl 11 March 1999.
415 This document was originally written by David Fiander for the 5.005