Commit | Line | Data |
c0c09dfd |
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. |