Debian Codegraph @

upstream/fedora-44/man1/perlos390.1

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