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