Use perlos400 to plan a legacy Perl PASE build

You will turn the installed perlos400(1) page into a short, reviewable plan for building Perl for the OS/400 PASE environment. The page is historical rather than a current OS/400 administration manual, so the useful result is a set of verified assumptions and a list of points that need checking on the target machine. Allow 15 minutes to inspect the documentation and prepare the plan. A real build and transfer will take longer and needs an OS/400 or PASE system, an AIX build host or a supported native toolchain, and an approved way to move files.

1. Check which documentation you actually have

Start on Linux by confirming the package and Perl release. This guide was checked with Ubuntu's perl-doc package version 5.38.2-3.2ubuntu0.6; the page identifies itself as generated from Perl 5.38.2. Your distribution may ship a different revision.

$ dpkg-query -W -f='\${Package} \${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6
$ perl -v
This is perl 5, version 38, subversion 2 ...

If the first command reports that the package is not installed, install the documentation package through your normal package-management process. That is a system change and may require elevated privileges; reading an already installed manpage does not.

Now open the page in the terminal:

$ man perlos400
$ perldoc perlos400

Checkpoint: you should see the warning that the document needs updating, followed by sections about PASE compilation, installation, use, known problems and Perl on ILE. This is a documentation page, not an executable called perlos400, so command -v perlos400 is not a meaningful installation test.

2. Separate the PASE path from the ILE path

The page describes two different environments. PASE is the route it recommends: Perl is built in an AIX-like environment and then runs through the Portable Application Solutions Environment. ILE is a separate porting target, and the page says its known port is based on Perl 5.00502 from August 1998. Do not combine the paths in one build plan.

For a PASE plan, record these documented facts before touching a source tree:

• The suggested AIX configure argument is -DPASE.
• The default installation directory is /QOpenSys/perl.
• -Dprefix=/some/dir changes the installation directory.
• -Dinstallprefix=/tmp/QOpenSys/perl stages files elsewhere while retaining /QOpenSys/perl as the intended installed path.

These are configuration choices, not universal defaults for every current Perl release. Confirm that the source release and the target OS/400 level still support them before compiling. The upstream Perl repository still carries the same OS/400 README, including the warning that it needs updating, which is evidence that this page should not be treated as a modern compatibility guarantee.

3. Prepare a reproducible PASE build note

Write down the Perl source version, the AIX host, the OS/400 release, the PASE level, the intended prefix and the person responsible for validating the result. Then the documented configure shape is:

$ sh Configure -DPASE ...

The three dots are not literal arguments. Replace them with the options you have reviewed for the chosen source release. If you need a staged package rather than an AIX installation in the final location, the page gives this form:

$ sh Configure -DPASE -Dinstallprefix=/tmp/QOpenSys/perl ...

Do not copy these commands into an unattended build without filling in the release-specific options and checking the generated configuration. A successful configure step only means that configuration completed; it does not prove that PASE can execute the resulting binary.

When compiling natively in PASE, the page specifically recommends building under /QOpenSys, because Perl expects a case-sensitive filesystem. That advice does not turn a normal Linux directory into a PASE build environment.

4. Install or stage the result

If the build happened on AIX, the documented workflow is to run make install, archive /QOpenSys/perl, transfer the archive to OS/400, and extract it from a PASE shell. The example transfer session is:

> binary
> site namefmt 1
> put perl.tar /QOpenSys

This changes the target system. Confirm the destination, archive contents and rollback plan with the operator before uploading anything. Do not use a privileged account merely because the example contains /QOpenSys; use the least privilege that can write the approved destination. Keep the original archive and existing Perl installation until the new binary has passed checks.

If compiling directly in PASE, the page says that make install is the remaining installation step. It documents /QOpenSys/perl/bin/perl as the default Perl binary path and suggests a symlink at /QOpenSys/usr/bin/perl so scripts can use the shorter path. A symlink changes command resolution for other users, so create it only after checking that the path is unused and that local change control permits it.

Recovery is straightforward if you staged the build: stop before replacing the live tree, remove or quarantine the staged directory, and restore the previous archive or symlink target. If you replaced an existing installation without a backup, the manpage supplies no undo command; that is why the archive and a tested rollback matter.

5. Verify the interpreter and script path

In the PASE shell, test the exact binary you installed before changing a system-wide symlink:

$ /QOpenSys/perl/bin/perl -e 'print $^V, "\n"'
v5.38.2

The output will match the Perl source you built, not necessarily the version shown in this Linux example. Then test a small script through the path your deployment intends to use. The page says that scripts beginning with #!/usr/bin/perl depend on a symlink at /QOpenSys/usr/bin/perl. It also gives #!/QOpenSys/perl/bin/perl as the fixed path.

That claim has boundaries. The page says the /usr/bin/perl form will not work for setuid or setgid scripts, or when PASE_EXEC_QOPENSYS is N. Treat those as security-sensitive cases: do not weaken execution settings just to make a shebang pass. Use the explicit path where the target policy allows it, and test the real execution mode rather than only invoking Perl interactively.

6. Investigate failures without guessing

The page records two old platform-specific traps. First, PASE may not provide oslevel; the document suggests a script that reports the AIX level supported by the runtime, with 4.3.3.0 as a fallback when unsure. That is a compatibility probe described by the page, not a safe way to identify a modern OS/400 release. Ask the platform owner for the real level.

Second, failed test cases may involve spool files or system calls that PASE does not implement. The page mentions PASE_SYSCALL_NOSIGILL and editing config.sh to undefine d_fchdir on V5R1. Do not apply either workaround as a blind fix. Capture the failing test, PASE level and generated configuration first; changing signal handling or feature detection can hide a real portability defect. The page itself says the fchdir() adjustment belongs in the configuration produced during a PASE build.