Python/2 -- The Python Interpreter for OS/2
===========================================

Assuming you have downloaded the binaries from my web site at
http://warped.cswnet.com/~jrush/python_os2, you are ready to
enter the wonderful world of Python programming.  To learn
more, just point your browser to the file x:\Python\html\index.html
on your local disk and begin reading.

For my non-OS/2 Python-related work, check out my other web page at:

    http://starship.python.net/crew/jrush.


-- Suggested Environment Variable Setup

With respect to the environment variables for Python, I use the
following setup:

    Set PYTHONHOME=C:\Python
    Set PYTHONPATH=.;C:\Python\Lib; \
                     C:\Python\Lib\plat-win; \
                     C:\Python\Lib\lib-tk; \
		     C:\Python\Lib\lib-dynload; \
		     C:\Python\Lib\site-packages; \
		     C:\Python\Lib\dos-8x3

Place any Python extension DLLs (often named .pyd instead of .dll)
you acquire into:

    C:\Python\Lib\lib-dynload

and add-on software in Python source form into:

    C:\Python\Lib\site-packages\<pkgname>


-- Testing your Installation

To Test your Installation, you can run the standard Python regression
test suite, by running the following commands:

    python C:\Python\lib\test\regrtest.py


-- Using Python as the Default OS/2 Batch Language

Note that OS/2 supports the Unix technique of putting the special
comment line at the time of scripts e.g. "#!/usr/bin/python" in
a different syntactic form.  To do this, put your script into a file
with a .CMD extension and added 'extproc' to the top as follows:

    extproc C:\Python\Python.exe -x
    import os
    print "Hello from Python"

The '-x' option tells Python to skip the first line of the file
while processing the rest as normal Python source.

If you are using the popular 4OS2 command shell replacement, you
can jus set an environment variable as:

    Set .PY=D:\Python\Python.exe

and any file with an extension of .py will automatically be executable.
This is a nice feature of 4OS2.


-- Functionality

This build includes support for most Python functionality as well as
TCP/IP sockets.  It omits the Posix ability to 'fork' a process but
supports threads using OS/2 native capabilities.  I have tried to
support everything possible but here are a few usage notes.


-- os.popen() Usage Warnings

With respect to my implementation of popen() under OS/2:

    import os

    fd = os.popen("pkzip.exe -@ junk.zip", 'wb')
    fd.write("file1.txt\n")
    fd.write("file2.txt\n")
    fd.write("file3.txt\n")
    fd.write("\x1a")  # Should Not Be Necessary But Is
    fd.close()

There is a bug, either in the VAC++ compiler or OS/2 itself, where the
simple closure of the write-side of a pipe -to- a process does not
send an EOF to that process.  I find I must explicitly write a
control-Z (EOF) before closing the pipe.  This is not a problem when
using popen() in read mode.

One other slight difference with my popen() is that I return None
from the close(), instead of the Unix convention of the return code
of the spawned program.  I could find no easy way to do this under
OS/2.


-- BEGINLIBPATH/ENDLIBPATH

With respect to environment variables, this OS/2 port supports the
special-to-OS/2 magic names of 'BEGINLIBPATH' and 'ENDLIBPATH' to
control where to load conventional DLLs from.  Those names are
intercepted and converted to calls on the OS/2 kernel APIs and
are inherited by child processes, whether Python-based or not.

A few new attributes have been added to the os module:

    os.meminstalled  # Count of Bytes of RAM Installed on Machine
    os.memkernel     # Count of Bytes of RAM Reserved (Non-Swappable)
    os.memvirtual    # Count of Bytes of Virtual RAM Possible
    os.timeslice     # Duration of Scheduler Timeslice, in Milliseconds
    os.maxpathlen    # Maximum Length of a Path Specification, in chars
    os.maxnamelen    # Maximum Length of a Single Dir/File Name, in chars
    os.version       # Version of OS/2 Being Run e.g. "4.00"
    os.revision      # Revision of OS/2 Being Run (usually zero)
    os.bootdrive     # Drive that System Booted From e.g. "C:"
                     # (useful to find the CONFIG.SYS used to boot with)


-- Recent Fixes/Compatability Improvements (Thanks to Michael Muller)

1) Fix for chdir function.

   The existing chdir function didn't change the current drive under OS/2.
   Since the current working directory really consists of the current drive
   and the drive's current working directory, chdir should really change the
   drive as well (especially since there is no chdrive function).

2) Fix for time.sleep()

   time.sleep() was using select() instead of DosSleep(), the native OS/2
   sleep function that was written into the code for it.  The select()
   method didn't work quite right, so DosSleep() is now being used.

3) Fix to make OS/2 locks function according to spec.

   The python lock acquire() method blocks if the same thread attempts
   to acquire the lock a second time, and the release() method can release
   a lock that was acquired by another thread.

   The OS/2 implementation was based on OS/2 mutex semaphores, which are
   owned by a particular thread & process.  As such, an attempt to
   re-acquire a lock from the owning thread always immediately succeeded and
   an attempt to release the lock from a non-owning thread always failed.

   Because of this, the standard Queue module didn't work under OS/2 - Queue
   uses locks as event semaphores which are triggered to notify another
   thread of an event.

   Locks under OS/2 were reimplemented using event semaphores and critical
   sections, and now they appear to function identically to the *NIX version.
   
   After implementing this fix, Fnorb's threaded model began to work under
   OS/2.


Rebuilding Using IBM VisualAge C/C++ for OS/2
=============================================

If you have installed the source package, to build Python for OS/2,
change into PC/os2vacpp and issue an 'NMAKE' command.  This will
build a PYTHON15.DLL containing the set of Python modules listed
in config.c and a small PYTHON.EXE to start the interpreter.

By changing the C compiler flag /Gd- in the makefile to /Gd+, you can
reduce the size of these by causing Python to dynamically link to the
C runtime DLLs instead of including their bulk in your binaries. 
However, this means that any system on which you run Python must have
the VAC++ compiler installed in order to have those DLLs available.

During the build process you may see a couple of harmless warnings:

  From the C Compiler, "No function prototype given for XXX", which
  comes from the use of K&R parameters within Python for portability.

  From the ILIB librarian, "Module Not Found (XXX)", which comes
  from its attempt to perform the (-+) operation, which removes and
  then adds a .OBJ to the library.  The first time a build is done,
  it obviously cannot remove what is not yet built.

Note that the makefile that ships with this release requires the
Warp 4 Toolkit headers and the MPTN Developer Kit headers/libraries.

-- Contact Info

If you have questions, suggestions or problems specifically with
the OS/2 VAC++ port of Python, please contact me at:

    Jeff Rush <jrush@summit-research.com>