perl 5.003_01: lib/File/Basename.pm

[p5sagit/p5-mst-13.2.git] / os2 / README.old

This documentation to the previous version is somewhat applicable yet.
No system() extensions, no -R option, the exec/system with one argument
will use sh.exe only (if required). IZ

			Perl 5.001 for OS/2.
			   Patchlevel "m"

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

		OS/2 port Copyright (c) 1990, 1991, 1994-95
	       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.9a05 (0.9a, fixlevel 5) 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.wpi.edu:/perl5/perl5.001.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. 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

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.

			POSIX and Socket modules builtin. No other extension
			modules supported.

			Note that lib/Socket.pm and lib/POSIX.pm reflect
			DLL use. If you need them with perl5x.exe, you
			have to remove the "bootstrap" line.

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

Requires:
- Perl5.001.tar.gz (Perl 5.001 sources).
- EMX 0.9a05 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 Unix-like tools, such as cp, cat, touch, find, ...

get Perl 5.001 source
apply patches\*		-- "official unofficial" patches to 5.001
apply os2\patches	-- OS/2 platform patches
copy ext\DynaLoader\dl_os2.xs ext\DynaLoader\DynaLoader.xs
copy os2\config.sh .
copy os2\makefile.mk .

If you do not have UPM (User Profile Management), remove "UPM" 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.

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

ttyname and ctermid do not work (return 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.

I did not test SDBM. I just added a lot of O_BINARY flags and compiled it.

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.

-----------------------------------------------------------------------------
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 TEXT.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 test 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();

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

  setpriority CLASS,PID,DELTA

	Set priority of process or process tree.

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

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

	DELTA:
		-31..+31

  getpriority IGNORED,PID

  	Return priority of process or process tree.

		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
	started child process or session as follows:

		0	= wait until child terminates (default)
		1	= do not wait, use wait() or waitpid() for status
		4	= new session
		5	= detached
		6	= PM program

	PM and session options, or-ed in:

		0x00000	= default
		0x00100	= minimized
		0x00200	= maximized
		0x00300	= fullscreen (session only)
		0x00400	= windowed (session only)

		0x00000	= foreground (only if running in foreground)
		0x01000	= background

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

		0x10000 = quote all arguments
		0x20000	= MKS argument passing convention

	If the control is not zero, system() does not wait until
	the child terminates and the return code is the id of the
	child process.

	If the control is not zero, and you do not call wait or
	waitpid, the child status fills up memory.

	Note: If the program is started with a mode of 4 or 6, it may
	be aborted when the starting program (perl) terminates. Later
	releases of EMX.DLL will probably know yet another flag bit
	to cut this fatal relationship.

  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 Perls 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.