Installation and Build Notes for AS/400 Perl -------------------------------------------- The Perl distribution for the AS/400 is packaged as a SAVF format file containing a precompiled perl executable with the perl libraries. The perl sources and libraries are a separate distribution. The binary and libraries are stored in the file PERLPGM.SAVF; the sources and libraries are stored in the file P500502.SAVF. Unfortunately, the make that IBM ships as part of it's Qshell environment does not properly implement default rules for building things, so it cannot be used to build perl from the sources. If you want to look at the perl sources, or attempt to build from the sources, then skip ahead to "Downloading and building the sources", otherwise, keep reading here for direction on how to download and install the binaries. The libraries are stored as separate SAVF-format files within the file you download. Once you've restored the save file you downloaded, you will have to restore the libraries. Before ftping the save files onto your AS/400 system, you must create the PERLDIST library, and the destination save file so that ftp will store the data properly: CRTLIB LIB(PERLDIST) TEXT('Perl 5 Distribution Library') CRTSAVF FILE(PERLDIST/PERLPGM) TEXT('AS/400 Perl Binaries') To restore the program files, run the following commands: RSTOBJ OBJ(*ALL) SAVLIB(PERLDIST) DEV(*SAVF) SAVF(PERLDIST/PERLPGM) Now, to run perl from within the Qshell environment easily, you have to create a symbolic link using the qsh command ln -s /qsys.lib/perldist.lib/perl.pgm /usr/bin/perl Finally, you have to install the perl script library into the IFS from the save file that was restored from the distribution file: CRTDIR '/usr/local' CRTDIR '/usr/local/lib' RST DEV('/QSYS.LIB/PERLDIST.LIB/PERLLIB.FILE') + OBJ('/usr/local/lib/*' *INCLUDE *SAME) Once that's all done, you may delete the save files PERLPGM, PERLSRC, and PERLLIB, if you wish. Make sure to read the "Release Notes" below for any differences or limitations of AS/400 perl. You're now ready to program in perl. If you are new to perl, you can find out more about it from these books: Gundavaram, Shishir. _CGI Programming on the World Wide Web_. Sebastopol, CA: O'Reilly, 1996. ISBN 1-56592-168-2. Wall, Larry, Tom Christiansen, and Randal L. Schwartz. _Programming Perl_. 2d Ed. (Covers Perl 5). Sebastopol, CA: O'Reilly, 1996. ISBN 1-56592-149-6. and these web sites: http://www.perl.org/ http://www.perl.com/perl/ Release Notes for AS/400 Perl ----------------------------- The core perl language is fully supported on the AS/400, except for the following issues: - The OS/400 Unix-like APIs do not fully support file descriptors. Perl is only supported when run from within a Qshell environment, from the web server as a CGI processor, or some other environment in which the POSIX file descriptors 0, 1, and 2 have been properly initialized and the environment variable QIBM_USE_DESCRIPTOR_STDIO has been set to either 'Y' or 'I'. - While standard input and standard output may now be redirected from within perl using the idiom open(STDOUT, ">outfile") the OS/400 runtime does not properly support closing STDOUT and then opening it on the new file. That is, the standard perl idiom close(STDOUT); out(STDOUT, ">outfile"); does not work. - The file names "stdout", "stdin", and "stderr" are treated specially by the OS/400 C runtime. Do NOT use these file names within your perl programs. - Perl scripts are not directly executable. To invoke a perl program as a CGI, you must write a small CL program that will dispatch to the perl script itself. For example, the script BEGIN CALL PGM(PERLDIST/PERL) PARM('/QOpenSys/hello.pl') ENDPGM will invoke the perl script 'hello.pl' in the root of the QOpenSys file system. There are also some issues related to the AS/400 environment that developers porting scripts from other environments must be aware of: - The arguments to the perl system() function and any command substitutions (ie. backquoted strings) must now be written as Qshell command strings, using the limited set of Qshell utilities that are provided. - Perl reads scripts and data out of the integrated filesystem (IFS). To access native OS/400 files, you must use the IFS-style of name. For example, the file PERLDIST/QCSRC.AS400 would be written as '/QSYS.LIB/PERLDIST.LIB/QCSRC.FILE/AS400.MBR'. See the AS/400 documentation about the IFS for details about file naming. - The AS/400 is an EBCDIC system. All scripts being transfered from ASCII environments will have to be translated. FTP does this automatically for text transfers, as does the AS/400 client access Windows file server when copying into the HFS. - Pipes are now supported by OS/400, and perl takes advantage of them. OS/400 does not, however, support the POSIX fork() API, so the "|-" method of forking a new copy of your perl script connected to the parent by a pipe is still not supported. - AS/400 Perl supports the DBI and DB2 modules, allowing access to databases via SQL and the perl DBI interfaces. Because AS/400 DB2 does not have full support for converting between numeric and character datatypes, perl programs must be more careful about the data types they pass as parameters in SQL statements. Integers must be declared as such, and NUMERIC and fixed-point DECIMAL numbers must be declared as floats. See the code in /usr/local/lib/perl5/dbsamples for examples of using the DB2 interfaces to access the database described in section 2.3 of "DB2 for AS/400 SQL Programming", IBM document number SC41-5611-02. Downloading and Building the Sources ------------------------------------ Before ftping the save files onto your AS/400 system, you must create the PERLDIST library, and the destination save file so that ftp will store the data properly: CRTLIB LIB(PERLDIST) TEXT('Perl 5 Distribution Library') CRTSAVF FILE(PERLDIST/P500502) TEXT('AS/400 Perl Sources') To restore the sources, run the commands: CRTDIR '/usr/local' CRTDIR '/usr/local/src RSTOBJ (OBJ(*ALL) SAVLIB(PERLDIST) DEV(*SAVF) SAVF(PERLDIST/P500502) RST DEV('/QSYS.LIB/PERLDIST.LIB/PERLSRC.FILE') + OBJ('/usr/local/src' *INCLUDE *SAME) The libraries are stored as separate SAVF-format files within the file you download. Once you've restored the save file you downloaded, you will have to restore the libraries: CRTDIR '/usr/local/lib' RST DEV('/QSYS.LIB/PERLDIST.LIB/PERLLIB.FILE') + OBJ('/usr/local/lib/*' *INCLUDE *SAME) To build the sources, you need to start the Qshell environment and run the following commands: cd /usr/local/src/perldist sh build.as400 The file "build.as400" is a script that invokes make several times to build perl and the various extensions that are supported. Unfortunately, the version of make that we used to build perl is an IBM-internal package, so some work will be necessary before this process will work on your system. If you want to try to build from sources, contact rchgo400@us.ibm.com to find out about acquiring the internal gmake port that we used to build on the AS/400 -- David J. Fiander