			Perl 5.002á3 for OS/2.

        Copyright (c) 1989,1990,1991,1992,1993,1994  Larry Wall
                       All rights reserved.

		OS/2 port Copyright (c) 1990, 1991, 1994-96
	       Raymond Chen, Kai Uwe Rommel, Andreas Kaiser
                            
Version 5 port (this package) by Andreas Kaiser <ak@ananke.s.bawue.de>
(2:246/8506.9@fidonet).

To run the executables supplied with this file, you have to install the
EMX runtime package emxrt.zip of version 0.9b1 or later.

The file emxrt.zip is available at ftp.rus.uni-stuttgart.de (the
origin), ftp-os2.nmsu.edu and many other places.

The source code of the original Perl 5.0 distribution is not included
here. You can get it at ftp://ftp.leo.org/.../perl5.002beta3.tar.gz
(and many other places).

For documentation of Perl 5, look at the files into the directory tree
"pod". For TeX or Postscript docs, get perlref-5.000.0.tar.gz (is a
later one available?). A LaTeX and postscript reference card is
available at
  ftp.NL.net:/pub/comp/programming/languages/perl/perlref-5.000.0.tar.gz
  prep.ai.mit.edu:/pub/gnu/perlref-5.000.0.tar.gz

Many REXX DLLs complement the features available by standard Perl,
supporting system calls (YdbaUtil - RXU??.ZIP), xBase (RexxBase,
shareware), serial I/O (RxAsync) and basic PM dialogs (VRexx). These
packages can be found at many OS/2 FTP servers.

-----------------------------------------------------------------------------
Installation:
-------------

If you did not have HPFS up to now, this is the right time to reformat
your filesystem(s)... While Perl itself does not require HPFS, a lot
of Perl library files do. Or try EMXOPT=-t.

copy perl5.exe perl5x.exe `some PATH dir`
copy os2\perlglob.exe `some PATH dir`
copy perl5.dll `some LIBPATH dir`

set PERL5LIB=x:/your/own/perl/lib;y:/somewhere/perl5/lib

set PERL5LOAD=10 to leave the interpreter(s) preloaded in memory for
10 minutes. It may reduce the time required to load perl on subsequent
invocations (but may significantly increase the load time at first
invocation if the emxload daemon is not yet running).

The perl5 extension DLLs (POSIX_.DLL, REXX_.DLL, ...) do not need a
LIBPATH entry.

Executables:
------------

perl5.exe,perl5.dll :	DynaLoader, REXX support, external DLLs

			No fork. Running a command via open() returns 1
			instead of the child process id.

			Other modules supported via extension DLLs, no
			builtins other than DynaLoader.

perl5x.exe :		No Dynaloader, no REXX.

			Supports fork. Running a command via open() uses fork
			(slow) and correctly returns the child process id.

			Fcntl, FileHandle, POSIX and Socket modules builtin.
			No other extension modules supported.

			Note that the .pm files of the builtin modules reflect
			DLL use. If you need them with perl5x.exe, you have to
			remove the "bootstrap" line.

-----------------------------------------------------------------------------
Building:
---------

Well, the binaries in this package are not easily rebuilt. The building
method I am using is largely my own, not based on the original perl
methods and may need unmentioned tools.

On the other hand, the original perl 5.002 distribution is ready to be
built using the standard build process, once you have all the
prerequisites. This version however lacks some features, such as
support for REXX variables.

The prerequisites of my build (I'm sure I forgot a few):
- Perl5.002beta3.tar.gz (Perl 5.002á3 sources).
- This stuff.
- EMX 0.9b01 or later (Compiler).
- OS/2 Development Toolkit (or change REXX inc/lib references).
- Korn shell (ksh) or some other Unix-like shell named ksh.
- DMake, with group recipes configured for a Unix shell.
- Larry Walls "patch" program.
- Several more or less Unix-like tools, such as cp, cat, touch, find, ...

get Perl 5.002 beta3 source
apply the OS/2 patches shipped with the standard perl distribution
apply os2\patches       -- my own patches
copy os2\config.sh .    -- my configuration stuff
copy os2\makefile.mk .

If you do not have UPM (User Profile Management), remove "UPM" from
makefile.mk. If you do not have DB2 2, remove "DB2CLI" from
makefile.mk.

-----------------------------------------------------------------------------
Not supported, bugs, "OS/2 is Not Unix":
----------------------------------------

Depending on whether you run perl5.exe or perl5x.exe, you can either
use extension modules and REXX, or fork, since the EMX implementation
of fork conflicts with DLL support. Remember that there is a hidden
fork in open(F, "-|") and open(F, "|-").

config.sh (Config.pm) lies. It shows d_fork='undef' even though it is
available in perl5x.exe. "dynamic_ext" and "extensions" are incorrect
for perl5x.exe. A few others may be incorrect as well, especially
those describing the development environment used when compiling Perl.

flock is available but does not yet work in EMX 0.9a.

ctermid does not work (returns NULL).

... and of course a lot of Unix-isms like process group, user and group
management, links, ...

For details, look into config.sh and the EMX library reference.

Several scripts of the test suite (see source distribution) fail due to
Unix-isms like /bin/sh, `echo *`, different quoting requirements, ...

When opening a command pipe [such as open(F,"cat|")], perl5.exe
returns 1 instead of the child's process id. Perl5x.exe correctly
returns the process id.

OS/2 does not have a true exec API (which is used both by the exec
function and when opening a command pipe with perl5x.exe). What
actually happens is the call of a subprocess with the father waiting
for the termination of its child. While waiting, the father still owns
all its resources (it passes signals to the child however) and there
may be some other side effects as well.

While localization is enabled, the EMX 0.9b1 runtime does not yet
support character set locales, so the precise locale names of the form
Xx_XX are not yet supported. Instead the Perl startup code defaults to
the C locale without complaining. Note that locale-sensitive character
set mappings may silently change when using a future version of
EMXLIBC.DLL supporting localized character sets.

-----------------------------------------------------------------------------
OS2::REXX Module (external library):
------------------------------------

NOTE: By default, the REXX variable pool is not available, neither to
Perl, nor to external REXX functions. To enable it, you have to start
Perl with the switch -R, which makes Perl call its interpreter through
REXX. REXX functions which do not use variables may be usable even
without -R though.

Load REXX DLL:

	$dll = load OS2::REXX NAME [, WHERE];

	NAME is DLL name, without path and extension.

	Directories are searched WHERE first (list of dirs), then
	environment paths PERL5REXX, PERLREXX or, as last resort, PATH.

	The DLL is not unloaded when the variable dies.

	Returns DLL object reference, or undef on failure.

Define function prefix:

	$dll->prefix(NAME);

	Define the prefix of external functions, prepended to the
	function names used within your program, when looking for
	the entries in the DLL.

	Example:
		$dll = load OS2::REXX "RexxBase";
		$dll->prefix("RexxBase_");
		$dll->Init();
	is the same as
		$dll = load OS2::REXX "RexxBase";
		$dll->RexxBase_Init();

Define queue:

	$dll->queue(NAME);

	Define the name of the REXX queue passed to all external
	functions of this module. Defaults to "SESSION".

Check for functions (optional):

	BOOL = $dll->find(NAME [, NAME [, ...]]);

	Returns true if all functions are available.

Call external REXX function:

	$dll->function(arguments);

	Returns the return string if the return code is 0, else undef.
	Dies with error message if the function is not available.

Bind scalar variable to REXX variable:

	tie $var, OS2::REXX, "NAME";

Bind array variable to REXX stem variable:

	tie @var, OS2::REXX, "NAME.";

	Only scalar operations work so far. No array assignments,
	no array operations, ... FORGET IT.

Bind hash array variable to REXX stem variable:

	tie %var, OS2::REXX, "NAME.";

	To access all visible REXX variables via hash array, bind to "";

	No array assignments. No array operations, other than hash array
	operations. Just like the *dbm based implementations.

	For the usual REXX stem variables, append a "." to the name,
	as shown above. If the hash key is part of the stem name, for
	example if you bind to "", you cannot use lower case in the stem
	part of the key and it is subject to character set restrictions.

Erase individual REXX variables (bound or not):

	OS2::REXX::drop("NAME" [, "NAME" [, ...]]);

Note that while function and variable names are case insensitive in the
REXX language, function names exported by a DLL and the REXX variables
(as seen by Perl through the chosen API) are all case sensitive!

Most REXX DLLs export function names all upper case, but there are a
few which export mixed case names (such as RxExtras). When trying to
find the entry point, both exact case and all upper case are searched.
If the DLL exports "RxNap", you have to specify the exact case, if it
exports "RXOPEN", you can use any case.

To avoid interfering with subroutine names defined by Perl (DESTROY)
or used within the REXX module (prefix, find), it is best to use mixed
case and to avoid lowercase only or uppercase only names when calling
REXX functions. Be consistent. The same function written in different
ways results in different Perl stubs.

There is no REXX interpolation on variable names, so the REXX variable
name TEST.ONE is not affected by some other REXX variable ONE. And it
is not the same variable as TEST.one!

You cannot call REXX functions which are not exported by the DLL.
While most DLLs export all their functions, some, like RxFTP, export
only "...LoadFuncs", which registers the functions within REXX only.

You cannot call 16-bit DLLs. The few interesting ones I found
(FTP,NETB,APPC) do not export their functions.

I do not know whether the REXX API is reentrant with respect to
exceptions (signals) when the REXX top-level exception handler is
overridden. So unless you know better than I do, do not access REXX
variables (probably tied to Perl variables) or call REXX functions
which access REXX queues or REXX variables in signal handlers.

See ext/OS2/REXX/rx*.pl for examples.

-----------------------------------------------------------------------------
OS2::UPM (external library):
----------------------------

UPM constants (see <upm.h>) are exported automatically, functions only
on request.

(USERID, TYPE) = local_user ()

	return local user

LIST = user_list (REMOTENODE="", REMOTETYPE_UPM_LOCAL)
	LIST = 4 items per logged on user
		[0] = user id
		[1] = remote node name
		[2] = remote node type (INT)
		[3] = session id (INT)

(USERID, TYPE) = local_logon ()

	do a local logon, PM window, if not already logged on

BOOL = logon (USERID, PASSWORD, AUTHCHECK=UPM_USER, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
BOOL = logoff (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)

	logon/logoff process (DB2/2)

BOOL = logon_user (USERID, PASSWORD, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
BOOL = logoff_user (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)

	logon/logoff user

ERRCODE = error ()

	return UPM error code of last failure

STRING = message (ERRCODE)

	return message text for supplied UPM error code

Defaults:
	REMOTETYPE = UPM_LOCAL
	REMOTENODE = ""
	AUTHCHECK  = UPM_USER

-----------------------------------------------------------------------------
OS2::FTP (external library):
----------------------------

$acct = new FTP "host", "userid", "passwd" [, "acct"]

	Create virtual FTP session - no login.

FTP::logoff()

	Logoff all sessions.

($msec, $address) = FTP::ping("host", pktlen);
$msec = FTP::ping($address, pktlen);

	Ping host. Returns milliseconds or negative error code.
	$address is 32-bit number.

$errno = $acct->errno();

	Return last error code (FTP*).

$text = FTP::message($errno);

	Return message text of last error.

$status:  <0 on error, >=0 on success.
$tfrtype: T_BINARY, T_ASCII, T_EBCDIC
"mode":   "w" for overwrite, "a" for append

$status = $acct->dir("local", "pattern"="*");
$status = $acct->ls("local", "pattern"="*");

$status = $acct->chdir("dir");
$status = $acct->mkdir("dir");
$status = $acct->rmdir("dir");
($status, $cwd) = $acct->getcwd();

$status = $acct->get("local", "remote"=local, "mode"="w", $tfrtype=T_BINARY);

$status = $acct->put("local", "remote"=local, $tfrtype=T_BINARY);
$status = $acct->putunique("local", "remote"=local, $tfrtype=T_BINARY);
$status = $acct->append("local", "remote"=local, $tfrtype=T_BINARY);

$status = $acct->rename("from", "to");
$status = $acct->delete("name");

$status = $acct->proxy($source_acct, "dst_file", "src_file", $tfrtype=T_BINARY);

$status = $acct->quote("string");
$status = $acct->site("string");
($status, $infostring) = $acct->sys();

-----------------------------------------------------------------------------
DB2CLI (external library):
--------------------------

See lib/DB2CLI.pm.

I did not check the output of a pod2somewhat converter because the
perl5 package (at least the one here) does not seem to have a
converter which accepts some .pm file (or I don't grok the way it
should be used).

-----------------------------------------------------------------------------
SNMP Distributed Programming Interface (DPI):
---------------------------------------------

Not much docs yet, sorry.

For the copyright of IBM's DPI library code, see ext/DPI/DOC/README.

The module interface mimics DPI 2.0. The implementation may use the
DPI 1.1 or the DPI 2.0 protocol, depending on how the DPI library is
built. The shipped binary use the DPI 1.1 protocol, which is supported
at least by the OS/2 and AIX agents.

-----------------------------------------------------------------------------
Other:
------

  setpriority WHICH,PID,PRIO

	Set priority of process or process tree.

	WHICH:	ignored (what's it good for?)

	PID:	>= 0:	process only
		<  0:	process tree

	PRIO:	class << 8 | delta

	    class:	0	no change
	 		1	idle-time	(lowest)
	  		2	regular
	  		3	time-critical	(highest)
	  		4	fixed-high	(between 2 and 3)

	    delta:	-31..+31

  getpriority IGNORED,PID

  	Return priority of process.

		Bits 8..15	priority class (1..4)
		Bits 0..7	priority within class (0..31)

  system LIST

	If the first element of LIST is an integer, it controls the
	mode of the started process and the relationship between the
	starting (father) and the started (child) process.

	You can use either one of the process modes:

		P_WAIT (0)	= wait until child terminates (default)
		P_NOWAIT	= do not wait until child terminates
		P_SESSION	= new session
		P_DETACH	= detached
		P_PM		= PM program

	and optionally add PM and session option bits:

		P_DEFAULT (0)	= default
		P_MINIMIZE	= minimized
		P_MAXIMIZE	= maximized
		P_FULLSCREEN	= fullscreen (session only)
		P_WINDOWED	= windowed (session only)

		P_FOREGROUND	= foreground (if running in foreground)
		P_BACKGROUND	= background

		P_NOCLOSE	= don't close window on exit (session only)

		P_QUOTE		= quote all arguments
		P_TILDE		= MKS argument passing convention
		P_UNRELATED	= do not kill child when father terminates

	The constants shown above are defined by OS2::Process.

	If P_UNRELATED is set, there is no father/child relationship.
	The starting process does not wait for termination of the new
	process, no matter what process mode is given, and system()
	does not return the process id (a "feature" of OS/2).

	If the process is started in P_WAIT mode, system() waits for
	completion of the child process and returns its termination
	status.

	Otherwise system() does not wait for termination of the child
	process and returns the process id of the child process. When
	the father process terminates, the child process is killed!

	Example:
	    use OS2::Process;
	    $pid = system(P_PM+P_BACKGROUND, "epm.exe");

	NOTE: Whether the first argument is a process control or not is
	guessed by looking at the data type. However Perl's dynamic
	typing system may yield unexpected results.

  system STRING
  exec STRING

	If the string starts with "@" or contains any of "%&|<>",
	it is called as a shell command. Else the program is called
	directly.

	If the environment variable SHELL is defined, it is used
	instead of COMSPEC when running shell commands. It should
	be a Unix-style shell.

  file checks (-X), stat(), ...

  	When testing filenames, not handles, char-devices are detected
  	only when prefixed by "/dev/", so "/dev/con" is valid, "con" is
  	not.

	Currently, only /dev/con and /dev/tty are recognized.

-----------------------------------------------------------------------------
History:

15.12.94 	Initial release (perl5000.zip).

17.12.94	Moved REXX sub defn to find(). Hash array for functions no
		longer required, allows overriding subs like "find".

		DLL entries are case sensitive, try both upper case and
		exact case.

18.12.94	Detect char- and block-devices (stat() hack). Some future
		release may probably remove block device support, once
		char-device support is built into EMX.

		Fixed perl5db tty check.

22.12.94	EMX fixlevel 2 exports its exception handler, so now
		signals work even when the REXX variable pool is enabled.

		Disabled error and exception popups.

27.12.94	Case conversions of tied variables cleaned up.

		REXX (REXX.DLL, REXXAPI.DLL) now loaded on demand.

7.1.95		Fixed Shell module (did not allow more than one argument).

11.1.95		Accept drive letter as absolute path in do/require/use.

13.1.95		Larrys memory-leak patches (#1, dated Friday 13).

26.1.95		fcntl and ioctl were missing. fcntl was explicitly disabled
		in its source code (ifndef DOSISH) and the ioctl enabler is
		in the wrong place (unixish.h instead of config.sh).

16.3.95 	DosQueryFSAttach (stat hack) may crash the system. Now just
		look for /dev/con and /dev/tty.

		Applied "pad_findlex" patch (patches/1).

23.3.95		Support fork. Two executables, one for DLLs and one for fork.

24.3.95	5.001

13.4.95		Patchlevel "c".

21.4.95		Truncate names of extension DLLs to 8 chars - Warp no longer
		accepts them (2.x did).

22.4.95		Replaced EMX dirent by my own to get all directory entries
		even when HPFS386 is used. Additionally, my implementation
		is not restricted in the total size of the directory (a
		conflict between Perl's memory allocator and the one of the
		EMX library DLL).

27.4.95		Support for fork() disabled system() in DLL version.

7.5.95		Added Tye McQueen's FileGlob. See File::KGlob*.

12.5.95		Fixed Cwd. Fixed OS/2 dependencies in MakeMaker, with
		a few Config.sh items added (separators, exe-extension).

		Moved UPM and REXX to OS2::. Combined REXXCALL and REXX.
		Plain old REXX module is still available as passthru though.

		Perl DLLs now have an underscore appended to avoid name
		conflicts with standard OS/2 DLLs (see DynaLoader.pm).

13.5.95		Added FTP API support (OS2::FTP).
		
2.7.95		Applied "official unofficial" patches up to level "m".
		The modpods documentation now is in the modules themselves.

4.7.95		Implement command pipes (my_popen) using fork instead of
		standard popen in the fork version (perl5x.exe). While this
		is a lot slower, it correctly returns the process id and
		supports open(F,"-|") and open(F,"|-").

		Use the same code for exec(CMD) as for system(CMD).

		Support socket functions (set|get|end)(host|net|proto|serv)ent.

15.7.95	5.001m

3.8.95		DB2 CLI module.

12.8.95		A debug printf was left over in perl5x.exe. And the shipped
		OS/2 patches were not up to date with the executables.

25.8.95		Due to inconsistent naming of DLLs of modules with more than
		8 chars, such DLLs were not loadable. The underscore is first
		appended to the full name, then it is truncated to 8 chars.

9.1.96		EMX 0.9b

		Added DB_File (since supported by EMX).

		POSIX::ttyname is now available.

20.2.96	5.002á3

		Still based on my own makefiles and hand-made config files
		(sorry Ilya). I have neither interest nor time to convert
		my system into a unix fake, make shell profiles, correct
		paths and environment variables in such a way that they
		work with unix shells, hack conflicting utilities (I'm
		using my own "cp","rm",...) and so on.

		Changed DLL naming convention to get compatible with
		Ilya's implementation: at most 7 chars plus underscore
		(well, it's more reasonable anyway)

		Localization is enabled. Please read the note above.

22.2.96		SNMP-DPI module.

26.2.96		Removed SDBM from distribution. DB should do.

		Added more extension modules as builtins into perl5x.

		Added OS2::Process module for verbose names for the child
		process control flags of system(). Fixed the type check of
		the process control argument.
