1PERLOS390(1)           Perl Programmers Reference Guide           PERLOS390(1)
2
3
4

NAME

6       perlos390 - building and installing Perl for z/OS (previously called
7       OS/390)
8

SYNOPSIS

10       This document will help you Configure, build, test and install Perl on
11       z/OS Unix System Services.
12

DESCRIPTION

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
18       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
26       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
32   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
38       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
43       You may also need the gunzip client port that Rocket Software provides
44       to unzip any zipped tarball you upload to z/OS.
45
46   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
53         gunzip perl-V.R.M.tar.gz
54
55       Then one of:
56
57         tar -xvf perl-V.R.M.tar
58
59         pax -r -f perl-V.R.M.tar
60
61       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
65       If instead you want the latest unstable development release, using the
66       native git on z/OS, clone Perl:
67
68         git clone https://github.com/Perl/perl5.git perl
69
70       Either way, once you have a 'perl' directory containing the source, cd
71       into it, and tag all the code as ASCII:
72
73         cd perl
74         chtag -R -h -t -cISO8859-1 *
75
76       Configure the build environment as 64-bit, Dynamic, ASCII, development,
77       deploying it to /usr/local/perl/ascii:
78
79         export PATH=$PWD:$PATH
80         export LIBPATH=$PWD:$PATH
81         ./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \
82               -Duse64bitall -Dusedl
83
84       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
89       Run GNU make to build Perl
90
91         make
92
93       Run tests to ensure Perl is working correctly. Currently, there are
94       about a dozen failing tests out of nearly 2500
95
96         make test_harness
97
98       Install Perl into /usr/local/perl/ascii:
99
100         make install
101
102   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
109       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
113       The downloaded perl will need to be converted to 1047 EBCDIC.  To do
114       this:
115
116         cd perl
117         Porting/makerel -e
118
119       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
123         cd ../
124         tar cf -  --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz
125
126       Use sftp to upload the zipped tar file to z/OS:
127
128         sftp <your system>
129         cd /tmp
130         put perl-V.R.M.tar.gz
131
132       Unzip and untar the zipped tar file on z/OS:
133
134         cd /tmp
135         gunzip perl-V.R.M.tar.gz
136
137       Then one of:
138
139         tar -xvf perl-V.R.M.tar
140
141         pax -r -f perl-V.R.M.tar
142
143       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
148       Configure the build environment as 64-bit, Dynamic, native,
149       development, deploying it to /usr/local/perl/ebcdic:
150
151         export PATH=$PWD:$PATH
152         export LIBPATH=$PWD:$PATH
153         ./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \
154               -Duse64bitall -Dusedl
155
156       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
161       Run GNU make to build Perl
162
163         make
164
165       Run tests to ensure Perl is working correctly.
166
167         make test_harness
168
169       You might also want to have GNU groff for OS/390 installed before
170       running the "make install" step for Perl.
171
172       Install Perl into /usr/local/perl/ebcdic:
173
174         make install
175
176       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
190       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
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
217       See also hints/os390.sh for other potential gotchas.
218
219   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
225       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
229   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
233       Shell
234
235       A message of the form:
236
237        (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
241       is nothing to worry about at all.
242
243       Dynamic loading
244
245       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
250       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
254       Optimizing
255
256       Optimization has not been turned on yet. There may be issues if Perl is
257       optimized.
258
259   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
263       Within USS your /etc/profile or $HOME/.profile may limit your ulimit
264       settings.  Check that the following command returns reasonable values:
265
266           ulimit -a
267
268       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
271       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
275   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
281       Out of Memory (31-bit only)
282
283       Out of memory problems should not be an issue, unless you are
284       attempting to build a 31-bit Perl.
285
286       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
293       The 31-bit C code asks for:
294
295        #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
296
297       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
304       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
308         HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
309
310       is needed to get through the test suite.
311
312   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
319       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
323   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
326           perl Makefile.PL
327           make
328           make test
329           make install
330
331       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
338           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
345   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
355       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
362       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
367       If tcsh is your login shell then use the setenv command.
368

AUTHORS

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
376       Mike Fulton and Karl Williamson have provided updates for UTF8, DLL,
377       64-bit and ASCII/EBCDIC Bi-Modal support
378

OTHER SITES

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

HISTORY

386       Updated 24 December 2021 to enable initial ASCII support
387
388       Updated 03 October  2019 for perl-5.33.3+
389
390       Updated 28 November 2001 for broken URLs.
391
392       Updated 12 March    2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
393
394       Updated 24 January  2001 to mention dynamic loading.
395
396       Updated 15 January  2001 for the 5.7.1 release of Perl.
397
398       Updated 12 November 2000 for the 5.7.1 release of Perl.
399
400       This document was podified for the 5.005_03 release of Perl 11 March
401       1999.
402
403       This document was originally written by David Fiander for the 5.005
404       release of Perl.
405
406
407
408perl v5.38.2                      2023-11-30                      PERLOS390(1)
Impressum