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
8 Copyright (c) 1989,1990,1991,1992,1993,1994 Larry Wall
11 OS/2 port Copyright (c) 1990, 1991, 1994-95
12 Raymond Chen, Kai Uwe Rommel, Andreas Kaiser
14 Version 5 port (this package) by Andreas Kaiser <ak@ananke.s.bawue.de>
15 (2:246/8506.9@fidonet).
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
21 The file emxrt.zip is available at ftp.rus.uni-stuttgart.de (the
22 origin), ftp-os2.nmsu.edu and many other places.
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
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
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.
39 -----------------------------------------------------------------------------
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.
47 copy perl5.exe perl5x.exe `some PATH dir`
48 copy os2\perlglob.exe `some PATH dir`
49 copy perl5.dll `some LIBPATH dir`
51 set PERL5LIB=x:/your/own/perl/lib;y:/somewhere/perl5/lib
53 The perl5 extension DLLs (POSIX_.DLL, REXX_.DLL, ...) do not need a
59 perl5.exe,perl5.dll : DynaLoader, REXX support, external DLLs
61 No fork. Running a command via open() returns 1
62 instead of the child process id.
64 Other modules supported via extension DLLs, no
65 builtins other than DynaLoader.
67 perl5x.exe : No Dynaloader, no REXX.
69 Supports fork. Running a command via open() uses fork
70 (slow) and correctly returns the child process id.
72 POSIX and Socket modules builtin. No other extension
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.
79 -----------------------------------------------------------------------------
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, ...
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
97 copy os2\makefile.mk .
99 If you do not have UPM (User Profile Management), remove "UPM" from
102 -----------------------------------------------------------------------------
103 Not supported, bugs, "OS/2 is Not Unix":
104 ----------------------------------------
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, "|-").
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
115 flock is available but does not yet work in EMX 0.9a.
117 ttyname and ctermid do not work (return NULL).
119 ... and of course a lot of Unix-isms like process group, user and group
120 management, links, ...
122 For details, look into config.sh and the EMX library reference.
124 I did not test SDBM. I just added a lot of O_BINARY flags and compiled it.
126 Several scripts of the test suite (see source distribution) fail due to
127 Unix-isms like /bin/sh, `echo *`, different quoting requirements, ...
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.
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.
140 -----------------------------------------------------------------------------
141 OS2::REXX Module (external library):
142 ------------------------------------
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
152 $dll = load OS2::REXX NAME [, WHERE];
154 NAME is DLL name, without path and extension.
156 Directories are searched WHERE first (list of dirs), then
157 environment paths PERL5REXX, PERLREXX or, as last resort, PATH.
159 The DLL is not unloaded when the variable dies.
161 Returns DLL object reference, or undef on failure.
163 Define function prefix:
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.
172 $dll = load OS2::REXX "RexxBase";
173 $dll->prefix("RexxBase_");
176 $dll = load OS2::REXX "RexxBase";
177 $dll->RexxBase_Init();
183 Define the name of the REXX queue passed to all external
184 functions of this module. Defaults to "SESSION".
186 Check for functions (optional):
188 BOOL = $dll->find(NAME [, NAME [, ...]]);
190 Returns true if all functions are available.
192 Call external REXX function:
194 $dll->function(arguments);
196 Returns the return string if the return code is 0, else undef.
197 Dies with error message if the function is not available.
199 Bind scalar variable to REXX variable:
201 tie $var, OS2::REXX, "NAME";
203 Bind array variable to REXX stem variable:
205 tie @var, OS2::REXX, "NAME.";
207 Only scalar operations work so far. No array assignments,
208 no array operations, ... FORGET IT.
210 Bind hash array variable to REXX stem variable:
212 tie %var, OS2::REXX, "NAME.";
214 To access all visible REXX variables via hash array, bind to "";
216 No array assignments. No array operations, other than hash array
217 operations. Just like the *dbm based implementations.
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.
224 Erase individual REXX variables (bound or not):
226 OS2::REXX::drop("NAME" [, "NAME" [, ...]]);
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!
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.
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.
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!
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.
252 You cannot call 16-bit DLLs. The few interesting ones I found
253 (FTP,NETB,APPC) do not export their functions.
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.
261 See ext/OS2/REXX/rx*.pl for examples.
263 -----------------------------------------------------------------------------
264 OS2::UPM (external library):
265 ----------------------------
267 UPM constants (see <upm.h>) are exported automatically, functions only
270 (USERID, TYPE) = local_user ()
274 LIST = user_list (REMOTENODE="", REMOTETYPE_UPM_LOCAL)
275 LIST = 4 items per logged on user
277 [1] = remote node name
278 [2] = remote node type (INT)
279 [3] = session id (INT)
281 (USERID, TYPE) = local_logon ()
283 do a local logon, PM window, if not already logged on
285 BOOL = logon (USERID, PASSWORD, AUTHCHECK=UPM_USER, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
286 BOOL = logoff (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
288 logon/logoff process (DB2/2)
290 BOOL = logon_user (USERID, PASSWORD, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
291 BOOL = logoff_user (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
297 return UPM error code of last failure
299 STRING = message (ERRCODE)
301 return message text for supplied UPM error code
304 REMOTETYPE = UPM_LOCAL
308 -----------------------------------------------------------------------------
309 OS2::FTP (external library):
310 ----------------------------
312 $acct = new FTP "host", "userid", "passwd" [, "acct"]
314 Create virtual FTP session - no login.
320 ($msec, $address) = FTP::ping("host", pktlen);
321 $msec = FTP::ping($address, pktlen);
323 Ping host. Returns milliseconds or negative error code.
324 $address is 32-bit number.
326 $errno = $acct->errno();
328 Return last error code (FTP*).
330 $text = FTP::message($errno);
332 Return message test of last error.
334 $status: <0 on error, >=0 on success.
335 $tfrtype: T_BINARY, T_ASCII, T_EBCDIC
336 "mode": "w" for overwrite, "a" for append
338 $status = $acct->dir("local", "pattern"="*");
339 $status = $acct->ls("local", "pattern"="*");
341 $status = $acct->chdir("dir");
342 $status = $acct->mkdir("dir");
343 $status = $acct->rmdir("dir");
344 ($status, $cwd) = $acct->getcwd();
346 $status = $acct->get("local", "remote"=local, "mode"="w", $tfrtype=T_BINARY);
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);
352 $status = $acct->rename("from", "to");
353 $status = $acct->delete("name");
355 $status = $acct->proxy($source_acct, "dst_file", "src_file", $tfrtype=T_BINARY);
357 $status = $acct->quote("string");
358 $status = $acct->site("string");
359 ($status, $infostring) = $acct->sys();
361 -----------------------------------------------------------------------------
365 setpriority CLASS,PID,DELTA
367 Set priority of process or process tree.
376 2 regular (dynamic priority)
377 3 time-critical (highest)
378 4 fixed-high (between regular and time-critical)
383 getpriority IGNORED,PID
385 Return priority of process or process tree.
387 Bits 8..15 priority class (1..4)
388 Bits 0..7 priority within class (0..31)
392 If the first element of LIST is an integer, it controls the
393 started child process or session as follows:
395 0 = wait until child terminates (default)
396 1 = do not wait, use wait() or waitpid() for status
401 PM and session options, or-ed in:
406 0x00300 = fullscreen (session only)
407 0x00400 = windowed (session only)
409 0x00000 = foreground (only if running in foreground)
412 0x02000 = don't close window on exit (session only)
414 0x10000 = quote all arguments
415 0x20000 = MKS argument passing convention
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
421 If the control is not zero, and you do not call wait or
422 waitpid, the child status fills up memory.
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.
432 If the string starts with "@" or contains any of "%&|<>",
433 it is called as a shell command. Else the program is called
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.
440 file checks (-X), stat(), ...
442 When testing filenames, not handles, char-devices are detected
443 only when prefixed by "/dev/", so "/dev/con" is valid, "con" is
446 Currently, only /dev/con and /dev/tty are recognized.
448 -----------------------------------------------------------------------------
451 15.12.94 Initial release (perl5000.zip).
453 17.12.94 Moved REXX sub defn to find(). Hash array for functions no
454 longer required, allows overriding subs like "find".
456 DLL entries are case sensitive, try both upper case and
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.
463 Fixed perl5db tty check.
465 22.12.94 EMX fixlevel 2 exports its exception handler, so now
466 signals work even when the REXX variable pool is enabled.
468 Disabled error and exception popups.
470 27.12.94 Case conversions of tied variables cleaned up.
472 REXX (REXX.DLL, REXXAPI.DLL) now loaded on demand.
474 7.1.95 Fixed Shell module (did not allow more than one argument).
476 11.1.95 Accept drive letter as absolute path in do/require/use.
478 13.1.95 Larrys memory-leak patches (#1, dated Friday 13).
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).
484 16.3.95 DosQueryFSAttach (stat hack) may crash the system. Now just
485 look for /dev/con and /dev/tty.
487 Applied "pad_findlex" patch (patches/1).
489 23.3.95 Support fork. Two executables, one for DLLs and one for fork.
493 13.4.95 Patchlevel "c".
495 21.4.95 Truncate names of extension DLLs to 8 chars - Warp no longer
496 accepts them (2.x did).
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
504 27.4.95 Support for fork() disabled system() in DLL version.
506 7.5.95 Added Tye McQueen's FileGlob. See File::KGlob*.
508 12.5.95 Fixed Cwd. Fixed OS/2 dependencies in MakeMaker, with
509 a few Config.sh items added (separators, exe-extension).
511 Moved UPM and REXX to OS2::. Combined REXXCALL and REXX.
512 Plain old REXX module is still available as passthru though.
514 Perl DLLs now have an underscore appended to avoid name
515 conflicts with standard OS/2 DLLs (see DynaLoader.pm).
517 13.5.95 Added FTP API support (OS2::FTP).
519 2.7.95 Applied "official unofficial" patches up to level "m".
520 The modpods documentation now is in the modules themselves.
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,"|-").
527 Use the same code for exec(CMD) as for system(CMD).
529 Support socket functions (set|get|end)(host|net|proto|serv)ent.