Debian Codegraph @

upstream/debian-unstable/man1/perlos390.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLOS390 1"
58 .TH PERLOS390 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlos390 \- building and installing Perl for z/OS (previously called OS/390)
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 This document will help you Configure, build, test and install Perl
68 on z/OS Unix System Services.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and
72 should work fine with z/OS 2.5.
73 It may work on other versions or releases, but those are
74 the ones it has been tested on.
75 .PP
76 The native character set for z/OS is EBCDIC, but it can also run in ASCII mode.
77 Perl can support either, but you have to compile it explicitly for one or the
78 other. You could have both an ASCII perl, and an EBCDIC perl on the same
79 machine. If you use ASCII mode and an ASCII perl, the Encode module shipped
80 with perl can be used to translate files from various EBCDIC code pages for
81 handling by perl, and then back on output
82 .PP
83 This document describes how to build a 64\-bit Dynamic Perl, either ASCII or
84 EBCDIC. You can interactively choose other configurations, as well as many
85 other options in the Configure script that is run as part of the build
86 process. You may need to carry out some system configuration tasks before
87 running Configure, as detailed below.
88 .SS Tools
89 .IX Subsection "Tools"
90 You will want to get GNU make 4.1 or later. GNU make can be downloaded from a
91 port that Rocket Software provides. You will need the z/OS c99 compiler from
92 IBM (though xlc in c99 mode without optimization turned on works in EBCDIC).
93 .PP
94 If you want the latest development version of Perl, you will need git.
95 You can use git on another platform and transfer the result via sftp or ftp to
96 z/OS. But there is a z/OS native git client port available through Rocket
97 Software.
98 .PP
99 You may also need the gunzip client port that Rocket Software provides to unzip
100 any zipped tarball you upload to z/OS.
101 .SS "Building a 64\-bit Dynamic ASCII Perl"
102 .IX Subsection "Building a 64-bit Dynamic ASCII Perl"
103 For building from an official stable release of Perl, go to
104 <https://www.perl.org/get.html> and choose any one of the
105 "Download latest stable source" buttons. This will get you a tarball. The
106 name of that tarball will be something like 'perl\-V.R.M,tar,gz', where V.R.M is
107 the version/release/modification of the perl you are downloading. Do
108 .PP
109 .Vb 1
110 \& gunzip perl\-V.R.M.tar.gz
111 .Ve
112 .PP
113 Then one of:
114 .PP
115 .Vb 1
116 \& tar \-xvf perl\-V.R.M.tar
117 \&
118 \& pax \-r \-f perl\-V.R.M.tar
119 .Ve
120 .PP
121 Either of these will create the source directory. You can rename it to
122 whatever you like; for these instructions, 'perl' is assumed to be the name.
123 .PP
124 If instead you want the latest unstable development release, using the native
125 git on z/OS, clone Perl:
126 .PP
127 .Vb 1
128 \& git clone https://github.com/Perl/perl5.git perl
129 .Ve
130 .PP
131 Either way, once you have a 'perl' directory containing the source, cd into it,
132 and tag all the code as ASCII:
133 .PP
134 .Vb 2
135 \& cd perl
136 \& chtag \-R \-h \-t \-cISO8859\-1 *
137 .Ve
138 .PP
139 Configure the build environment as 64\-bit, Dynamic, ASCII, development,
140 deploying it to \fI/usr/local/perl/ascii\fR:
141 .PP
142 .Vb 4
143 \& export PATH=$PWD:$PATH
144 \& export LIBPATH=$PWD:$PATH
145 \& ./Configure \-Dprefix=/usr/local/perl/ascii \-des \-Dusedevel \e
146 \& \-Duse64bitall \-Dusedl
147 .Ve
148 .PP
149 If you are building from a stable source, you don't need "\-Dusedevel".
150 (If you run Configure without options, it will interactively ask you about
151 every possible option based on its probing of what's available on your
152 particular machine, so you can choose as you go along.)
153 .PP
154 Run GNU make to build Perl
155 .PP
156 .Vb 1
157 \& make
158 .Ve
159 .PP
160 Run tests to ensure Perl is working correctly. Currently, there are about a
161 dozen failing tests out of nearly 2500
162 .PP
163 .Vb 1
164 \& make test_harness
165 .Ve
166 .PP
167 Install Perl into \fI/usr/local/perl/ascii\fR:
168 .PP
169 .Vb 1
170 \& make install
171 .Ve
172 .SS "Building a 64\-bit Dynamic EBCDIC Perl"
173 .IX Subsection "Building a 64-bit Dynamic EBCDIC Perl"
174 You will need a working perl on some box with connectivity to the destination
175 machine. On z/OS, it could be an ASCII perl, or a previous EBCDIC one.
176 Many machines will already have a pre-built perl already running, or one can
177 easily be downloaded from <https://www.perl.org/get.html>.
178 .PP
179 Follow the directions above in "Building a 64\-bit Dynamic ASCII Perl" as far as
180 getting a populated 'perl' directory. Then come back here to proceed.
181 .PP
182 The downloaded perl will need to be converted to 1047 EBCDIC. To do this:
183 .PP
184 .Vb 2
185 \& cd perl
186 \& Porting/makerel \-e
187 .Ve
188 .PP
189 If the Porting/makerel step fails with an error that it can not issue the tar
190 command, proceed to issue the command interactively, where V.R.M is the
191 version/release/modification of Perl you are uploading:
192 .PP
193 .Vb 2
194 \& cd ../
195 \& tar cf \- \-\-format=ustar perl\-V.R.M | gzip \-\-best > perl\-V.R.M.tar.gz
196 .Ve
197 .PP
198 Use sftp to upload the zipped tar file to z/OS:
199 .PP
200 .Vb 3
201 \& sftp <your system>
202 \& cd /tmp
203 \& put perl\-V.R.M.tar.gz
204 .Ve
205 .PP
206 Unzip and untar the zipped tar file on z/OS:
207 .PP
208 .Vb 2
209 \& cd /tmp
210 \& gunzip perl\-V.R.M.tar.gz
211 .Ve
212 .PP
213 Then one of:
214 .PP
215 .Vb 1
216 \& tar \-xvf perl\-V.R.M.tar
217 \&
218 \& pax \-r \-f perl\-V.R.M.tar
219 .Ve
220 .PP
221 You now have the source code for the EBCDIC Perl on z/OS and can proceed to
222 build it. This is analagous to how you would build the code for ASCII, but
223 note: you \fBshould not\fR tag the code but instead leave it untagged.
224 .PP
225 Configure the build environment as 64\-bit, Dynamic, native, development,
226 deploying it to \fI/usr/local/perl/ebcdic\fR:
227 .PP
228 .Vb 4
229 \& export PATH=$PWD:$PATH
230 \& export LIBPATH=$PWD:$PATH
231 \& ./Configure \-Dprefix=/usr/local/perl/ebcdic \-des \-Dusedevel \e
232 \& \-Duse64bitall \-Dusedl
233 .Ve
234 .PP
235 If you are building from a stable source, you don't need "\-Dusedevel".
236 (If you run Configure without options, it will interactively ask you about
237 every possible option based on its probing of what's available on your
238 particular machine, so you can choose as you go along.)
239 .PP
240 Run GNU make to build Perl
241 .PP
242 .Vb 1
243 \& make
244 .Ve
245 .PP
246 Run tests to ensure Perl is working correctly.
247 .PP
248 .Vb 1
249 \& make test_harness
250 .Ve
251 .PP
252 You might also want to have GNU groff for OS/390 installed before
253 running the "make install" step for Perl.
254 .PP
255 Install Perl into \fI/usr/local/perl/ebcdic\fR:
256 .PP
257 .Vb 1
258 \& make install
259 .Ve
260 .PP
261 EBCDIC Perl is still a work in progress. All the core code works as far as we
262 know, but various modules you might want to download from CPAN do not. The
263 failures range from very minor to catastrophic. Many of them are simply bugs
264 in the tests, with the module actually working properly. This happens because,
265 for example, the test is coded to expect a certain character ASCII code point;
266 when it gets the EBCDIC value back instead, it complains. But the code
267 actually worked. Other potential failures that aren't really failures stem
268 from checksums coming out differently, since \f(CW\*(C`A\*(C'\fR, for example, has a different
269 bit representation between the character sets. A test that is expecting the
270 ASCII value will show failure, even if the module is working perfectly. Also
271 in sorting, uppercase letters come before lowercase letters on ASCII systems;
272 the reverse on EBCDIC.
273 .PP
274 Some CPAN modules come bundled with the downloaded perl. And a few of those
275 have yet to be fixed to pass on EBCDIC platforms. As a result they are skipped
276 when you run 'make test'. The current list is:
277 .PP
278 .Vb 10
279 \& Archive::Tar
280 \& Config::Perl::V
281 \& CPAN::Meta
282 \& CPAN::Meta::YAML
283 \& Digest::MD5
284 \& Digest::SHA
285 \& Encode
286 \& ExtUtils::MakeMaker
287 \& ExtUtils::Manifest
288 \& HTTP::Tiny
289 \& IO::Compress
290 \& IPC::Cmd
291 \& JSON::PP
292 \& libnet
293 \& MIME::Base64
294 \& Module::Metadata
295 \& PerlIO::via\-QuotedPrint
296 \& Pod::Checker
297 \& podlators
298 \& Pod::Simple
299 \& Socket
300 \& Test::Harness
301 .Ve
302 .PP
303 See also \fIhints/os390.sh\fR for other potential gotchas.
304 .SS "Setup and utilities for Perl on OS/390"
305 .IX Subsection "Setup and utilities for Perl on OS/390"
306 This may also be a good time to ensure that your \fI/etc/protocol\fR file
307 and either your \fI/etc/resolv.conf\fR or \fI/etc/hosts\fR files are in place.
308 The IBM document that describes such USS system setup issues is
309 "z/OS UNIX System Services Planning"
310 .PP
311 For successful testing you may need to turn on the sticky bit for your
312 world readable /tmp directory if you have not already done so (see man chmod).
313 .SS "Useful files for trouble-shooting"
314 .IX Subsection "Useful files for trouble-shooting"
315 If your configuration is failing, read hints/os390.sh
316 This file provides z/OS specific options to direct the build process.
317 .PP
318 \fIShell\fR
319 .IX Subsection "Shell"
320 .PP
321 A message of the form:
322 .PP
323 .Vb 3
324 \& (I see you are using the Korn shell. Some ksh\*(Aqs blow up on Configure,
325 \& mainly on older exotic systems. If yours does, try the Bourne shell
326 \& instead.)
327 .Ve
328 .PP
329 is nothing to worry about at all.
330 .PP
331 \fIDynamic loading\fR
332 .IX Subsection "Dynamic loading"
333 .PP
334 Dynamic loading is required if you want to use XS modules from CPAN (like
335 DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from
336 CPAN with newer versions (like Encode) without rebuilding all of the perl
337 binary.
338 .PP
339 The instructions above will create a dynamic Perl. If you do not want to
340 use dynamic loading, remove the \-Dusedl option.
341 See the comments in hints/os390.sh for more information on dynamic loading.
342 .PP
343 \fIOptimizing\fR
344 .IX Subsection "Optimizing"
345 .PP
346 Optimization has not been turned on yet. There may be issues if Perl
347 is optimized.
348 .SS "Build Anomalies with Perl on OS/390"
349 .IX Subsection "Build Anomalies with Perl on OS/390"
350 "Out of memory!" messages during the build of Perl are most often fixed
351 by re building the GNU make utility for OS/390 from a source code kit.
352 .PP
353 Within USS your \fI/etc/profile\fR or \fR\f(CI$HOME\fR\fI/.profile\fR may limit your ulimit
354 settings. Check that the following command returns reasonable values:
355 .PP
356 .Vb 1
357 \& ulimit \-a
358 .Ve
359 .PP
360 To conserve memory you should have your compiler modules loaded into the
361 Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
362 .PP
363 If the compiler complains of syntax errors during the build of the
364 Socket extension then be sure to fix the syntax error in the system
365 header /usr/include/sys/socket.h.
366 .SS "Testing Anomalies with Perl on OS/390"
367 .IX Subsection "Testing Anomalies with Perl on OS/390"
368 The "make test" step runs a Perl Verification Procedure, usually before
369 installation. You might encounter STDERR messages even during a successful
370 run of "make test". Here is a guide to some of the more commonly seen
371 anomalies:
372 .PP
373 \fIOut of Memory (31\-bit only)\fR
374 .IX Subsection "Out of Memory (31-bit only)"
375 .PP
376 Out of memory problems should not be an issue, unless you are attempting to build
377 a 31\-bit Perl.
378 .PP
379 If you _are_ building a 31\-bit Perl, the constrained environment may mean you
380 need to change memory options for Perl.
381 In addition to the comments
382 above on memory limitations it is also worth checking for _CEE_RUNOPTS
383 in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31\-bit only
384 to set CEE run options, but the environment variable wins.
385 .PP
386 The 31\-bit C code asks for:
387 .PP
388 .Vb 1
389 \& #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
390 .Ve
391 .PP
392 The important parts of that are the second argument (the increment) to HEAP,
393 and allowing the stack to be "Above the (16M) line". If the heap
394 increment is too small then when perl (for example loading unicode/Name.pl) tries
395 to create a "big" (400K+) string it cannot fit in a single segment
396 and you get "Out of Memory!" \- even if there is still plenty of memory
397 available.
398 .PP
399 A related issue is use with perl's malloc. Perl's malloc uses \f(CWsbrk()\fR
400 to get memory, and \f(CWsbrk()\fR is limited to the first allocation so in this
401 case something like:
402 .PP
403 .Vb 1
404 \& HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
405 .Ve
406 .PP
407 is needed to get through the test suite.
408 .SS "Usage Hints for Perl on z/OS"
409 .IX Subsection "Usage Hints for Perl on z/OS"
410 When using Perl on z/OS please keep in mind that the EBCDIC and ASCII
411 character sets are different. See perlebcdic for more on such character
412 set issues. Perl builtin functions that may behave differently under
413 EBCDIC are also mentioned in the perlport.pod document.
414 .PP
415 If you are having trouble with square brackets then consider switching your
416 rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for
417 working with Perl on USS.
418 .SS "Modules and Extensions for Perl on z/OS (Static Only)"
419 .IX Subsection "Modules and Extensions for Perl on z/OS (Static Only)"
420 Pure Perl (that is non XS) modules may be installed via the usual:
421 .PP
422 .Vb 4
423 \& perl Makefile.PL
424 \& make
425 \& make test
426 \& make install
427 .Ve
428 .PP
429 If you built perl with dynamic loading capability then that would also
430 be the way to build XS based extensions. However, if you built perl with
431 static linking you can still build XS based extensions for z/OS
432 but you will need to follow the instructions in ExtUtils::MakeMaker for
433 building statically linked perl binaries. In the simplest configurations
434 building a static perl + XS extension boils down to:
435 .PP
436 .Vb 6
437 \& perl Makefile.PL
438 \& make
439 \& make perl
440 \& make test
441 \& make install
442 \& make \-f Makefile.aperl inst_perl MAP_TARGET=perl
443 .Ve
444 .SS "Running Perl on z/OS"
445 .IX Subsection "Running Perl on z/OS"
446 To run the 64\-bit Dynamic Perl environment, update your PATH and LIBPATH
447 to include the location you installed Perl into, and then run the perl you
448 installed as perlV.R.M where V/R/M is the Version/Release/Modification level
449 of the current development level.
450 If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to
451 set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl
452 source code you run is tagged appropriately as ASCII or EBCDIC using
453 "chtag \-t \-c<CCSID>":
454 .IP "For ASCII Only:" 4
455 .IX Item "For ASCII Only:"
456 .Vb 5
457 \& export _BPXK_AUTOCVT=ON
458 \& export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)"
459 \& export _TAG_REDIR_ERR="txt"
460 \& export _TAG_REDIR_IN="txt"
461 \& export _TAG_REDIR_OUT="txt"
462 .Ve
463 .IP "For ASCII or EBCDIC:" 4
464 .IX Item "For ASCII or EBCDIC:"
465 .Vb 3
466 \& export PATH=/usr/local/perl/ascii:$PATH
467 \& export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH
468 \& perlV.R.M args
469 .Ve
470 .PP
471 If tcsh is your login shell then use the setenv command.
472 .SH AUTHORS
473 .IX Header "AUTHORS"
474 David Fiander and Peter Prymmer with thanks to Dennis Longnecker
475 and William Raffloer for valuable reports, LPAR and PTF feedback.
476 Thanks to Mike MacIsaac and Egon Terwedow for SG24\-5944\-00.
477 Thanks to Ignasi Roca for pointing out the floating point problems.
478 Thanks to John Goodyear for dynamic loading help.
479 .PP
480 Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64\-bit and
481 ASCII/EBCDIC Bi-Modal support
482 .SH "OTHER SITES"
483 .IX Header "OTHER SITES"
484 <https://github.com/ZOSOpenTools/perlport/> provides documentation and tools
485 for building various z/OS Perl configurations and has some useful tools in the
486 \&'bin' directory you may want to use for building z/OS Perl yourself.
487 .SH HISTORY
488 .IX Header "HISTORY"
489 Updated 24 December 2021 to enable initial ASCII support
490 .PP
491 Updated 03 October 2019 for perl\-5.33.3+
492 .PP
493 Updated 28 November 2001 for broken URLs.
494 .PP
495 Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
496 .PP
497 Updated 24 January 2001 to mention dynamic loading.
498 .PP
499 Updated 15 January 2001 for the 5.7.1 release of Perl.
500 .PP
501 Updated 12 November 2000 for the 5.7.1 release of Perl.
502 .PP
503 This document was podified for the 5.005_03 release of Perl 11 March 1999.
504 .PP
505 This document was originally written by David Fiander for the 5.005
506 release of Perl.