os2/README.old

   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.