OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl501m.zip / README.os2 < prev next >

Wrap

Text File | 1995-07-15 | 16.8 KB | 526 lines

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.