You are viewing the version of this documentation from Perl 5.35.9. This is a development release of Perl.

CONTENTS

NAME

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

SYNOPSIS

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

DESCRIPTION

This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and should work fine with z/OS 2.5. It may work on other versions or releases, but those are the ones it has been tested on. There are many ways you can build Perl for z/OS. This document will describe how to build a 64-bit Dynamic EBCDIC Perl as well as a 64-bit Dynamic ASCII Perl.

You may need to carry out some system configuration tasks before running the Configure script for Perl.

Tools

You will want to get GNU make 4.1 or later. GNU make can be downloaded from a port that Rocket Software provides. You will need the z/OS c99 compiler from IBM. You can also obtain a z/OS native git client port that Rocket Software provides. This is optional - you can use git on another platform and transfer the code via ftp to z/OS For EBCDIC only, you will need gunzip client port that Rocket Software provides to unzip the zipped tarball you upload to z/OS

Building a 64-bit Dynamic ASCII Perl

Using the native git on z/OS, clone Perl:

git clone https://github.com/Perl/perl5.git perl

Change into the perl directory and tag all the code as ASCII:

cd perl
chtag -R -h -t -cISO8859-1 *

Configure the build environment as 64-bit, Dynamic, ASCII, development, deploying it to /usr/local/perl/ascii:

export PATH=$PWD:$PATH
export LIBPATH=$PWD:$PATH
./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \
      -Duse64bitall -Dusedl

Run GNU make to build Perl

make

Run tests to ensure Perl is working correctly. Currently, there are 33 failing tests out of 2479

make tests

Install Perl into /usr/local/perl/ascii:

make install

Building a 64-bit Dynamic EBCDIC Perl

Using the native git on a platform other than z/OS, (e.g. Mac, Windows, Linux) clone Perl:

git clone https://github.com/Perl/perl5.git perl

Change into the perl directory and modify the source so it is suitable for building on z/OS

cd perl
Porting/makerel -e

If the Porting/makerel step fails with an error that it can not issue the tar command, proceed to issue the command interactively, where V.R.M is the version/release/modification of Perl you are uploading:

cd ../
tar cf -  --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz

Use sftp to upload the zipped tar file to z/OS:

sftp <your system>
cd /tmp
put perl-V.R.M.tar.gz

Unzip and untar the zipped tar file on z/OS:

cd /tmp
gunzip perl-V.R.M.tar.gz
tar -xvf perl-V.R.M.tar

You now have the source code for the EBCDIC Perl on z/OS and can proceed to build it. This is analagous to how you would build the code for ASCII, but note: you should not tag the code but instead leave it untagged.

Configure the build environment as 64-bit, Dynamic, ASCII, development, deploying it to /usr/local/perl/ebcdic:

export PATH=$PWD:$PATH
export LIBPATH=$PWD:$PATH
./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \
      -Duse64bitall -Dusedl

Run GNU make to build Perl

make

Run tests to ensure Perl is working correctly. Currently, there are 99 tests failing out of 1949

make tests

Install Perl into /usr/local/perl/ebcdic:

make install

Setup and utilities for Perl on OS/390

This may also be a good time to ensure that your /etc/protocol file and either your /etc/resolv.conf or /etc/hosts files are in place. The IBM document that describes such USS system setup issues is "z/OS UNIX System Services Planning"

For successful testing you may need to turn on the sticky bit for your world readable /tmp directory if you have not already done so (see man chmod).

Useful files for trouble-shooting

If your configuration is failing, read hints/os390.sh This file provides z/OS specific options to direct the build process.

Shell

A message of the form:

(I see you are using the Korn shell.  Some ksh's blow up on Configure,
mainly on older exotic systems.  If yours does, try the Bourne shell
instead.)

is nothing to worry about at all.

Dynamic loading

Dynamic loading is required if you want to use XS modules from CPAN (like DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from CPAN with newer versions (like Encode) without rebuilding all of the perl binary.

The instructions above will create a dynamic Perl. If you do not want to use dynamic loading, remove the -Dusedl option. See the comments in hints/os390.sh for more information on dynamic loading.

Optimizing

Optimization has not been turned on yet. There may be issues if Perl is optimized.

Build Anomalies with Perl on OS/390

"Out of memory!" messages during the build of Perl are most often fixed by re building the GNU make utility for OS/390 from a source code kit.

Within USS your /etc/profile or $HOME/.profile may limit your ulimit settings. Check that the following command returns reasonable values:

ulimit -a

Testing Anomalies with Perl on OS/390

The "make test" step runs a Perl Verification Procedure, usually before installation. You might encounter STDERR messages even during a successful run of "make test". Here is a guide to some of the more commonly seen anomalies:

Out of Memory (31-bit only)

Out of memory problems should not be an issue, unless you are attempting to build a 31-bit Perl.

If you _are_ building a 31-bit Perl, the constrained environment may mean you need to change memory options for Perl. In addition to the comments above on memory limitations it is also worth checking for _CEE_RUNOPTS in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31-bit only to set CEE run options, but the environment variable wins.

The 31-bit C code asks for:

#pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))

The important parts of that are the second argument (the increment) to HEAP, and allowing the stack to be "Above the (16M) line". If the heap increment is too small then when perl (for example loading unicode/Name.pl) tries to create a "big" (400K+) string it cannot fit in a single segment and you get "Out of Memory!" - even if there is still plenty of memory available.

A related issue is use with perl's malloc. Perl's malloc uses sbrk() to get memory, and sbrk() is limited to the first allocation so in this case something like:

HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)

is needed to get through the test suite.

Usage Hints for Perl on z/OS

When using Perl on z/OS please keep in mind that the EBCDIC and ASCII character sets are different. See perlebcdic.pod for more on such character set issues. Perl builtin functions that may behave differently under EBCDIC are also mentioned in the perlport.pod document.

If you are having trouble with square brackets then consider switching your rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for working with Perl on USS.

Modules and Extensions for Perl on z/OS (Static Only)

Pure Perl (that is non XS) modules may be installed via the usual:

perl Makefile.PL
make
make test
make install

If you built perl with dynamic loading capability then that would also be the way to build XS based extensions. However, if you built perl with static linking you can still build XS based extensions for z/OS but you will need to follow the instructions in ExtUtils::MakeMaker for building statically linked perl binaries. In the simplest configurations building a static perl + XS extension boils down to:

perl Makefile.PL
make
make perl
make test
make install
make -f Makefile.aperl inst_perl MAP_TARGET=perl

Running Perl on z/OS

To run the 64-bit Dynamic Perl environment, update your PATH and LIBPATH to include the location you installed Perl into, and then run the perl you installed as perlV.R.M where V/R/M is the Version/Release/Modification level of the current development level. If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl source code you run is tagged appropriately as ASCII or EBCDIC using chtag -t -c<CCSID>:

For ASCII Only:

export _BPXK_AUTOCVT=ON
export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)"
export _TAG_REDIR_ERR="txt"
export _TAG_REDIR_IN="txt"
export _TAG_REDIR_OUT="txt"

For ASCII or EBCDIC:

export PATH=/usr/local/perl/ascii:$PATH
export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH
perlV.R.M args

AUTHORS

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

Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64-bit and ASCII/EBCDIC Bi-Modal support

Other sites

https://github.com/ZOSOpenTools/perlport/ provides documentation and tools for building various z/OS Perl configurations and has some useful tools in the 'bin' directory you may want to use for building z/OS Perl yourself.

HISTORY

Updated 24 December 2021 to enable initial ASCII support

Updated 03 October 2019 for perl-5.33.3+

Updated 28 November 2001 for broken URLs.

Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.

Updated 24 January 2001 to mention dynamic loading.

Updated 15 January 2001 for the 5.7.1 release of Perl.

Updated 12 November 2000 for the 5.7.1 release of Perl.

This document was podified for the 5.005_03 release of Perl 11 March 1999.

This document was originally written by David Fiander for the 5.005 release of Perl.