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

NAME

6       perlos390 - building and installing Perl for OS/390 and z/OS
7

SYNOPSIS

9       This document will help you Configure, build, test and install Perl on
10       OS/390 (aka z/OS) Unix System Services.
11
12       This document needs to be updated, but we don't know what it should
13       say.  Please submit comments to <https://github.com/Perl/perl5/issues>.
14

DESCRIPTION

16       This is a fully ported Perl for OS/390 Version 2 Release 3, 5, 6, 7, 8,
17       and 9.  It may work on other versions or releases, but those are the
18       ones we have tested it on.
19
20       You may need to carry out some system configuration tasks before
21       running the Configure script for Perl.
22
23   Tools
24       The z/OS Unix Tools and Toys list may prove helpful and contains links
25       to ports of much of the software helpful for building Perl.
26       <http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html>
27
28   Unpacking Perl distribution on OS/390
29       If using ftp remember to transfer the distribution in binary format.
30
31       Gunzip/gzip for OS/390 is discussed at:
32
33         http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html
34
35       to extract an ASCII tar archive on OS/390, try this:
36
37          pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
38
39       or
40
41          zcat latest.tar.Z | pax -o to=IBM-1047,from=ISO8859-1 -r
42
43       If you get lots of errors of the form
44
45        tar: FSUM7171 ...: cannot set uid/gid: EDC5139I Operation not permitted
46
47       you did not read the above and tried to use tar instead of pax, you'll
48       first have to remove the (now corrupt) perl directory
49
50          rm -rf perl-...
51
52       and then use pax.
53
54   Setup and utilities for Perl on OS/390
55       Be sure that your yacc installation is in place including any necessary
56       parser template files. If you have not already done so then be sure to:
57
58         cp /samples/yyparse.c /etc
59
60       This may also be a good time to ensure that your /etc/protocol file and
61       either your /etc/resolv.conf or /etc/hosts files are in place.  The IBM
62       document that described such USS system setup issues was SC28-1890-07
63       "OS/390 UNIX System Services Planning", in particular Chapter 6 on
64       customizing the OE shell.
65
66       GNU make for OS/390, which is recommended for the build of perl (as
67       well as building CPAN modules and extensions), is available from the
68       "Tools".
69
70       Some people have reported encountering "Out of memory!" errors while
71       trying to build Perl using GNU make binaries.  If you encounter such
72       trouble then try to download the source code kit and build GNU make
73       from source to eliminate any such trouble.  You might also find GNU
74       make (as well as Perl and Apache) in the red-piece/book "Open Source
75       Software for OS/390 UNIX", SG24-5944-00 from IBM.
76
77       If instead of the recommended GNU make you would like to use the system
78       supplied make program then be sure to install the default rules file
79       properly via the shell command:
80
81           cp /samples/startup.mk /etc
82
83       and be sure to also set the environment variable _C89_CCMODE=1
84       (exporting _C89_CCMODE=1 is also a good idea for users of GNU make).
85
86       You might also want to have GNU groff for OS/390 installed before
87       running the "make install" step for Perl.
88
89       There is a syntax error in the /usr/include/sys/socket.h header file
90       that IBM supplies with USS V2R7, V2R8, and possibly V2R9.  The problem
91       with the header file is that near the definition of the SO_REUSEPORT
92       constant there is a spurious extra '/' character outside of a comment
93       like so:
94
95        #define SO_REUSEPORT    0x0200    /* allow local address & port
96                                             reuse */                    /
97
98       You could edit that header yourself to remove that last '/', or you
99       might note that Language Environment (LE) APAR PQ39997 describes the
100       problem and PTF's UQ46272 and UQ46271 are the (R8 at least) fixes and
101       apply them.  If left unattended that syntax error will turn up as an
102       inability for Perl to build its "Socket" extension.
103
104       For successful testing you may need to turn on the sticky bit for your
105       world readable /tmp directory if you have not already done so (see man
106       chmod).
107
108   Configure Perl on OS/390
109       Once you have unpacked the distribution, run "sh Configure" (see
110       INSTALL for a full discussion of the Configure options).  There is a
111       "hints" file for os390 that specifies the correct values for most
112       things.  Some things to watch out for include:
113
114       Shell
115
116       A message of the form:
117
118        (I see you are using the Korn shell.  Some ksh's blow up on Configure,
119        mainly on older exotic systems.  If yours does, try the Bourne shell instead.)
120
121       is nothing to worry about at all.
122
123       Samples
124
125       Some of the parser default template files in /samples are needed in
126       /etc.  In particular be sure that you at least copy /samples/yyparse.c
127       to /etc before running Perl's Configure.  This step ensures successful
128       extraction of EBCDIC versions of parser files such as perly.c and
129       perly.h.  This has to be done before running Configure the first time.
130       If you failed to do so then the easiest way to re-Configure Perl is to
131       delete your misconfigured build root and re-extract the source from the
132       tar ball.  Then you must ensure that /etc/yyparse.c is properly in
133       place before attempting to re-run Configure.
134
135       Dynamic loading
136
137       Dynamic loading is required if you want to use XS modules from CPAN
138       (like DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE
139       modules from CPAN with newer versions (like Encode) without rebuilding
140       all of the perl binary.
141
142       This port will support dynamic loading, but it is not selected by
143       default.  If you would like to experiment with dynamic loading then be
144       sure to specify -Dusedl in the arguments to the Configure script.  See
145       the comments in hints/os390.sh for more information on dynamic loading.
146       If you build with dynamic loading then you will need to add the
147       $archlibexp/CORE directory to your LIBPATH environment variable in
148       order for perl to work.  See the config.sh file for the value of
149       $archlibexp.  If in trying to use Perl you see an error message similar
150       to:
151
152        CEE3501S The module libperl.dll was not found.
153          From entry point __dllstaticinit at compile unit offset +00000194
154          at
155
156       then your LIBPATH does not have the location of libperl.x and either
157       libperl.dll or libperl.so in it.  Add that directory to your LIBPATH
158       and proceed.
159
160       In hints/os390.sh, selecting -Dusedl will default to *also* select
161       -Duseshrplib.  Having a shared plib not only requires LIBPATH to be set
162       to the correct location of libperl.so but also makes it close to
163       impossible to run more than one different perl that was built this way
164       at the same time.
165
166       All objects that are involved in -Dusedl builds should be compiled for
167       this, probably by adding to all ccflags
168
169        -qexportall -qxplink -qdll -Wc,XPLINK,dll,EXPORTALL -Wl,XPLINK,dll
170
171       Optimizing
172
173       Do not turn on the compiler optimization flag "-O".  There is a bug in
174       either the optimizer or perl that causes perl to not work correctly
175       when the optimizer is on.
176
177       Config files
178
179       Some of the configuration files in /etc used by the networking APIs are
180       either missing or have the wrong names.  In particular, make sure that
181       there's either an /etc/resolv.conf or an /etc/hosts, so that
182       gethostbyname() works, and make sure that the file /etc/proto has been
183       renamed to /etc/protocol (NOT /etc/protocols, as used by other Unix
184       systems).  You may have to look for things like HOSTNAME and
185       DOMAINORIGIN in the "//'SYS1.TCPPARMS(TCPDATA)'" PDS member in order to
186       properly set up your /etc networking files.
187
188   Build, Test, Install Perl on OS/390
189       Simply put:
190
191           sh Configure
192           make
193           make test
194
195       if everything looks ok (see the next section for test/IVP diagnosis)
196       then:
197
198           make install
199
200       this last step may or may not require UID=0 privileges depending on how
201       you answered the questions that Configure asked and whether or not you
202       have write access to the directories you specified.
203
204   Build Anomalies with Perl on OS/390
205       "Out of memory!" messages during the build of Perl are most often fixed
206       by re building the GNU make utility for OS/390 from a source code kit.
207
208       Building debugging-enabled binaries (with -g or -g3) will increase the
209       chance of getting these errors. Prevent -g if possible.
210
211       Another memory limiting item to check is your MAXASSIZE parameter in
212       your 'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8
213       address space limits can be set on a per user ID basis in the USS
214       segment of a RACF profile).  People have reported successful builds of
215       Perl with MAXASSIZE parameters as small as 503316480 (and it may be
216       possible to build Perl with a MAXASSIZE smaller than that).
217
218       Within USS your /etc/profile or $HOME/.profile may limit your ulimit
219       settings.  Check that the following command returns reasonable values:
220
221           ulimit -a
222
223       To conserve memory you should have your compiler modules loaded into
224       the Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
225
226       If the c89 compiler complains of syntax errors during the build of the
227       Socket extension then be sure to fix the syntax error in the system
228       header /usr/include/sys/socket.h.
229
230   Testing Anomalies with Perl on OS/390
231       The "make test" step runs a Perl Verification Procedure, usually before
232       installation.  You might encounter STDERR messages even during a
233       successful run of "make test".  Here is a guide to some of the more
234       commonly seen anomalies:
235
236       Signals
237
238       A message of the form:
239
240        io/openpid...........CEE5210S The signal SIGHUP was received.
241        CEE5210S The signal SIGHUP was received.
242        CEE5210S The signal SIGHUP was received.
243        ok
244
245       indicates that the t/io/openpid.t test of Perl has passed but done so
246       with extraneous messages on stderr from CEE.
247
248       File::Temp
249
250       A message of the form:
251
252        lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/)
253        is not safe (sticky bit not set when world writable?) at
254        lib/ftmp-security.t line 100
255        File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky
256        bit not set when world writable?) at lib/ftmp-security.t line 100
257        ok
258
259       indicates a problem with the permissions on your /tmp directory within
260       the HFS.  To correct that problem issue the command:
261
262           chmod a+t /tmp
263
264       from an account with write access to the directory entry for /tmp.
265
266       Out of Memory!
267
268       Recent perl test suite is quite memory hungry. In addition to the
269       comments above on memory limitations it is also worth checking for
270       _CEE_RUNOPTS in your environment. Perl now has (in miniperlmain.c) a C
271       #pragma to set CEE run options, but the environment variable wins.
272
273       The C code asks for:
274
275        #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
276
277       The important parts of that are the second argument (the increment) to
278       HEAP, and allowing the stack to be "Above the (16M) line". If the heap
279       increment is too small then when perl (for example loading
280       unicode/Name.pl) tries to create a "big" (400K+) string it cannot fit
281       in a single segment and you get "Out of Memory!" - even if there is
282       still plenty of memory available.
283
284       A related issue is use with perl's malloc. Perl's malloc uses "sbrk()"
285       to get memory, and "sbrk()" is limited to the first allocation so in
286       this case something like:
287
288         HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
289
290       is needed to get through the test suite.
291
292   Installation Anomalies with Perl on OS/390
293       The installman script will try to run on OS/390.  There will be fewer
294       errors if you have a roff utility installed.  You can obtain GNU groff
295       from the Redbook SG24-5944-00 ftp site.
296
297   Usage Hints for Perl on OS/390
298       When using perl on OS/390 please keep in mind that the EBCDIC and ASCII
299       character sets are different.  See perlebcdic.pod for more on such
300       character set issues.  Perl builtin functions that may behave
301       differently under EBCDIC are also mentioned in the perlport.pod
302       document.
303
304       Open Edition (UNIX System Services) from V2R8 onward does support
305       #!/path/to/perl script invocation.  There is a PTF available from IBM
306       for V2R7 that will allow shell/kernel support for #!.  USS releases
307       prior to V2R7 did not support the #! means of script invocation.  If
308       you are running V2R6 or earlier then see:
309
310           head `whence perldoc`
311
312       for an example of how to use the "eval exec" trick to ask the shell to
313       have Perl run your scripts on those older releases of Unix System
314       Services.
315
316       If you are having trouble with square brackets then consider switching
317       your rlogin or telnet client.  Try to avoid older 3270 emulators and
318       ISHELL for working with Perl on USS.
319
320   Floating Point Anomalies with Perl on OS/390
321       There appears to be a bug in the floating point implementation on S/390
322       systems such that calling int() on the product of a number and a small
323       magnitude number is not the same as calling int() on the quotient of
324       that number and a large magnitude number.  For example, in the
325       following Perl code:
326
327           my $x = 100000.0;
328           my $y = int($x * 1e-5) * 1e5; # '0'
329           my $z = int($x / 1e+5) * 1e5;  # '100000'
330           print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
331
332       Although one would expect the quantities $y and $z to be the same and
333       equal to 100000 they will differ and instead will be 0 and 100000
334       respectively.
335
336       The problem can be further examined in a roughly equivalent C program:
337
338           #include <stdio.h>
339           #include <math.h>
340           main()
341           {
342           double r1,r2;
343           double x = 100000.0;
344           double y = 0.0;
345           double z = 0.0;
346           x = 100000.0 * 1e-5;
347           r1 = modf (x,&y);
348           x = 100000.0 / 1e+5;
349           r2 = modf (x,&z);
350           printf("y is %e and z is %e\n",y*1e5,z*1e5);
351           /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
352           }
353
354   Modules and Extensions for Perl on OS/390
355       Pure Perl (that is non XS) modules may be installed via the usual:
356
357           perl Makefile.PL
358           make
359           make test
360           make install
361
362       If you built perl with dynamic loading capability then that would also
363       be the way to build XS based extensions.  However, if you built perl
364       with the default static linking you can still build XS based extensions
365       for OS/390 but you will need to follow the instructions in
366       ExtUtils::MakeMaker for building statically linked perl binaries.  In
367       the simplest configurations building a static perl + XS extension boils
368       down to:
369
370           perl Makefile.PL
371           make
372           make perl
373           make test
374           make install
375           make -f Makefile.aperl inst_perl MAP_TARGET=perl
376
377       In most cases people have reported better results with GNU make rather
378       than the system's /bin/make program, whether for plain modules or for
379       XS based extensions.
380
381       If the make process encounters trouble with either compilation or
382       linking then try setting the _C89_CCMODE to 1.  Assuming sh is your
383       login shell then run:
384
385           export _C89_CCMODE=1
386
387       If tcsh is your login shell then use the setenv command.
388

AUTHORS

390       David Fiander and Peter Prymmer with thanks to Dennis Longnecker and
391       William Raffloer for valuable reports, LPAR and PTF feedback.  Thanks
392       to Mike MacIsaac and Egon Terwedow for SG24-5944-00.  Thanks to Ignasi
393       Roca for pointing out the floating point problems.  Thanks to John
394       Goodyear for dynamic loading help.
395

SEE ALSO

397       INSTALL, perlport, perlebcdic, ExtUtils::MakeMaker.
398
399        http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
400
401        http://www.redbooks.ibm.com/redbooks/SG245944.html
402
403        http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc
404
405        http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
406
407        http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/ceea3030/
408
409        http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/CBCUG030/
410
411   Mailing list for Perl on OS/390
412       If you are interested in the z/OS (formerly known as OS/390) and POSIX-
413       BC (BS2000) ports of Perl then see the perl-mvs mailing list.  To
414       subscribe, send an empty message to perl-mvs-subscribe@perl.org.
415
416       See also:
417
418           https://lists.perl.org/list/perl-mvs.html
419
420       There are web archives of the mailing list at:
421
422           https://www.nntp.perl.org/group/perl.mvs/
423

HISTORY

425       This document was originally written by David Fiander for the 5.005
426       release of Perl.
427
428       This document was podified for the 5.005_03 release of Perl 11 March
429       1999.
430
431       Updated 12 November 2000 for the 5.7.1 release of Perl.
432
433       Updated 15 January  2001 for the 5.7.1 release of Perl.
434
435       Updated 24 January  2001 to mention dynamic loading.
436
437       Updated 12 March    2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
438
439       Updated 28 November 2001 for broken URLs.
440
441       Updated 03 October  2019 for perl-5.32.0+
442
443
444
445perl v5.32.1                      2021-05-31                      PERLOS390(1)
Impressum