Remove Encode::Tcl::Extended, suggested by
[p5sagit/p5-mst-13.2.git] / README.os390
CommitLineData
9133bbab 1This document is written in pod format hence there are punctuation
a83b6f46 2characters in odd places. Do not worry, you've apparently got the
3ASCII->EBCDIC translation worked out correctly. You can read more
4about pod in pod/perlpod.pod or the short summary in the INSTALL file.
9d116dd7 5
8fde188e 6=head1 NAME
7
37a78d01 8README.os390 - building and installing Perl for OS/390 and z/OS
8fde188e 9
10=head1 SYNOPSIS
11
12This document will help you Configure, build, test and install Perl
37a78d01 13on OS/390 (aka z/OS) Unix System Services.
8fde188e 14
15=head1 DESCRIPTION
16
9133bbab 17This is a fully ported Perl for OS/390 Version 2 Release 3, 5, 6, 7,
188, and 9. It may work on other versions or releases, but those are
eae55d03 19the ones we've tested it on.
8fde188e 20
9133bbab 21You may need to carry out some system configuration tasks before
22running the Configure script for Perl.
8fde188e 23
37a78d01 24
25=head2 Tools
26
27The z/OS Unix Tools and Toys list may prove helpful and contains links
f110302f 28to ports of much of the software helpful for building Perl.
37a78d01 29http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
30
31
a83b6f46 32=head2 Unpacking Perl distribution on OS/390
9d116dd7 33
0e7519cd 34If using ftp remember to transfer the distribution in binary format.
35
9d116dd7 36Gunzip/gzip for OS/390 is discussed at:
37
37a78d01 38 http://www-1.ibm.com/servers/eserver/zseries/zos/unix/faq/bpxqp1.html
9d116dd7 39
40to extract an ASCII tar archive on OS/390, try this:
41
42 pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
43
0e7519cd 44If you get lots of errors of the form
bbee22da 45
46 tar: FSUM7171 ...: cannot set uid/gid: EDC5139I Operation not permitted.
47 tar: FSUM7148 cannot create file "...": EDC5111I Permission denied.
48
0e7519cd 49you didn't read the above and tried to use tar instead of pax, you'll
50first have to remove the (now corrupt) perl directory
51
52 rm -rf perl-...
53
54and then use pax.
bbee22da 55
a83b6f46 56=head2 Setup and utilities for Perl on OS/390
8fde188e 57
58Be sure that your yacc installation is in place including any necessary
59parser template files. If you have not already done so then be sure to:
60
61 cp /samples/yyparse.c /etc
62
9133bbab 63This may also be a good time to ensure that your /etc/protocol file
8fde188e 64and either your /etc/resolv.conf or /etc/hosts files are in place.
eae55d03 65The IBM document that described such USS system setup issues was
66SC28-1890-07 "OS/390 UNIX System Services Planning", in particular
67Chapter 6 on customizing the OE shell.
8fde188e 68
37a78d01 69GNU make for OS/390, which is recommended for the build of perl (as
70well as building CPAN modules and extensions), is available from the
71L</Tools>.
9d116dd7 72
9133bbab 73Some people have reported encountering "Out of memory!" errors while
74trying to build Perl using GNU make binaries. If you encounter such
75trouble then try to download the source code kit and build GNU make
76from source to eliminate any such trouble. You might also find GNU make
77(as well as Perl and Apache) in the red-piece/book "Open Source Software
eae55d03 78for OS/390 UNIX", SG24-5944-00 from IBM.
79
9133bbab 80If instead of the recommended GNU make you would like to use the system
81supplied make program then be sure to install the default rules file
8dd596cc 82properly via the shell command:
83
84 cp /samples/startup.mk /etc
85
86and be sure to also set the environment variable _C89_CCMODE=1 (exporting
87_C89_CCMODE=1 is also a good idea for users of GNU make).
88
f2766b05 89You might also want to have GNU groff for OS/390 installed before
90running the `make install` step for Perl.
91
eae55d03 92There is a syntax error in the /usr/include/sys/socket.h header file
93that IBM supplies with USS V2R7, V2R8, and possibly V2R9. The problem with
94the header file is that near the definition of the SO_REUSEPORT constant
95there is a spurious extra '/' character outside of a comment like so:
96
97 #define SO_REUSEPORT 0x0200 /* allow local address & port
98 reuse */ /
99
9133bbab 100You could edit that header yourself to remove that last '/', or you might
101note that Language Environment (LE) APAR PQ39997 describes the problem
eae55d03 102and PTF's UQ46272 and UQ46271 are the (R8 at least) fixes and apply them.
9133bbab 103If left unattended that syntax error will turn up as an inability for Perl
eae55d03 104to build its "Socket" extension.
105
9133bbab 106For successful testing you may need to turn on the sticky bit for your
eae55d03 107world readable /tmp directory if you have not already done so (see man chmod).
108
a83b6f46 109=head2 Configure Perl on OS/390
8fde188e 110
9133bbab 111Once you've unpacked the distribution, run "sh Configure" (see INSTALL
112for a full discussion of the Configure options). There is a "hints" file
8fde188e 113for os390 that specifies the correct values for most things. Some things
114to watch out for include:
115
116=over 4
117
118=item *
119
eae55d03 120A message of the form:
121
122 (I see you are using the Korn shell. Some ksh's blow up on Configure,
123 mainly on older exotic systems. If yours does, try the Bourne shell instead.)
124
125is nothing to worry about at all.
126
127=item *
128
8fde188e 129Some of the parser default template files in /samples are needed in /etc.
130In particular be sure that you at least copy /samples/yyparse.c to /etc
eae55d03 131before running Perl's Configure. This step ensures successful extraction
9133bbab 132of EBCDIC versions of parser files such as perly.c, perly.h, and x2p/a2p.c.
133This has to be done before running Configure the first time. If you failed
134to do so then the easiest way to re-Configure Perl is to delete your
135misconfigured build root and re-extract the source from the tar ball.
136Then you must ensure that /etc/yyparse.c is properly in place before
59c9e5d6 137attempting to re-run Configure.
8fde188e 138
139=item *
140
f2766b05 141This port will support dynamic loading, but it is not selected by
142default. If you would like to experiment with dynamic loading then
143be sure to specify -Dusedl in the arguments to the Configure script.
144See the comments in hints/os390.sh for more information on dynamic loading.
145If you build with dynamic loading then you will need to add the
146$archlibexp/CORE directory to your LIBPATH environment variable in order
147for perl to work. See the config.sh file for the value of $archlibexp.
59c9e5d6 148If in trying to use Perl you see an error message similar to:
149
150 CEE3501S The module libperl.dll was not found.
151 From entry point __dllstaticinit at compile unit offset +00000194 at
152
9133bbab 153then your LIBPATH does not have the location of libperl.x and either
59c9e5d6 154libperl.dll or libperl.so in it. Add that directory to your LIBPATH and
155proceed.
8fde188e 156
157=item *
9d116dd7 158
eae55d03 159Do not turn on the compiler optimization flag "-O". There is
8fde188e 160a bug in either the optimizer or perl that causes perl to
161not work correctly when the optimizer is on.
9d116dd7 162
8fde188e 163=item *
9d116dd7 164
8fde188e 165Some of the configuration files in /etc used by the
166networking APIs are either missing or have the wrong
167names. In particular, make sure that there's either
eae55d03 168an /etc/resolv.conf or an /etc/hosts, so that
8fde188e 169gethostbyname() works, and make sure that the file
170/etc/proto has been renamed to /etc/protocol (NOT
171/etc/protocols, as used by other Unix systems).
59c9e5d6 172You may have to look for things like HOSTNAME and DOMAINORIGIN
9133bbab 173in the "//'SYS1.TCPPARMS(TCPDATA)'" PDS member in order to
59c9e5d6 174properly set up your /etc networking files.
9d116dd7 175
8fde188e 176=back
177
a83b6f46 178=head2 Build, Test, Install Perl on OS/390
8fde188e 179
180Simply put:
181
182 sh Configure
183 make
184 make test
185
eae55d03 186if everything looks ok (see the next section for test/IVP diagnosis) then:
8fde188e 187
188 make install
189
190this last step may or may not require UID=0 privileges depending
191on how you answered the questions that Configure asked and whether
192or not you have write access to the directories you specified.
193
a83b6f46 194=head2 Build Anomalies with Perl on OS/390
eae55d03 195
196"Out of memory!" messages during the build of Perl are most often fixed
197by re building the GNU make utility for OS/390 from a source code kit.
198
199Another memory limiting item to check is your MAXASSIZE parameter in your
200'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8 address space
9133bbab 201limits can be set on a per user ID basis in the USS segment of a RACF
eae55d03 202profile). People have reported successful builds of Perl with MAXASSIZE
203parameters as small as 503316480 (and it may be possible to build Perl
204with a MAXASSIZE smaller than that).
205
9133bbab 206Within USS your /etc/profile or $HOME/.profile may limit your ulimit
eae55d03 207settings. Check that the following command returns reasonable values:
208
209 ulimit -a
210
211To conserve memory you should have your compiler modules loaded into the
212Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
213
214If the c89 compiler complains of syntax errors during the build of the
215Socket extension then be sure to fix the syntax error in the system
216header /usr/include/sys/socket.h.
217
a83b6f46 218=head2 Testing Anomalies with Perl on OS/390
eae55d03 219
220The `make test` step runs a Perl Verification Procedure, usually before
221installation. You might encounter STDERR messages even during a successful
222run of `make test`. Here is a guide to some of the more commonly seen
223anomalies:
224
225=over 4
226
227=item *
228
229A message of the form:
230
231 comp/cpp.............ERROR CBC3191 ./.301989890.c:1 The character $ is not a
232 valid C source character.
233 FSUM3065 The COMPILE step ended with return code 12.
234 FSUM3017 Could not compile .301989890.c. Correct the errors and try again.
235 ok
236
237indicates that the t/comp/cpp.t test of Perl's -P command line switch has
238passed but that the particular invocation of c89 -E in the cpp script does
239not suppress the C compiler check of source code validity.
240
241=item *
242
243A message of the form:
244
245 io/openpid...........CEE5210S The signal SIGHUP was received.
246 CEE5210S The signal SIGHUP was received.
247 CEE5210S The signal SIGHUP was received.
248 ok
249
250indicates that the t/io/openpid.t test of Perl has passed but done so
251with extraneous messages on stderr from CEE.
252
253=item *
254
255A message of the form:
256
257 lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/) is not safe
258 (sticky bit not set when world writable?) at lib/ftmp-security.t line 100
259 File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky bit not
260 set when world writable?) at lib/ftmp-security.t line 100
261 ok
262
263indicates a problem with the permissions on your /tmp directory within the HFS.
264To correct that problem issue the command:
265
266 chmod a+t /tmp
267
268from an account with write access to the directory entry for /tmp.
269
9133bbab 270=item *
271
272Out of Memory!
273
274Recent perl test suite is quite memory hunrgy. In addition to the comments
275above on memory limitations it is also worth checking for _CEE_RUNOPTS
276in your environment. Perl now has (in miniperlmain.c) a C #pragma
210b36aa 277to set CEE run options, but the environment variable wins.
9133bbab 278
210b36aa 279The C code asks for:
9133bbab 280
281 #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
282
283The important parts of that are the second argument (the increment) to HEAP,
284and allowing the stack to be "Above the (16M) line". If the heap
210b36aa 285increment is too small then when perl (for example loading unicode/Name.pl) tries
286to create a "big" (400K+) string it cannot fit in a single segment
9133bbab 287and you get "Out of Memory!" - even if there is still plenty of memory
288available.
289
290A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()>
291to get memory, and C<sbrk()> is limited to the first allocation so in this
292case something like:
293
294 HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
295
296is needed to get through the test suite.
297
298
eae55d03 299=back
300
a83b6f46 301=head2 Installation Anomalies with Perl on OS/390
f2766b05 302
303The installman script will try to run on OS/390. There will be fewer errors
9133bbab 304if you have a roff utility installed. You can obtain GNU groff from the
f2766b05 305Redbook SG24-5944-00 ftp site.
306
a83b6f46 307=head2 Usage Hints for Perl on OS/390
64d55c8a 308
9d116dd7 309When using perl on OS/390 please keep in mind that the EBCDIC and ASCII
9133bbab 310character sets are different. See perlebcdic.pod for more on such character
311set issues. Perl builtin functions that may behave differently under
eae55d03 312EBCDIC are also mentioned in the perlport.pod document.
9d116dd7 313
9133bbab 314Open Edition (UNIX System Services) from V2R8 onward does support
315#!/path/to/perl script invocation. There is a PTF available from
eae55d03 316IBM for V2R7 that will allow shell/kernel support for #!. USS
9133bbab 317releases prior to V2R7 did not support the #! means of script invocation.
eae55d03 318If you are running V2R6 or earlier then see:
9d116dd7 319
320 head `whence perldoc`
321
322for an example of how to use the "eval exec" trick to ask the shell to
eae55d03 323have Perl run your scripts on those older releases of Unix System Services.
324
59c9e5d6 325If you are having trouble with square brackets then consider switching your
9133bbab 326rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for
59c9e5d6 327working with Perl on USS.
328
a83b6f46 329=head2 Floating Point Anomalies with Perl on OS/390
35a77668 330
9133bbab 331There appears to be a bug in the floating point implementation on S/390
332systems such that calling int() on the product of a number and a small
333magnitude number is not the same as calling int() on the quotient of
334that number and a large magnitude number. For example, in the following
35a77668 335Perl code:
336
337 my $x = 100000.0;
338 my $y = int($x * 1e-5) * 1e5; # '0'
339 my $z = int($x / 1e+5) * 1e5; # '100000'
340 print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
341
9133bbab 342Although one would expect the quantities $y and $z to be the same and equal
35a77668 343to 100000 they will differ and instead will be 0 and 100000 respectively.
344
345The problem can be further examined in a roughly equivalent C program:
346
347 #include <stdio.h>
348 #include <math.h>
349 main()
350 {
351 double r1,r2;
352 double x = 100000.0;
353 double y = 0.0;
354 double z = 0.0;
355 x = 100000.0 * 1e-5;
356 r1 = modf (x,&y);
357 x = 100000.0 / 1e+5;
358 r2 = modf (x,&z);
359 printf("y is %e and z is %e\n",y*1e5,z*1e5);
360 /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
361 }
362
a83b6f46 363=head2 Modules and Extensions for Perl on OS/390
eae55d03 364
365Pure pure (that is non xs) modules may be installed via the usual:
366
367 perl Makefile.PL
368 make
369 make test
370 make install
371
f2766b05 372If you built perl with dynamic loading capability then that would also
373be the way to build xs based extensions. However, if you built perl with
9133bbab 374the default static linking you can still build xs based extensions for OS/390
375but you will need to follow the instructions in ExtUtils::MakeMaker for
376building statically linked perl binaries. In the simplest configurations
59c9e5d6 377building a static perl + xs extension boils down to:
9d116dd7 378
eae55d03 379 perl Makefile.PL
380 make
381 make perl
382 make test
383 make install
384 make -f Makefile.aperl inst_perl MAP_TARGET=perl
8fde188e 385
9133bbab 386In most cases people have reported better results with GNU make rather
eae55d03 387than the system's /bin/make program, whether for plain modules or for
388xs based extensions.
8fde188e 389
f2766b05 390If the make process encounters trouble with either compilation or
391linking then try setting the _C89_CCMODE to 1. Assuming sh is your
392login shell then run:
393
394 export _C89_CCMODE=1
395
396If tcsh is your login shell then use the setenv command.
397
8fde188e 398=head1 AUTHORS
399
eae55d03 400David Fiander and Peter Prymmer with thanks to Dennis Longnecker
401and William Raffloer for valuable reports, LPAR and PTF feedback.
402Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
35a77668 403Thanks to Ignasi Roca for pointing out the floating point problems.
f2766b05 404Thanks to John Goodyear for dynamic loading help.
8fde188e 405
406=head1 SEE ALSO
407
eae55d03 408L<INSTALL>, L<perlport>, L<perlebcdic>, L<ExtUtils::MakeMaker>.
409
37a78d01 410 http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
eae55d03 411
412 http://www.redbooks.ibm.com/abstracts/sg245944.html
413
1e32511c 414 http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc
eae55d03 415
416 http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
8fde188e 417
9133bbab 418 http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/ceea3030/
419
420 http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/CBCUG030/
421
a83b6f46 422=head2 Mailing list for Perl on OS/390
8fde188e 423
9133bbab 424The Perl Institute (http://www.perl.org/) maintains a perl-mvs
8fde188e 425mailing list of interest to all folks building and/or
9133bbab 426using perl on all EBCDIC platforms (not just OS/390).
eae55d03 427To subscribe, send a message of:
9d116dd7 428
429 subscribe perl-mvs
430
35a77668 431to majordomo@perl.org. See also:
432
433 http://lists.perl.org/showlist.cgi?name=perl-mvs
434
435There are web archives of the mailing list at:
eae55d03 436
437 http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
35a77668 438 http://archive.develooper.com/perl-mvs@perl.org/
9d116dd7 439
8fde188e 440=head1 HISTORY
441
442This document was originally written by David Fiander for the 5.005
443release of Perl.
444
eae55d03 445This document was podified for the 5.005_03 release of Perl 11 March 1999.
446
37a78d01 447Updated 28 November 2001 for broken URLs.
448
eae55d03 449Updated 12 November 2000 for the 5.7.1 release of Perl.
8fde188e 450
35a77668 451Updated 15 January 2001 for the 5.7.1 release of Perl.
452
f2766b05 453Updated 24 January 2001 to mention dynamic loading.
454
59c9e5d6 455Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
456
8fde188e 457=cut
eae55d03 458