| 1 | If you read this file _as_is_, just ignore the funny characters you see. |
| 2 | It is written in the POD format (see pod/perlpod.pod) which is specially |
| 3 | designed to be readable as is. |
| 4 | |
| 5 | =head1 NAME |
| 6 | |
| 7 | README.os400 - Perl version 5 on OS/400 |
| 8 | |
| 9 | =head1 DESCRIPTION |
| 10 | |
| 11 | This document describes various features of IBM's OS/400 operating |
| 12 | system that will affect how Perl version 5 (hereafter just Perl) is |
| 13 | compiled and/or runs. |
| 14 | |
| 15 | By far the easiest way to build Perl for OS/400 is to use the PASE |
| 16 | (Portable Application Solutions Environment), for more information see |
| 17 | http://www.iseries.ibm.com/developer/factory/pase/index.html |
| 18 | This environment allows one to use AIX APIs while programming, and it |
| 19 | provides a runtime that allows AIX binaries to execute directly on the |
| 20 | PowerPC iSeries. |
| 21 | |
| 22 | =head2 Compiling Perl for OS/400 PASE |
| 23 | |
| 24 | The recommended way to build Perl for the OS/400 PASE is to build the |
| 25 | Perl 5 source code (release 5.8.1 or later) under AIX. |
| 26 | |
| 27 | The trick is to give a special parameter to the Configure shell script |
| 28 | when running it on AIX: |
| 29 | |
| 30 | sh Configure -DPASE ... |
| 31 | |
| 32 | The default installation directory of Perl under PASE is /QOpenSys/perl. |
| 33 | This can be modified if needed with Configure parameter -Dprefix=/some/dir. |
| 34 | |
| 35 | Starting from OS/400 V5R2 the IBM Visual Age compiler is supported |
| 36 | on OS/400 PASE, so it is possible to build Perl natively on OS/400. |
| 37 | The easier way, however, is to compile in AIX, as just described. |
| 38 | |
| 39 | If you don't want to install the compiled Perl in AIX into /QOpenSys |
| 40 | (for packaging it before copying it to PASE), you can use a Configure |
| 41 | parameter: -Dinstallprefix=/tmp/QOpenSys/perl. This will cause the |
| 42 | "make install" to install everything into that directory, while the |
| 43 | installed files still think they are (will be) in /QOpenSys/perl. |
| 44 | |
| 45 | If building natively on PASE, please do the build under the /QOpenSys |
| 46 | directory, since Perl is happier when built on a case sensitive filesystem. |
| 47 | |
| 48 | =head2 Installing Perl in OS/400 PASE |
| 49 | |
| 50 | If you are compiling on AIX, simply do a "make install" on the AIX box. |
| 51 | Once the install finishes, tar up the /QOpenSys/perl directory. Transfer |
| 52 | the tarball to the OS/400 using FTP with the following commands: |
| 53 | |
| 54 | > binary |
| 55 | > site namefmt 1 |
| 56 | > put perl.tar /QOpenSys |
| 57 | |
| 58 | Once you have it on, simply bring up a PASE shell and extract the tarball. |
| 59 | |
| 60 | If you are compiling in PASE, then "make install" is the only thing you |
| 61 | will need to do. |
| 62 | |
| 63 | The default path for perl binary is /QOpenSys/perl/bin/perl. You'll |
| 64 | want to symlink /QOpenSys/usr/bin/perl to this file so you don't have |
| 65 | to modify your path. |
| 66 | |
| 67 | =head2 Using Perl in OS/400 PASE |
| 68 | |
| 69 | Perl in PASE may be used in the same manner as you would use Perl on AIX. |
| 70 | |
| 71 | Scripts starting with #!/usr/bin/perl should work if you have |
| 72 | /QOpenSys/usr/bin/perl symlinked to your perl binary. This will not |
| 73 | work if you've done a setuid/setgid or have environment variable |
| 74 | PASE_EXEC_QOPENSYS="N". If you have V5R1, you'll need to get the |
| 75 | latest PTFs to have this feature. Scripts starting with |
| 76 | #!/QOpenSys/perl/bin/perl should always work. |
| 77 | |
| 78 | =head2 Known Problems |
| 79 | |
| 80 | When compiling in PASE, there is no "oslevel" command. Therefore, |
| 81 | you may want to create a script called "oslevel" that echoes the |
| 82 | level of AIX that your version of PASE runtime supports. If you're |
| 83 | unsure, consult your documentation or use "4.3.3.0". |
| 84 | |
| 85 | If you have test cases that fail, check for the existence of spool files. |
| 86 | The test case may be trying to use a syscall that is not implemented |
| 87 | in PASE. To avoid the SIGILL, try setting the PASE_SYSCALL_NOSIGILL |
| 88 | environment variable or have a handler for the SIGILL. If you can |
| 89 | compile programs for PASE, run the config script and edit config.sh |
| 90 | when it gives you the option. If you want to remove fchdir(), which |
| 91 | isn't implement in V5R1, simply change the line that says: |
| 92 | |
| 93 | d_fchdir='define' |
| 94 | |
| 95 | to |
| 96 | |
| 97 | d_fchdir='undef' |
| 98 | |
| 99 | and then compile Perl. The places where fchdir() is used have |
| 100 | alternatives for systems that do not have fchdir() available. |
| 101 | |
| 102 | =head2 Perl on ILE |
| 103 | |
| 104 | There exists a port of Perl to the ILE environment. This port, however, |
| 105 | is based quite an old release of Perl, Perl 5.00502 (August 1998). |
| 106 | (As of July 2002 the latest release of Perl is 5.8.0, and even 5.6.1 |
| 107 | has been out since April 2001.) If you need to run Perl on ILE, though, |
| 108 | you may need this older port: http://www.cpan.org/ports/#os400 |
| 109 | Note that any Perl release later than 5.00502 has not been ported to ILE. |
| 110 | |
| 111 | If you need to use Perl in the ILE environment, you may want to consider |
| 112 | using Qp2RunPase() to call the PASE version of Perl. |
| 113 | |
| 114 | =head1 AUTHORS |
| 115 | |
| 116 | Jarkko Hietaniemi <jhi@iki.fi> |
| 117 | Bryan Logan <bryanlog@us.ibm.com> |
| 118 | David Larson <larson1@us.ibm.com> |
| 119 | |
| 120 | =cut |