home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl501m.zip / README.os2 < prev   
Text File  |  1995-07-15  |  17KB  |  526 lines
  1.             Perl 5.001 for OS/2.
  2.                Patchlevel "m"
  3.  
  4.         Copyright (c) 1989,1990,1991,1992,1993,1994  Larry Wall
  5.                        All rights reserved.
  6.  
  7.         OS/2 port Copyright (c) 1990, 1991, 1994-95
  8.            Raymond Chen, Kai Uwe Rommel, Andreas Kaiser
  9.                             
  10. Version 5 port (this package) by Andreas Kaiser <ak@ananke.s.bawue.de>
  11. (2:246/8506.9@fidonet).
  12.  
  13. To run the executables supplied with this file, you have to install the
  14. EMX runtime package emxrt.zip of version 0.9a05 (0.9a, fixlevel 5) or
  15. later.
  16.  
  17. The file emxrt.zip is available at ftp.rus.uni-stuttgart.de (the
  18. origin), ftp-os2.nmsu.edu and many other places.
  19.  
  20. The source code of the original Perl 5.0 distribution is not included
  21. here. You can get it at ftp://ftp.wpi.edu:/perl5/perl5.001.tar.gz (and
  22. many other places).
  23.  
  24. For documentation of Perl 5, look at the files into the directory tree
  25. "pod". For TeX or Postscript docs, get perlref-5.000.0.tar.gz. A LaTeX
  26. and postscript reference card is available at
  27.   ftp.NL.net:/pub/comp/programming/languages/perl/perlref-5.000.0.tar.gz
  28.   prep.ai.mit.edu:/pub/gnu/perlref-5.000.0.tar.gz
  29.  
  30. Many REXX DLLs complement the features available by standard Perl,
  31. supporting system calls (YdbaUtil - RXU??.ZIP), xBase (RexxBase,
  32. shareware), serial I/O (RxAsync) and basic PM dialogs (VRexx). These
  33. packages can be found at many OS/2 FTP servers.
  34.  
  35. -----------------------------------------------------------------------------
  36. Installation:
  37. -------------
  38.  
  39. If you did not have HPFS up to now, this is the right time to reformat
  40. your filesystem(s)... While Perl itself does not require HPFS, a lot
  41. of Perl library files do. Or try EMXOPT=-t.
  42.  
  43. copy perl5.exe perl5x.exe `some PATH dir`
  44. copy os2\perlglob.exe `some PATH dir`
  45. copy perl5.dll `some LIBPATH dir`
  46.  
  47. set PERL5LIB=x:/your/own/perl/lib;y:/somewhere/perl5/lib
  48.  
  49. The perl5 extension DLLs (POSIX_.DLL, REXX_.DLL, ...) do not need a
  50. LIBPATH entry.
  51.  
  52. Executables:
  53. ------------
  54.  
  55. perl5.exe,perl5.dll :    DynaLoader, REXX support, external DLLs
  56.  
  57.             No fork. Running a command via open() returns 1
  58.             instead of the child process id.
  59.  
  60.             Other modules supported via extension DLLs, no
  61.             builtins other than DynaLoader.
  62.  
  63. perl5x.exe :        No Dynaloader, no REXX.
  64.  
  65.             Supports fork. Running a command via open() uses fork
  66.             (slow) and correctly returns the child process id.
  67.  
  68.             POSIX and Socket modules builtin. No other extension
  69.             modules supported.
  70.  
  71.             Note that lib/Socket.pm and lib/POSIX.pm reflect
  72.             DLL use. If you need them with perl5x.exe, you
  73.             have to remove the "bootstrap" line.
  74.  
  75. -----------------------------------------------------------------------------
  76. Building:
  77. ---------
  78.  
  79. Requires:
  80. - Perl5.001.tar.gz (Perl 5.001 sources).
  81. - EMX 0.9a05 or later (Compiler).
  82. - OS/2 Development Toolkit (or change REXX inc/lib references).
  83. - Korn shell (ksh) or some other Unix-like shell named ksh.
  84. - DMake, with group recipes configured for a Unix shell.
  85. - Larry Walls "patch" program.
  86. - Several Unix-like tools, such as cp, cat, touch, find, ...
  87.  
  88. get Perl 5.001 source
  89. apply patches\*        -- "official unofficial" patches to 5.001
  90. apply os2\patches    -- OS/2 platform patches
  91. copy ext\DynaLoader\dl_os2.xs ext\DynaLoader\DynaLoader.xs
  92. copy os2\config.sh .
  93. copy os2\makefile.mk .
  94.  
  95. If you do not have UPM (User Profile Management), remove "UPM" from
  96. makefile.mk.
  97.  
  98. -----------------------------------------------------------------------------
  99. Not supported, bugs, "OS/2 is Not Unix":
  100. ----------------------------------------
  101.  
  102. Depending on whether you run perl5.exe or perl5x.exe, you can either
  103. use extension modules and REXX, or fork, since the EMX implementation
  104. of fork conflicts with DLL support. Remember that there is a hidden
  105. fork in open(F, "-|") and open(F, "|-").
  106.  
  107. config.sh (Config.pm) lies. It shows d_fork='undef' even though it is
  108. available in perl5x.exe. "dynamic_ext" and "extensions" are incorrect
  109. for perl5x.exe.
  110.  
  111. flock is available but does not yet work in EMX 0.9a.
  112.  
  113. ttyname and ctermid do not work (return NULL).
  114.  
  115. ... and of course a lot of Unix-isms like process group, user and group
  116. management, links, ...
  117.  
  118. For details, look into config.sh and the EMX library reference.
  119.  
  120. I did not test SDBM. I just added a lot of O_BINARY flags and compiled it.
  121.  
  122. Several scripts of the test suite (see source distribution) fail due to
  123. Unix-isms like /bin/sh, `echo *`, different quoting requirements, ...
  124.  
  125. When opening a command pipe [such as open(F,"cat|")], perl5.exe
  126. returns 1 instead of the child's process id. Perl5x.exe correctly
  127. returns the process id.
  128.  
  129. OS/2 does not have a true exec API (which is used both by the exec
  130. function and when opening a command pipe with perl5x.exe). What
  131. actually happens is the call of a subprocess with the father waiting
  132. for the termination of its child. While waiting, the father still owns
  133. all its resources (it passes signals to the child however) and there
  134. may be some other side effects as well.
  135.  
  136. -----------------------------------------------------------------------------
  137. OS2::REXX Module (external library):
  138. ------------------------------------
  139.  
  140. NOTE: By default, the REXX variable pool is not available, neither to
  141. Perl, nor to external REXX functions. To enable it, you have to start
  142. Perl with the switch -R, which makes Perl call its interpreter through
  143. REXX. REXX functions which do not use variables may be usable even
  144. without -R though.
  145.  
  146. Load REXX DLL:
  147.  
  148.     $dll = load OS2::REXX NAME [, WHERE];
  149.  
  150.     NAME is DLL name, without path and extension.
  151.  
  152.     Directories are searched WHERE first (list of dirs), then
  153.     environment paths PERL5REXX, PERLREXX or, as last resort, PATH.
  154.  
  155.     The DLL is not unloaded when the variable dies.
  156.  
  157.     Returns DLL object reference, or undef on failure.
  158.  
  159. Define function prefix:
  160.  
  161.     $dll->prefix(NAME);
  162.  
  163.     Define the prefix of external functions, prepended to the
  164.     function names used within your program, when looking for
  165.     the entries in the DLL.
  166.  
  167.     Example:
  168.         $dll = load OS2::REXX "RexxBase";
  169.         $dll->prefix("RexxBase_");
  170.         $dll->Init();
  171.     is the same as
  172.         $dll = load OS2::REXX "RexxBase";
  173.         $dll->RexxBase_Init();
  174.  
  175. Define queue:
  176.  
  177.     $dll->queue(NAME);
  178.  
  179.     Define the name of the REXX queue passed to all external
  180.     functions of this module. Defaults to "SESSION".
  181.  
  182. Check for functions (optional):
  183.  
  184.     BOOL = $dll->find(NAME [, NAME [, ...]]);
  185.  
  186.     Returns true if all functions are available.
  187.  
  188. Call external REXX function:
  189.  
  190.     $dll->function(arguments);
  191.  
  192.     Returns the return string if the return code is 0, else undef.
  193.     Dies with error message if the function is not available.
  194.  
  195. Bind scalar variable to REXX variable:
  196.  
  197.     tie $var, OS2::REXX, "NAME";
  198.  
  199. Bind array variable to REXX stem variable:
  200.  
  201.     tie @var, OS2::REXX, "NAME.";
  202.  
  203.     Only scalar operations work so far. No array assignments,
  204.     no array operations, ... FORGET IT.
  205.  
  206. Bind hash array variable to REXX stem variable:
  207.  
  208.     tie %var, OS2::REXX, "NAME.";
  209.  
  210.     To access all visible REXX variables via hash array, bind to "";
  211.  
  212.     No array assignments. No array operations, other than hash array
  213.     operations. Just like the *dbm based implementations.
  214.  
  215.     For the usual REXX stem variables, append a "." to the name,
  216.     as shown above. If the hash key is part of the stem name, for
  217.     example if you bind to "", you cannot use lower case in the stem
  218.     part of the key and it is subject to character set restrictions.
  219.  
  220. Erase individual REXX variables (bound or not):
  221.  
  222.     OS2::REXX::drop("NAME" [, "NAME" [, ...]]);
  223.  
  224. Note that while function and variable names are case insensitive in the
  225. REXX language, function names exported by a DLL and the REXX variables
  226. (as seen by Perl through the chosen API) are all case sensitive!
  227.  
  228. Most REXX DLLs export function names all upper case, but there are a
  229. few which export mixed case names (such as RxExtras). When trying to
  230. find the entry point, both exact case and all upper case are searched.
  231. If the DLL exports "RxNap", you have to specify the exact case, if it
  232. exports "RXOPEN", you can use any case.
  233.  
  234. To avoid interfering with subroutine names defined by Perl (DESTROY)
  235. or used within the REXX module (prefix, find), it is best to use mixed
  236. case and to avoid lowercase only or uppercase only names when calling
  237. REXX functions. Be consistent. The same function written in different
  238. ways results in different Perl stubs.
  239.  
  240. There is no REXX interpolation on variable names, so the REXX variable
  241. name TEST.ONE is not affected by some other REXX variable ONE. And it
  242. is not the same variable as TEXT.one!
  243.  
  244. You cannot call REXX functions which are not exported by the DLL.
  245. While most DLLs export all their functions, some, like RxFTP, export
  246. only "...LoadFuncs", which registers the functions within REXX only.
  247.  
  248. You cannot call 16-bit DLLs. The few interesting ones I found
  249. (FTP,NETB,APPC) do not export their functions.
  250.  
  251. I do not know whether the REXX API is reentrant with respect to
  252. exceptions (signals) when the REXX top-level exception handler is
  253. overridden. So unless you know better than I do, do not access REXX
  254. variables (probably tied to Perl variables) or call REXX functions
  255. which access REXX queues or REXX variables in signal handlers.
  256.  
  257. See ext/OS2/REXX/rx*.pl for examples.
  258.  
  259. -----------------------------------------------------------------------------
  260. OS2::UPM (external library):
  261. ----------------------------
  262.  
  263. UPM constants (see <upm.h>) are exported automatically, functions only
  264. on request.
  265.  
  266. (USERID, TYPE) = local_user ()
  267.  
  268.     return local user
  269.  
  270. LIST = user_list (REMOTENODE="", REMOTETYPE_UPM_LOCAL)
  271.     LIST = 4 items per logged on user
  272.         [0] = user id
  273.         [1] = remote node name
  274.         [2] = remote node type (INT)
  275.         [3] = session id (INT)
  276.  
  277. (USERID, TYPE) = local_logon ()
  278.  
  279.     do a local logon, PM window, if not already logged on
  280.  
  281. BOOL = logon (USERID, PASSWORD, AUTHCHECK=UPM_USER, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
  282. BOOL = logoff (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
  283.  
  284.     logon/logoff process (DB2/2)
  285.  
  286. BOOL = logon_user (USERID, PASSWORD, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
  287. BOOL = logoff_user (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
  288.  
  289.     logon/logoff user
  290.  
  291. ERRCODE = error ()
  292.  
  293.     return UPM error code of last failure
  294.  
  295. STRING = message (ERRCODE)
  296.  
  297.     return message text for supplied UPM error code
  298.  
  299. Defaults:
  300.     REMOTETYPE = UPM_LOCAL
  301.     REMOTENODE = ""
  302.     AUTHCHECK  = UPM_USER
  303.  
  304. -----------------------------------------------------------------------------
  305. OS2::FTP (external library):
  306. ----------------------------
  307.  
  308. $acct = new FTP "host", "userid", "passwd" [, "acct"]
  309.  
  310.     Create virtual FTP session - no login.
  311.  
  312. FTP::logoff()
  313.  
  314.     Logoff all sessions.
  315.  
  316. ($msec, $address) = FTP::ping("host", pktlen);
  317. $msec = FTP::ping($address, pktlen);
  318.  
  319.     Ping host. Returns milliseconds or negative error code.
  320.     $address is 32-bit number.
  321.  
  322. $errno = $acct->errno();
  323.  
  324.     Return last error code (FTP*).
  325.  
  326. $text = FTP::message($errno);
  327.  
  328.     Return message test of last error.
  329.  
  330. $status:  <0 on error, >=0 on success.
  331. $tfrtype: T_BINARY, T_ASCII, T_EBCDIC
  332. "mode":   "w" for overwrite, "a" for append
  333.  
  334. $status = $acct->dir("local", "pattern"="*");
  335. $status = $acct->ls("local", "pattern"="*");
  336.  
  337. $status = $acct->chdir("dir");
  338. $status = $acct->mkdir("dir");
  339. $status = $acct->rmdir("dir");
  340. ($status, $cwd) = $acct->getcwd();
  341.  
  342. $status = $acct->get("local", "remote"=local, "mode"="w", $tfrtype=T_BINARY);
  343.  
  344. $status = $acct->put("local", "remote"=local, $tfrtype=T_BINARY);
  345. $status = $acct->putunique("local", "remote"=local, $tfrtype=T_BINARY);
  346. $status = $acct->append("local", "remote"=local, $tfrtype=T_BINARY);
  347.  
  348. $status = $acct->rename("from", "to");
  349. $status = $acct->delete("name");
  350.  
  351. $status = $acct->proxy($source_acct, "dst_file", "src_file", $tfrtype=T_BINARY);
  352.  
  353. $status = $acct->quote("string");
  354. $status = $acct->site("string");
  355. ($status, $infostring) = $acct->sys();
  356.  
  357. -----------------------------------------------------------------------------
  358. Other:
  359. ------
  360.  
  361.   setpriority CLASS,PID,DELTA
  362.  
  363.     Set priority of process or process tree.
  364.  
  365.     PID:
  366.         >= 0:    process only
  367.         <  0:    process tree
  368.  
  369.     CLASS:
  370.         0    no change
  371.          1    idle-time    (lowest)
  372.           2    regular        (dynamic priority)
  373.           3    time-critical    (highest)
  374.           4    fixed-high    (between regular and time-critical)
  375.  
  376.     DELTA:
  377.         -31..+31
  378.  
  379.   getpriority IGNORED,PID
  380.  
  381.       Return priority of process or process tree.
  382.  
  383.         Bits 8..15    priority class (1..4)
  384.         Bits 0..7    priority within class (0..31)
  385.  
  386.   system LIST
  387.  
  388.     If the first element of LIST is an integer, it controls the
  389.     started child process or session as follows:
  390.  
  391.         0    = wait until child terminates (default)
  392.         1    = do not wait, use wait() or waitpid() for status
  393.         4    = new session
  394.         5    = detached
  395.         6    = PM program
  396.  
  397.     PM and session options, or-ed in:
  398.  
  399.         0x00000    = default
  400.         0x00100    = minimized
  401.         0x00200    = maximized
  402.         0x00300    = fullscreen (session only)
  403.         0x00400    = windowed (session only)
  404.  
  405.         0x00000    = foreground (only if running in foreground)
  406.         0x01000    = background
  407.  
  408.         0x02000    = don't close window on exit (session only)
  409.  
  410.         0x10000 = quote all arguments
  411.         0x20000    = MKS argument passing convention
  412.  
  413.     If the control is not zero, system() does not wait until
  414.     the child terminates and the return code is the id of the
  415.     child process.
  416.  
  417.     If the control is not zero, and you do not call wait or
  418.     waitpid, the child status fills up memory.
  419.  
  420.     Note: If the program is started with a mode of 4 or 6, it may
  421.     be aborted when the starting program (perl) terminates. Later
  422.     releases of EMX.DLL will probably know yet another flag bit
  423.     to cut this fatal relationship.
  424.  
  425.   system STRING
  426.   exec STRING
  427.  
  428.     If the string starts with "@" or contains any of "%&|<>",
  429.     it is called as a shell command. Else the program is called
  430.     directly.
  431.  
  432.     If the environment variable SHELL is defined, it is used
  433.     instead of COMSPEC when running shell commands. It should
  434.     be a Unix-style shell.
  435.  
  436.   file checks (-X), stat(), ...
  437.  
  438.       When testing filenames, not handles, char-devices are detected
  439.       only when prefixed by "/dev/", so "/dev/con" is valid, "con" is
  440.       not.
  441.  
  442.     Currently, only /dev/con and /dev/tty are recognized.
  443.  
  444. -----------------------------------------------------------------------------
  445. History:
  446.  
  447. 15.12.94     Initial release (perl5000.zip).
  448.  
  449. 17.12.94    Moved REXX sub defn to find(). Hash array for functions no
  450.         longer required, allows overriding subs like "find".
  451.  
  452.         DLL entries are case sensitive, try both upper case and
  453.         exact case.
  454.  
  455. 18.12.94    Detect char- and block-devices (stat() hack). Some future
  456.         release may probably remove block device support, once
  457.         char-device support is built into EMX.
  458.  
  459.         Fixed perl5db tty check.
  460.  
  461. 22.12.94    EMX fixlevel 2 exports its exception handler, so now
  462.         signals work even when the REXX variable pool is enabled.
  463.  
  464.         Disabled error and exception popups.
  465.  
  466. 27.12.94    Case conversions of tied variables cleaned up.
  467.  
  468.         REXX (REXX.DLL, REXXAPI.DLL) now loaded on demand.
  469.  
  470. 7.1.95        Fixed Shell module (did not allow more than one argument).
  471.  
  472. 11.1.95        Accept drive letter as absolute path in do/require/use.
  473.  
  474. 13.1.95        Larrys memory-leak patches (#1, dated Friday 13).
  475.  
  476. 26.1.95        fcntl and ioctl were missing. fcntl was explicitly disabled
  477.         in its source code (ifndef DOSISH) and the ioctl enabler is
  478.         in the wrong place (unixish.h instead of config.sh).
  479.  
  480. 16.3.95     DosQueryFSAttach (stat hack) may crash the system. Now just
  481.         look for /dev/con and /dev/tty.
  482.  
  483.         Applied "pad_findlex" patch (patches/1).
  484.  
  485. 23.3.95        Support fork. Two executables, one for DLLs and one for fork.
  486.  
  487. 24.3.95    5.001
  488.  
  489. 13.4.95        Patchlevel "c".
  490.  
  491. 21.4.95        Truncate names of extension DLLs to 8 chars - Warp no longer
  492.         accepts them (2.x did).
  493.  
  494. 22.4.95        Replaced EMX dirent by my own to get all directory entries
  495.         even when HPFS386 is used. Additionally, my implementation
  496.         is not restricted in the total size of the directory (a
  497.         conflict between Perls memory allocator and the one of the
  498.         EMX library DLL).
  499.  
  500. 27.4.95        Support for fork() disabled system() in DLL version.
  501.  
  502. 7.5.95        Added Tye McQueen's FileGlob. See File::KGlob*.
  503.  
  504. 12.5.95        Fixed Cwd. Fixed OS/2 dependencies in MakeMaker, with
  505.         a few Config.sh items added (separators, exe-extension).
  506.  
  507.         Moved UPM and REXX to OS2::. Combined REXXCALL and REXX.
  508.         Plain old REXX module is still available as passthru though.
  509.  
  510.         Perl DLLs now have an underscore appended to avoid name
  511.         conflicts with standard OS/2 DLLs (see DynaLoader.pm).
  512.  
  513. 13.5.95        Added FTP API support (OS2::FTP).
  514.         
  515. 2.7.95        Applied "official unofficial" patches up to level "m".
  516.         The modpods documentation now is in the modules themselves.
  517.  
  518. 4.7.95        Implement command pipes (my_popen) using fork instead of
  519.         standard popen in the fork version (perl5x.exe). While this
  520.         is a lot slower, it correctly returns the process id and
  521.         supports open(F,"-|") and open(F,"|-").
  522.  
  523.         Use the same code for exec(CMD) as for system(CMD).
  524.  
  525.         Support socket functions (set|get|end)(host|net|proto|serv)ent.
  526.