diff options
Diffstat (limited to 'gnu/usr.bin/perl/os2/README.old')
| -rw-r--r-- | gnu/usr.bin/perl/os2/README.old | 529 |
1 files changed, 529 insertions, 0 deletions
diff --git a/gnu/usr.bin/perl/os2/README.old b/gnu/usr.bin/perl/os2/README.old new file mode 100644 index 00000000000..f49d6be1fa6 --- /dev/null +++ b/gnu/usr.bin/perl/os2/README.old @@ -0,0 +1,529 @@ +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. |