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