  PYVMS - Python on OpenVMS -General Manual                       PAGE 1
  title page


                        __
                       |  \ |   |       _
                       |__/ |   |  -   / \   -O-
                       |     \ /    \_/   \_/
                       |      |
                                              _
                                |  |  /\/\   / \
                                |  | / || \  \_
                                \  / |    |    \
                                 \/  |    |  \_/



  Copyright, 1996 - 1999 by Uwe Zessin

  ------------------------------------------------------------------------
  PYVMS - General Manual

  August 1999

  This manual contains documentation about 'Python on OpenVMS'.


  Software Version:
          PYVMS V1.5.2-V005


  Uwe Zessin, Germany
  ------------------------------------------------------------------------
  24-AUG-1999 ZE.

  PYVMS - Python on OpenVMS -General Manual                       PAGE 2
  Python copyright


  0.1  The original Python Copyright

  (copied from MISC/COPYRIGHT.)


  Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
  The Netherlands.

                          All Rights Reserved

  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose and without fee is hereby granted,
  provided that the above copyright notice appear in all copies and that
  both that copyright notice and this permission notice appear in
  supporting documentation, and that the names of Stichting Mathematisch
  Centrum or CWI or Corporation for National Research Initiatives or
  CNRI not be used in advertising or publicity pertaining to
  distribution of the software without specific, written prior
  permission.

  While CWI is the initial source for this software, a modified version
  is made available by the Corporation for National Research Initiatives
  (CNRI) at the Internet address ftp://ftp.python.org.

  STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  PERFORMANCE OF THIS SOFTWARE.

  ------------------------------------------------------------------------
  18-MAY-1998 ZE.

  PYVMS - Python on OpenVMS -General Manual                       PAGE 3
  PYVMS copyright


  0.2  The PYVMS Copyright


  Copyright 1996-1999, by Uwe Zessin

    This software is provided to you free of charge. Use at your own risk -
    if it doesn't work, I disclaim all responsibility.
    This software may be freely distributed as long as it is accompanied by
    the copyright notice. If you change this software, you may re-distribute
    it only if you keep the original notes AND an additional notice identifying
    you and indicating that you have changed it.

  ------------------------------------------------------------------------
  I have found this wording somewhere on  the  Internet  and  liked  it.
  Unfortunately  I  haven't  noted  the  author's  name so I cannot give
  credit.
  ------------------------------------------------------------------------
  14-FEB-1999 ZE.

  PYVMS - Python on OpenVMS -General Manual                       PAGE 4
  table of contents


                                     CONTENTS

          0.1       The original Python Copyright  . . . . . . . . . . 2
          0.2       The PYVMS Copyright  . . . . . . . . . . . . . . . 3


  CHAPTER 1       Introduction

          1.1     Welcome  . . . . . . . . . . . . . . . . . . . . . 1-1
          1.2     Version numbers / file names . . . . . . . . . . . 1-3


  CHAPTER 2       Documentation

          2.1     access to PYVMS documentation  . . . . . . . . . . 2-1
          2.2     conventions used in the documentation  . . . . . . 2-2


  CHAPTER 3       Patches

          3.1     Patches to OpenVMS . . . . . . . . . . . . . . . . 3-1
          3.1.1     Patches are available from:  . . . . . . . . . . 3-1
          3.1.2     Patches commented: . . . . . . . . . . . . . . . 3-1
          3.1.2.1   VAXACRT11_061  . . . . . . . . . . . . . . . . . 3-1
          3.2     Patches to Python  . . . . . . . . . . . . . . . . 3-2
          3.3     how patching is/was done on OpenVMS  . . . . . . . 3-2


  CHAPTER 4       Python in the OpenVMS environment

          4.1     path support . . . . . . . . . . . . . . . . . . . 4-1
          4.2     command line editing . . . . . . . . . . . . . . . 4-2
          4.3     dynamic loading  . . . . . . . . . . . . . . . . . 4-2
          4.4     embedding Python on OpenVMS  . . . . . . . . . . . 4-3


  CHAPTER 5       programming guidelines

          5.1     functions  . . . . . . . . . . . . . . . . . . . . 5-1
          5.1.1     arguments  . . . . . . . . . . . . . . . . . . . 5-1
          5.1.2     keyword arguments  . . . . . . . . . . . . . . . 5-1
          5.1.3     functions returning no data  . . . . . . . . . . 5-1
          5.1.4     functions returning dictionaries . . . . . . . . 5-2
          5.2     OpenVMS condition values . . . . . . . . . . . . . 5-2
          5.3     special OpenVMS datatypes  . . . . . . . . . . . . 5-2
          5.3.1     64-bit quadword  . . . . . . . . . . . . . . . . 5-2
          5.3.1.1   date and time calculations . . . . . . . . . . . 5-3
          5.3.2     128-bit octaword . . . . . . . . . . . . . . . . 5-4
          5.4     processes  . . . . . . . . . . . . . . . . . . . . 5-5
          5.4.1     privileges . . . . . . . . . . . . . . . . . . . 5-5
          5.4.2     process identification (PID) . . . . . . . . . . 5-6
          5.4.3     rightslist identifiers . . . . . . . . . . . . . 5-6
          5.5     security related objects . . . . . . . . . . . . . 5-7
          5.5.1     ACL + ACE  . . . . . . . . . . . . . . . . . . . 5-7

  PYVMS - Python on OpenVMS -General Manual                       PAGE 5
  table of contents


  CHAPTER 6       configuration guidelines

          6.1     Introduction . . . . . . . . . . . . . . . . . . . 6-1
          6.2     builtin modules  . . . . . . . . . . . . . . . . . 6-1
          6.2.1     format of CONFIG.DAT . . . . . . . . . . . . . . 6-2
          6.3     module methods . . . . . . . . . . . . . . . . . . 6-3
          6.3.1     format of mod__METHODS.DAT . . . . . . . . . . . 6-5


  CHAPTER 7       embedding the Python interpreter


  CHAPTER 8       changes to Python modules

          8.1     compileall . . . . . . . . . . . . . . . . . . . . 8-1
          8.2     tempfile . . . . . . . . . . . . . . . . . . . . . 8-1
          8.3     test_support . . . . . . . . . . . . . . . . . . . 8-1


  CHAPTER 9       Tools

          9.1     coming with PYVMS  . . . . . . . . . . . . . . . . 9-1
          9.1.1     CVT_DOC - convert .HTML to final docu formats  . 9-1
          9.1.2     CVT__HTML - convert .HTML to .RNO  . . . . . . . 9-2
          9.1.3     CVT__RNO - convert .RNO to final docu  . . . . . 9-3
          9.1.4     FILE_SET_DATE - alter CDT and RDT  . . . . . . . 9-4
          9.1.5     HTML2RNO.PY - convert .HTML to .RNO  . . . . . . 9-5
          9.1.6     UNTAR2DATESET - create procedure to change dates 9-8
          9.1.7     VMSDEF2MAR - convert a VMSDEF .DAT file to macro 9-9
          9.1.8     VMSDEF_BLDDIR2MAR - build VMSDEF directory . .  9-10
          9.1.9     VMSVER2MAR - build VMS version table . . . . .  9-11
          9.2     not delivered with PYVMS . . . . . . . . . . . .  9-12
          9.2.1     GZIP - (de)compress files to/from archive  . .  9-12
          9.2.2     UNZIP - decompress files from archive  . . . .  9-12
          9.2.3     VMSTAR - maintain TapeARchive file . . . . . .  9-13


  CHAPTER 10      The history of PYVMS

          10.1    reason for this chapter  . . . . . . . . . . . .  10-1
          10.2    first contact + Python V1.3  . . . . . . . . . .  10-1
          10.3    Python V1.4  . . . . . . . . . . . . . . . . . .  10-1
          10.4    Python V1.5  . . . . . . . . . . . . . . . . . .  10-2
          10.5    Python V1.5.1  . . . . . . . . . . . . . . . . .  10-2
          10.6    Python V1.5.2  . . . . . . . . . . . . . . . . .  10-3


  CHAPTER 11      The future of PYVMS


  CHAPTER 12      Notes

          12.1    PYVMS notes  . . . . . . . . . . . . . . . . . .  12-1
          12.2    the VMSDEF data structures . . . . . . . . . . .  12-6

  PYVMS - Python on OpenVMS -General Manual                       PAGE 6
  table of contents


  INDEX
                                                                 INDEX-1












                                CHAPTER 1

                               Introduction



                        __
                       |  \ |   |       _
                       |__/ |   |  -   / \   -O-
                       |     \ /    \_/   \_/
                       |      |
                                              _
                                |  |  /\/\   / \
                                |  | / || \  \_
                                \  / |    |    \
                                 \/  |    |  \_/



  1.1  Welcome

  Welcome to PYVMS - the Python  programming  language  running  on  the
  OpenVMS operating system.

                      This is the 'GENeral MANual'.

  It contains all sorts of information.  Other documentation is  in  the
  'installation manual' and the 'reference manual'.
  ------------------------------------------------------------------------

  For information  about  Python,  please  refer  to  its  homepage  at:
  http://www.python.org/

  Information about the  OpenVMS  operating  system  can  be  found  at:
  http://www.openvms.digital.com/

  ------------------------------------------------------------------------
  Please note:
  This text is/was originally written in HTML format so it can be viewed
  with  a browser.  The '.HTML' files are also converted by a tool named
  HTML2RNO to '.RNO' files.

  Those are then processed by the  RUNOFF  text-formatter  (which  comes
  with  the  OpenVMS operating system) to produce '.MEM' or '.LNI' files
  which can be printed.  So, some things  may  look  strange  when  this
  documentation is viewed with a browser or read as a text file, but now

  PYVMS - Python on OpenVMS -General Manual                     PAGE 1-2
  Introduction


  you know why.
  ------------------------------------------------------------------------
  PYVMS has been configured with as much builtin  modules  as  possible.
  Here is a list as of 08-JUN-1999:

  >>> print sys.builtin_module_names
  ('__builtin__', '__main__', 'array', 'audioop', 'binascii', 'cPickle',
  'cStringIO', 'cmath', 'errno', 'imageop', 'imp', 'marshal', 'math',
  'md5', 'new', 'operator', 'parser', 'pcre', 'posix', 'pyvms', 'regex',
  'rgbimg', 'rotor', 'select', 'sha', 'signal', 'socket', 'soundex',
  'strop', 'struct', 'sys', 'time', 'timing', 'vms_brkdef',
  'vms_ciadef', 'vms_dcdef', 'vms_dmtdef', 'vms_dvidef', 'vms_fabdef',
  'vms_fscndef', 'vms_initdef', 'vms_jpidef', 'vms_kgbdef', 'vms_lbr',
  'vms_lckdef', 'vms_lib', 'vms_libdtdef', 'vms_lnmdef', 'vms_mail',
  'vms_maildef', 'vms_mntdef', 'vms_namdef', 'vms_ossdef', 'vms_prcdef',
  'vms_prvdef', 'vms_pscandef', 'vms_quidef', 'vms_rabdef',
  'vms_rsdmdef', 'vms_sjcdef', 'vms_statedef', 'vms_sys', 'vms_trmdef',
  'vms_uaidef', 'vms_xaballdef', 'vms_xabfhcdef', 'vms_xabitmdef',
  'vms_xabkeydef', 'vms_xabprodef')

  Beginning with version 1.5.2-V005 the '*vms_lbr*' and the '*vms_mail*'
  modules  are  no  longer  enabled  by  default  -  see 'configuration:
  builtin modules' for details.

  Please note:
  None of the nonVMS-related modules have been thoroughly tested.
  ------------------------------------------------------------------------
  PYVMS consists of the following elements:

        -  the original Python distribution stored in the directory tree
           [PYTHON.PYTHON-1_5_2...]
        -  some files that have been changed for OpenVMS
           e.g.  [.MODULES]TIMEMODULE.C
        -  files that implement the interfaces to OpenVMS routines (e.g.
           VMS_LIB.C).   Look  under  REFMAN  'Modules'  in the table of
           contents.
        -  additional  files   that   implement   /   provide   enhanced
           functionality  that  is  not  available on (some versions of)
           OpenVMS (e.g.  utime() )
        -  a number of data  files  that  describe  VMS  version-related
           information, item codes, bitmasks and constants (VMSD*.DAT)
        -  command  procedures  to  ease  translation  (e.   g.   VMSDEF
           related data files) and compilation
        -  examples and documentation

  I have tried to keep the original directory tree unchanged as much  as
  possible.  Additional files are located in the [.VMS...] sub-tree.

  No changes have been sent back to have them included into the original
  source.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 1-3
  Introduction


  1.2  Version numbers / file names

  The current release of Python on OpenVMS is version  1.5.2-V005.   The
  filenames       -       PYTHON1_5_2.ZIP,       PYVMS1_5_2-V005SRC.ZIP,
  PYVMS1_5_2-V001U4SRC.ZIP, PYVMS1_5_2-V005DOC.TLB -  are  laid  out  as
  follows:

  PYTHON
          The Python distribution.
          Note that the Python documentation is separate.

  PYVMS
          'Python on OpenVMS'

  1_5_2
          The port is based on Python version 1.5.2.

  V005
          OpenVMS port - version 5.  It will be incremented for each new
          release.   If  the  Python version increments (e.g.  to 1.5.3)
          then the version number of the next OpenVMS port will reset to
          V001 again.
  V001U4
          OpenVMS port - a kit that contains updates  from  version  001
          (002 and 003) to 004.

  DOC
          This file contains pre-build PYVMS documentation.

          A documentation kit (the ".TLB" file) is always complete.

  SRC
          The PYVMS PYVMS source kit.  Documentation is embedded in HTML
          format.   You can first build Python and then convert the HTML
          to other formats - see chapter 'installing +  building  PYVMS'
          in the 'installation manual'.

  OBJ_arch
          This file contains precompiled objects.
          arch can be 'ALPHA' or 'VAX'.

  Download sources are listed in the installation manual.

  ------------------------------------------------------------------------

  As of 21-AUG-1999 'PYVMS' is still a  'hobby'  project  of  mine  (Uwe
  Zessin) which I do for my own pleasure in my spare time.

  ------------------------------------------------------------------------
  21-AUG-1999 ZE.












                                CHAPTER 2

                              Documentation



  2.1  access to PYVMS documentation

  Documentation for PYVMS is available in a  number  of  formats.   This
  chapter describes various methods to access them.
  ------------------------------------------------------------------------
  The original source is written as a number of '.HTML' files which  you
  can  find  in the [.VMS.DOC...] subdirectory tree of the distribution.
  You have several options to access them:


        -  If you run a web-server yourself, then you  can  include  the
           files there.  You only need to extract all '.HTML' and '.GIF'
           files from the [.VMS.DOC] subdirectory.
           As of 19-AUG-1998 I am aware of the  following  two  freeware
           HTTP servers, which run on the OpenVMS operating system:

            o  the 'OSU DECthreads HTTP server' is available at:
               http://ecr6s1.eng.ohio-state.edu/www/doc/serverinfo.html
               or
               ftp://kcgl23.eng.ohio-state.edu/

            o  the 'WASD HTTP Server Package' is available at:
               http://www.vsm.com.au:8000/
               or
               ftp:/ftp.vsm.com.au/wasd/
               or
               ftp://ftp.vms.stacken.kth.se/mirrors/vsm/wasd/

           Other freeware and commercial servers are available, too, but
           I don't have any information about them.

        -  You can access the files directly from your web-browser like:
           $! define a foreign command
           $ NETSCAPE == "$disk:[directory]NETSCAPE.EXE"
           $ NETSCAPE -
             file://localhost/DKA100/PYTHON/PYTHON-1_5_2/VMS/DOC/DOCU.HTML


  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -General Manual                     PAGE 2-2
  access to PYVMS documentation


  As of 27-APR-1998 I am aware of  the  following  browsers,  which  are
  available for the OpenVMS operating system:


        -  NETSCAPE  for  OpenVMS  is  available  from  Compaq  Computer
           Corporation (which merged with Digital Equipment Corporation)
           and can be  used  if  you  have  a  valid  DECwindows/  Motif
           license.   It  is  part  of  the  'Internet Product Suite for
           OpenVMS'.  The URL is:
           http://www.openvms.digital.com/openvms/products/ips/

        -  LYNX is a text-only browser that allows reading  the  '.HTML'
           files from an ASCII terminal.  Please start from:
           http://lynx.browser.org/

           Currently, the documentation does not  contain  any  pictures
           (except  for  the  PYVMS Logo), so you will not miss anything
           important.

        -  MOSAIC is included with some versions of  DECwindows  /Motif.
           Different  versions  of  MOSAIC are also available from other
           sources, but I do not have any information.

  ------------------------------------------------------------------------
  I have created a simple converter (written in Python)  named  HTML2RNO
  that  is  able to convert the '.HTML' files into RUNOFF format ('.RNO'
  files).  RUNOFF, also known as DSR - Digital  Standard  Runoff,  is  a
  text-formatter that is supplied with the OpenVMS operating system.

  It converts the '.RNO' files to a '.MEM' file for line-printer  output
  or  a  '.LNI' file for printers understanding ANSI format.  I have not
  tried to include much '.test page nn' hints into the '.HTML' files  to
  help  RUNOFF make a better looking documentation - the page breaks are
  sometimes located at very 'unfortunate' positions...

  A simple set of EDT commands converts the '.MEM' file to a '.TXT' file
  which  is  for  reading the text with a text editor.  They just delete
  the '<CR><LF>' sequences and remove any lines for bold printing.
  The  file  TXT.FDL  is  used  to  change  the  record  attributes   of
  PYVMSDOC.TXT.
  ------------------------------------------------------------------------
  04-JUN-1999 ZE.



  2.2  conventions used in the documentation

  The documentation for PYVMS uses a number of conventions:

  The printed documentation (files '*.MEM' or '*.LNI*) contain  a  table
  of contents and an index that are generated by RUNOFF.

  Some lines (commands or output messages) which  are  too  long  for  a
  single  line  are  manually  wrapped.  This is indicated by a trailing

  PYVMS - Python on OpenVMS -General Manual                     PAGE 2-3
  conventions used in the documentation


  backslash ().  Here is an example:

  UAF> add /identifier ID_1 /attributes=resource
  %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights\
   database                                                         ^
                                                                    |


  The HTML version which you can read with a browser has both  a  simple
  table of contents and an index, which are manually maintained.
  ------------------------------------------------------------------------
  You very likely  have  found  out  already  that  the  documention  is
  scattered  with lots of dates.  They indicate the last time a specific
  chapter, page, or paragraph has been modified or a  specific  sentence
  stating a fact has been checked.
  ------------------------------------------------------------------------
  If you read the documentation from a browser you will  see  that  some
  pages  have  LOTS  of hypertext links.  They should help you to easily
  switch between the information.
  ------------------------------------------------------------------------
  Places where information is missing or perhaps  incorrect  are  marked
  with '@@'.
  ------------------------------------------------------------------------
  08-FEB-1999 ZE.












                                CHAPTER 3

                                 Patches



  3.1  Patches to OpenVMS

  This section describes which Patches  to  OpenVMS  might  have  to  be
  applied.



  3.1.1  Patches are available from:

  http://www.service.digital.com/

  A search machine is available at:
  http://search.service.digital.com/



  3.1.2  Patches commented:

  3.1.2.1  VAXACRT11_061

  There is a bug in some versions of  the  C  RTL.   The  value  of  the
  environment  name "TERM", obtained by calling the getenv function, can
  return a wrong value like this:

  >>> import posix
  >>> print posix.environ['USER']
  ZESSIN
  >>> print posix.environ['TERM']
  USER=ZESSIN
  >>>

  This is supposed to be fixed in the VAXACRT01_061 (and later) kits.  I
  had  installed  VAXACRT11_061  which  applies to OpenVMS VAX Versions:
  V5.5-2, V5.5-2H4, V5.5-2HF, V6.0, V6.1 and the bug has disappeared.

  >>> import posix
  >>> print posix.environ['TERM']
  vt300-80
  >>>


  PYVMS - Python on OpenVMS -General Manual                     PAGE 3-2
  patches to Python and OpenVMS


  Relinking  of  Python  was  _not_  necessary.    Please   check   your
  environment.

  It looks OK on OpenVMS Alpha V6.2-1H3 + V7.1, but  there  are  patches
  (named ALPACRTxx_xxx) for these DEC C RTL versions available, too.



  3.2  Patches to Python

  This section explains which patches to Python itself are available  at
  the  time  of  maintaining  this  page and which have been applied for
  PYVMS.

  When PYVMS version 1.5.2-V001 was released no patches did exist.
  18-APR-1999 ZE.



  3.3  how patching is/was done on OpenVMS

  I used the NETSCAPE browser (see 'access to PYVMS  documentation'  for
  details)  on  OpenVMS  to  download the patches from the URL mentioned
  above.

  Here is an example:

  $! -- create a temporary 'work' directory
  $ SET DEFAULT DKA100:[PYTHON.PYTHON-1_5_1.VMS.PATCHES.WRK]
  $ CREATE /DIRECTORY []
  $!
  $! -- now download the patches and store them in this directory.
  $!
  $ DIRECTORY

  Directory DKA100:[PYTHON.PYTHON-1_5_1.VMS.PATCHES.WRK]

  STROPMODULE-1.TXT;1

  Total of 1 file.

  $! -- find out where the file(s) to be patched are located:
  $ SEARCH STROPMODULE-1.TXT;1 "RCS file:"
  RCS file: /projects/cvsroot/python/dist/src/Modules/stropmodule.c,v
  $! -> it's in the [.MODULES] directory -----!!!!!!!
  $!
  $! -- make a backup copy of the file (optional)
  $ BACKUP [---.MODULES]STROPMODULE.C [---.MODULES]*.C$P -
    /BY_OWNER=ORIGINAL
  $!
  $! -- copy the file into the 'working' directory
  $ COPY [---.MODULES]STROPMODULE.C []
  $!
  $! -- OpenVMS POSIX provides the PATCH utility

  PYVMS - Python on OpenVMS -General Manual                     PAGE 3-3
  patches to Python and OpenVMS


  $ POSIX
  $# posix prompt
  $patch < stropmodule-1.txt
  Hmm...  Looks like a new-style context diff to me...
  The text leading up to this was:
  --------------------------
  |Index: Modules/stropmodule.c
  |===================================================================
  |RCS file: /projects/cvsroot/python/dist/src/Modules/stropmodule.c,v
  |retrieving revision 2.48
  |diff -c -r2.48 stropmodule.c
  |*** stropmodule.c      1998/05/22 00:53:47     2.48
  |--- stropmodule.c      1998/07/25 04:23:01
  --------------------------
  Patching file stropmodule.c using Plan A...
  Hunk #1 succeeded at 694 (offset -2 lines).
  done
  $exit
  $! -- back at DCL-prompt
  $!
  $! -- define foreign command for the FILE_SET_DATE utility
  $ FSD == "$DKA100:[PYTHON.PYTHON-1_5_1.VMS.TOOLS]FILE_SET_DATE_VAX.EXE"
  $!
  $! -- find out 'correct' date and time from the patch-file
  $ SEARCH STROPMODULE-1.TXT "stropmodule.c"
  Index: Modules/stropmodule.c
  RCS file: /projects/cvsroot/python/dist/src/Modules/stropmodule.c,v
  diff -c -r2.48 stropmodule.c
  *** stropmodule.c       1998/05/22 00:53:47     2.48
  --- stropmodule.c       1998/07/25 04:23:01
  $! -------------------> !!!!!!!!!!!!!!!!!!!
  $!
  $! -- set date and time of the patched file to that in the patch
  $ FSD STROPMODULE.C "25-JUL-1998 04:23:01.00"
  $! -> don't forget these --------------> !!!
  $!
  $! -- move the patched file back into the Python-area
  $ RENAME STROPMODULE.C [---.MODULES]*.*;0
  $!
  $! -- move the patch file to the [.VMS.PATCHES] directory
  $ RENAME STROPMODULE-1.TXT [-]
  $!
  $! -- move to [.VMS]
  $ SET DEFAULT [--]
  $!
  $! -- compile the patched module
  $ @DCC_MODULES STROPMODULE
  $ @PCC_MODULES STROPMODULE
  $!
  $! -- create new executables
  $ @LINKD_PY
  $ @LINKP_PY


  PYVMS - Python on OpenVMS -General Manual                     PAGE 3-4
  patches to Python and OpenVMS


  The following tasks are necessary to keep the documentation in sync:


        -  This chapter needs to be updated for each  patch  applied  at
           several locations:
            o  The copy of the patch page which describes the patches.
            o  Comments about the patches - how they are related to  the
               OpenVMS port.
        -  The 'install + building PYVMS' chapter in  the  'installation
           manual'  needs  to be enhanced to include the BACKUP commands
           for any files never being patched before.
        -  The procedure [PYTHON.TOOLS]BUILD_DIST_SRC.COM  needs  to  be
           enhanced to copy the patched file, too.

  ------------------------------------------------------------------------
  02-MAY-1999 ZE.












                                CHAPTER 4

                    Python in the OpenVMS environment



  This section explains how Python works  in  the  OpenVMS  environment.
  See also the 'programming guidelines' chapter.



  4.1  path support

  Python uses several 'environment variables' which tell the  executable
  where the other files (so called libraries) are located.

  Most of the work is done in the file GETPATH.C.  On OpenVMS, a heavily
  modified version is stored in VMS__GETPATH.C.

  The original version of GETPATH.C uses the path to the executable  for
  further  lookup.   This  code  has  been  removed from VMS__GETPATH.C.
  Several  attempts  are  made  to   find   special   'landmark'   files
  ("string.py") - this code as been removed, too.

  Two directories are needed:

  prefix
          This directory contains the platform independent common  '.py'
          and '.pyc' files.

          A symbol or logical name "PYTHON_LIBRARY" is checked  for  the
          prefix.   Python's  'sys'  module  will contain a string named
          'prefix'.  Its value will also be appended to  the  'path'  as
          shown  below.   Note:  the file specification must be in POSIX
          notation as shown below.  (Currently,) you  cannot  specify  a
          list of file specifications (e.g.:  "/spec1:/spec2").

          $ define PYTHON_LIBRARY "/DKA100/PYTHON/PYTHON-1_5_2/LIB"
          $ python
          Python 1.5.2 (V005a, Sat Aug 21 15:21:10 1999) [DECC] on vms
          Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
          portions Copyright 1996-1999 Uwe Zessin
          >>> print sys.prefix
          /DKA100/PYTHON/PYTHON-1_5_2/LIB
          >>>

  PYVMS - Python on OpenVMS -General Manual                     PAGE 4-2
  Python in the OpenVMS environment



          >>> for path in sys.path:
          ...   print path
          ...

          /DKA100/PYTHON/PYTHON-1_5_2/LIB
          /DKA100/PYTHON/PYTHON-1_5_2/VMS/TOOLS
          /DKA100/PYTHON/PYTHON-1_5_1/LIB         <-- PYTHON_LIBRARY appended
          >>>

  exec_prefix
          This directory contains platform dependent files -  so  called
          shared   library   modules,  which  are  similar  to  OpenVMS'
          shareable  images.   They  are  used  to  dynamically   loaded
          additional  modules.   There  is  currently  (21-AUG-1999)  no
          support for this.

          A symbol or logical name "PYTHON_SHARE"  is  checked  for  the
          exec_prefix.   Python's  'sys'  module  will  contain a string
          named 'exec_prefix'.  Its value is currently (21-AUG-1999) NOT
          appended to 'sys.path'.


  ------------------------------------------------------------------------
  @@ explain PYTHONPATH ...
  ------------------------------------------------------------------------



  4.2  command line editing

  The DCL environment uses an  enhanced  readline  function  located  in
  PYVMS_READLINE.C  that  uses the SMG$ routines for editing and command
  history.  Module 'pyvms' allows access to readline history.  The POSIX
  environment    still    uses    the    Python-supplied    routine   in
  [.PARSER]MYREADLINE.C
  ------------------------------------------------------------------------



  4.3  dynamic loading

  On a Unix operation system this means, quoted from:
  ftp://ftp.cwi.nl/pub/dynload/dl.txt

  'Dynamic loading:  adding object code to the text segment of a running
  process, with the purpose -- usually -- of executing instructions from
  it' ...

  On OpenVMS it is not possible to  load  object  code  this  way.   One
  might,  instead,  put a module in a shareable image.  The interpreter,
  however is not linked against it, so it is not loaded at startup.  The
  shareable image is only activated when the module is being imported.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 4-3
  Python in the OpenVMS environment


  21-AUG-1999
  Some work has  been  done,  but  it  did  not  made  it  into  version
  1.5.2-V005.

  I don't believe that makes much sense unless the module is _very_  big
  and not used often.  The minimum page size of an Alpha processor is at
  least 8 KBytes and I think you would need at least  several  pages  if
  you map a shareable image via LIB$FIND_IMAGE_SYMBOL()

  Note:     module    'vms_lib'     provides     an     interface     to
  LIB$FIND_IMAGE_SYMBOL()  to  look  up  a  symbol  value in a shareable
  image, but there is currently (21-AUG-1999) no way to call  a  routine
  in this image.
  ------------------------------------------------------------------------



  4.4  embedding Python on OpenVMS

  Some comments in  an  earlier  version  of  this  manual  raised  some
  confusion.

  The idea was to put all routines in a shareable image to save space if
  multiple  variants  were  build.  As mentioned above, some experiments
  have been done, but it's not ready for release.

  There  is  nothing  in  the  implementation  that  tries  to   prevent
  embedding.   With  version 1.5.2-V005 a simple demo has been created -
  see the 'embedding' chapter.
  ------------------------------------------------------------------------
  21-AUG-1999 ZE.












                                CHAPTER 5

                          programming guidelines



  This  section  gives  some  guidelines  how  to  use  the  programming
  interface to OpenVMS routines.



  5.1  functions

  5.1.1  arguments

  Some functions (e.  g.:  vms_lib.currency) do not have any  arguments.
  If you provide any, then the programming interface WILL raise a Python
  exception.  The redundant argument is not silently ignored!

  Some arguments of a function might not apply in a specific  situation.
  As  keyword  arguments  are  not implemented you have to insert 'None'
  instead.  See the examples of vms_lib.day() or vms_lib.getdvi() to get
  an idea.

  OpenVMS system services usually require ALL  arguments  be  specified.
  The Python interface routines usually substitute 'None' with '0 passed
  by value' to indicate an omitted argument.  They also  allow  trailing
  'unused' arguments to be omitted.



  5.1.2  keyword arguments

  e.g.:  >>> ret = routine (p1 = val1)
  are not supported for OpenVMS interface routines.



  5.1.3  functions returning no data

  Some  routines  do  not   need   to   return   any   'data'   -   e.g.
  vms_lib.attach()  returns  'None'  upon  successful completion.  If an
  error happens, they will still raise a Python exception.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 5-2
  programming guidelines


  5.1.4  functions returning dictionaries

  Some routines like  'vms_sys.getjpiw()'  need  to  return  a  variable
  amount  of  data  depending  on its input parameters (the item list in
  this  case).   The  data  is  stored  under  different  'keys'  in   a
  dictionary.

  Using a tuple or a list would raise the  question  of  which  data  is
  stored at which position.



  5.2  OpenVMS condition values

  Using the native interfaces a programmer  should  _always_  check  the
  returned   condition  value.   Some  routines  also  use  the  OpenVMS
  condition mechanism to signal errors, but a programmer should not rely
  on it.

  Almost all routines within Python do not return the 'status' code from
  the  underlying OpenVMS service.  They use the Python model of raising
  a Python exception when an error happens.

  There  are   some   routines   which   behave   differently   -   e.g.
  vms_lib.set_logical().   The  reason  for  this  is a uniform style of
  returning data - in this case  it  is  a  dictionary.   Routines  with
  different  status  values  that  can  indicate success do not raise an
  exception, too.

  The vms_sys.getmsg() routine allows the translation of the  code  into
  its text message:

      >>> import vms_sys
      >>> print vms_sys.getmsg(0x2c)
      ('%SYSTEM-F-ABORT, abort', (0, 0, 0, 0))
      >>>

  See the 'reference manual' for details.



  5.3  special OpenVMS datatypes

  Python on OpenVMS does not have a builtin 64-bit or 128-bit datatype.



  5.3.1  64-bit quadword

  These are usually simulated by using Python's "long integer" datatype.
  See  vms_sys.gettim()  or vms_sys.asctim() for examples.  An exception
  are quadwords that are used  for  rightslist  identifiers  -  see  the
  explanation more below this text.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 5-3
  programming guidelines


  Using a "long integer" does allow the programmer  to  do  calculations
  within Python.  See the next section.

  Date and time values are returned as a signed  long  integer,  however
  bitmasks like privileges are returned as an unsigned long integer.



  5.3.1.1  date and time calculations

  An OpenVMS binary date + time is internally represented  by  a  signed
  quadword.  A positive value (including 0) indicates an absolute date +
  time (e.g.  29-FEB-2000 12:34:45.78).  A negative value means a  delta
  time  (12  21:56:34.91),  meaning 12 days, twenty-one hours, fifty-six
  minutes, thirty-four seconds and 91 hundredth of a second.

  Although an OpenVMS 'delta time' is represented by a negative value it
  does  not have a "direction".  If you see something like "+01:00:00" -
  this is a 'combination time' - it means "add one hour to  the  current
  date + time".

  Let's do some examples:

      >>> import vms_lib, vms_sys

  If you are like me and always forget VMS' base date:

      >>> vms_sys.asctim (0L)
      '17-NOV-1858 00:00:00.00'
      >>>

  The smallest increment is 100 nanoseconds.  It's easy to find out  how
  many of these 'ticks' are in a second:

      >>> vms_sys.bintim ('17-NOV-1858 00:00:01.00')
      10000000L
      >>>

  Warning!  The trailing 'L' shows that this is a Python 'long integer'.
  This  is  not  a delta-time!  '10000000L' really indicates the 17th of
  November in the year 1858, one second after midnight.

  Now, a one-second delta time:

      >>> vms_sys.bintim ('0 00:00:01.00')
      -10000000L
      >>>


  Let's use a different date:

      >>> feb29_y2k = vms_sys.bintim ('29-FEB-2000 12:34:56.78')
      >>> feb29_y2k
      44585444967800000L

  PYVMS - Python on OpenVMS -General Manual                     PAGE 5-4
  programming guidelines


      >>>


  Calculate one second.

      >>> one_second = vms_sys.bintim ('0 00:00:01.00')
      >>> one_second
      -10000000L
      >>>


  To add one second, we have to subtract the delta-time:

      >>> new_time = feb29_y2k - one_second
      >>> new_time
      44585444977800000L
      >>> vms_sys.asctim (new_time)
      '29-FEB-2000 12:34:57.78'
                          *
      >>> print new_time - feb29_y2k
      10000000L
      >>>


  Remember:  this value does NOT represent a one-second 'delta-time'!


  There are also OpenVMS RTL routines to do date + time calculations:

      >>> new_time_2 = vms_lib.add_times (feb29_y2k, one_second)
      >>> new_time_2
      44585444977800000L
      >>> vms_sys.asctim (new_time_2)
      '29-FEB-2000 12:34:57.78'
                          *
      >>>


  This routine, however, has  some  restrictions.   Please  see  'REFMAN
  Modules, vms_lib module, vms_lib.add_times' for details.

  To subtract a delta time from an absolute date + time  using  Python's
  long  integer  datatype you have to ADD both values.  There is also an
  OpenVMS RTL routine for this - see 'REFMAN  Modules,  vms_lib  module,
  vms_lib.sub_times()'.



  5.3.2  128-bit octaword

  These are simulated by using Python's "long  integer"  datatype.   See
  vms_sys.getutc() or vms_sys.ascutc() for examples.

  Using a "long integer" does allow the programmer  to  do  calculations

  PYVMS - Python on OpenVMS -General Manual                     PAGE 5-5
  programming guidelines


  within Python.



  5.4  processes

  5.4.1  privileges

  A Python on OpenVMS executable is  not  meant  to  be  installed  (via
  $INSTALL)  with  any  privileges!   It  is  possible to turn off these
  elevated privileges by a call to vms_sys.setprv (),  but  a  user  can
  always just '$RUN' the Python executable...
  The user can also enable additional  privileges  from  his  authorized
  privilege mask or turn on any privilege if he has the SETPRV privilege
  by calling vms_sys.setprv().

                                   ---

  Privilege bitmask values are stored in module 'vms_prvdef'.  @@ Ignore
  the  'PRV$_NULL'  item  code in this module.  It is a work-around to a
  deficy in the VMSDEF2MAR.COM procedure  which  currently  cannot  cope
  with a VMSDEF module that has no item codes.

  A  privilege  bitmask  is  64  bits  wide.   All  bit  definitions  in
  'vms_prvdef' are defined as Python long integers.

  >>> import vms_prvdef
  >>>
  >>> # a bit in the first longword
  >>> vms_prvdef.PRV_M_ALLSPOOL
  16L
  >>> type (vms_prvdef.PRV_M_ALLSPOOL)
  <type 'long int'>
  >>>
  >>> # a bit in the second longword
  >>> hex (vms_prvdef.PRV_M_READALL)
  '0x800000000L'
  >>> type (vms_prvdef.PRV_M_READALL)
  <type 'long int'>
  >>>


  Since 14-FEB-1999 it is no longer necessary to  convert  the  bitmasks
  from  a  Python  integer  (32-bit)  to  a Python long integer (64-bit)
  because a BITMASK64 structure has  been  implemented.   The  following
  bits  are still defined in the 'vms_prvdef' module with their (32-bit)
  values in the second longword:

  PRV_M2_UPGRADE,   PRV_M2_DOWNGRADE,   PRV_M2_GRPPRV,   PRV_M2_READALL,
  PRV_M2_IMPORT, PRV_M2_AUDIT, PRV_M2_SECURITY.
  (_M2_ indicates that this bit is located in the 2nd longword.)

  'vms_prvdef' also includes the bits with the '_M_' code and their real
  64-bit value.  See the example of PRV_M_READALL above.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 5-6
  programming guidelines


  Privileges  are  used,  for  example,  in  the   following   routines:
  vms_lib.getjpi(),         vms_sys.creprc(),         vms_sys.getjpiw(),
  vms_sys.getuai(), vms_sys.process_scan() and vms_sys.setuai().



  5.4.2  process identification (PID)

  OpenVMS DCL utilities use an  8-character  hex  number  as  input  and
  output for the PID and translate it internally because system services
  and run-time library routines use a binary longword.

  Within Python on OpenVMS a PID must always be specified as an  integer
  data type - it is never a hex-string.  e.g.:

  $ PID = F$GETJPI(0,"PID")
  $ show symbol PID
  PID = "0000021A"
  $ NUMBER = %X'PID'
  $ show symbol NUMBER
  NUMBER = 538 Hex = 0000021A Octal = 00000001032
  $

  You have to use the number '538' within Python.

  >>> ctx,data = vms_lib.getjpi("JPI$_IMAGNAME",538)
  >>> print data
  DKA100:[PYTHON.PYTHON-1_5_1.VMS]PYTHON_ALPHA.EXE;1
  >>>

  ('ctx' is either the process'  PID  or,  during  wildcard  lookups,  a
  context  value.   Please  see  the description of vms_lib.getjpi() for
  details.)

  Several system  services  (SYS$DELPRC,  SYS$FORCEX,  ...)  return  the
  target  process'  PID  if  you  specifiy  0 for the PID argument and a
  process name.

  For  consistency  the  Python  interface  always  returns  the  target
  process'  PID  -  no  matter if you specify an explicit PID or use the
  process name argument.

                                   ---
  Almost all examples in this documentation use a 'low'  value  for  the
  PID.   This  is  because  development happens on non-clustered OpenVMS
  systems.



  5.4.3  rightslist identifiers

  Identifiers (UIC and general) and their attributes are represented  as
  Python integers (32-bit values).  The 'vms_kgbdef' module contains the
  attribute bitmask values (KGB_M_name).   Translation  to  /  from  the

  PYVMS - Python on OpenVMS -General Manual                     PAGE 5-7
  programming guidelines


  names  can  be  done using the vms_sys.asctoid() and vms_sys.idtoasc()
  routines.

  Some system services  like  vms_sys.add_holder()  require  a  quadword
  containing  the identifier in one of the longwords.  The other usually
  is used for the attributes.  In this case the  interface  routines  do
  not use a single Python long integer but a tuple of 2 integers.



  5.5  security related objects

  5.5.1  ACL + ACE

  An ACL (Access Control List) is made up from one or more ACEs  (Access
  Control list Entries).  They are stored inside normal Python strings.

  Warning!
  ACEs are a set of bytes, not  a  set  of  printable  characters.   You
  should  not  output  a  binary ACE/ACL to a terminal, because the data
  stream  can  contain  control  sequences  that  alter  the  terminal's
  settings.  Using the 'repr()' builtin is safe:

      >>> print repr (acestr)
      '\014\001\000\000\020\000\000\000\004\000\003\000'
      >>>


  The vms_sys.format_acl() routine accepts a binary ACE  and  translates
  it  in  its ASCII equivalent.  The vms_sys.parse_acl() routine accepts
  an ASCII string and translates it to the binary representation that is
  used inside OpenVMS.

  The vms_sys.get_security() routine and the 'vmsobj_xabpro' object  can
  be used to retrieve ACLs or ACEs from files and other objects (not via
  XABPRO).
  ------------------------------------------------------------------------
  21-AUG-1999 ZE.












                                CHAPTER 6

                         configuration guidelines



  6.1  Introduction

  Beginning with Python on OpenVMS version 1.5.2-V004 it is possible  to
  do  better  customization  when  building  a Python interpreter.  This
  especially helps people which do not have access to a C compiler.

  This section explains how this is to be done.
  ------------------------------------------------------------------------



  6.2  builtin modules

  The list of Python's builtin modules has been historically defined  by
  a 'C' structure in file CONFIG.C.

  Since version 1.5.2-V004 this file has been replaced by  a  data  file
  (CONFIG.DAT).  This are the steps:

        -  Edit CONFIG.DAT - the format is described more below.

        -  Use the procedure CONFIG_INITTAB2MAR.COM to convert this file
           to  an  assembler source file and create an additional linker
           options file (CONFIG.OPT).

        -  Run procedure DMACRO_VMS.COM to create an object  file.   The
           object   module   is   not   put   into  the  object  library
           VMS_MACRO.OLB!  This  allows  easier  creation  of  different
           versions of the interpreter or embedding.

        -  Create the executable by running the  procedure  LINKD_PY.COM
           that calls the OpenVMS linker.

  Example:

      $ edit CONFIG.DAT
        ...
      $ @ CONFIG_INITTAB2MAR.COM  CONFIG.DAT  "D"
      $ directory CONFIG;


  PYVMS - Python on OpenVMS -General Manual                     PAGE 6-2
  configuration: builtin modules


      Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

      CONFIG.C_;1         CONFIG.DAT;2

      Total of 2 files.
      $

      $ @ DMACRO_VMS CONFIG_INITTAB
      %DMACRO-I-MODULE, compiling module CONFIG_INITTAB
      $ directory CONFIG*;

      Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

      CONFIG.C_;1         CONFIG.DAT;2        CONFIG.OPT;1
      CONFIG_INITTAB.MAR;1                    CONFIG_INITTAB2MAR.COM;2

      Total of 5 files.
      $

      $ @ LINKD_PY
      ----------------------------------------------------------------
      %LINKD_PY-I-LINKPRG, linking program PYTHON_VAX.EXE
      $

      $ directory PYTHON_*.EXE;

      Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

      PYTHON_VAX.EXE;1

      Total of 1 file.
      $

  The file 'CONFIG.C' is no longer used and can  be  deleted  after  its
  contents have been merged with those of CONFIG.DAT.



  6.2.1  format of CONFIG.DAT

  A comment is started by the "!" character.  It must be in column 1  on
  a comment-only line.

  A ";" in column 1 is also treated as a  comment,  however  the  entire
  line  is  also  copied to the output '.MAR' file where it is used as a
  comment as well.


  column 1
          The module name as seen inside Python.
          Mixed case is allowed.  One or more SPACE  characters  delimit
          this column from the next one.

  column 2

  PYVMS - Python on OpenVMS -General Manual                     PAGE 6-3
  configuration: builtin modules


          Name of the initialization  routine  for  this  module.   Some
          internal  routines  have 'NULL' here, which is translated to a
          NULL pointer.
          Mixed case is allowed, but is currently not used  on  OpenVMS.
          One or more SPACE characters delimit this column from the next
          one.

  column 3
          configuration indicator
          This is validated  against  input  parameter  2  to  procedure
          CONFIG_INITTAB2MAR.COM.   The "D" means "DCL environment", the
          "P" means "POSIX" environment, "T" is for  threading  support.
          ALL characters must be specified together as parameter 2.

          E.  g.:  for threading support  in  the  DCL  environment  the
          following call has to be done:

              $ @ CONFIG_INITTAB2MAR.COM  CONFIG.DAT  "DT"
            

  column 4
          linker option
          Data from this column goes into file "CONFIG.OPT".  Look for a
          column that contains the string "zlib" as an example.

          There must not be a SPACE character in this column!

  The list is terminated by a line containing '0 0'.

  21-JUL-1999 ZE.
  ------------------------------------------------------------------------



  6.3  module methods

  The list of a modules' methods is usually defined by a  'C'  structure
  within the 'C' souce file of the module.

  Beginning version 1.5.2-V004  this  table  _can_  be  replaced  by  an
  external  data  file  per module.  To date, only the following modules
  have been changed:

        -  vms_lib
        -  vms_sys


  These modules have been the prime target in order to support  multiple
  operation system versions, because newer ones provide additional calls
  which result in LINK errors, at minimum.  Adaption  of  other  modules
  (if that is wanted) should be easy by taking them as an example.

  Maintenance:

  PYVMS - Python on OpenVMS -General Manual                     PAGE 6-4
  configuration: module methods


        -  Edit file 'mod__METHODS.DAT' - the format is  described  more
           below.
        -  Use the procedure MODULEMETHODS2MAR.COM to convert this  file
           to an assembler source file.
        -  Run procedure DMACRO_VMS.COM to create an object file and put
           it into the object library VMS_MACRO.OLB.
        -  Create the executable by running the  procedure  LINKD_PY.COM
           that calls the OpenVMS linker.

  Example:

      $ edit VMS_SYS__METHODS.DAT
        ...
      $ @ MODULEMETHODS2MAR  VMS_SYS__METHODS.DAT  "."  "."
      $ directory VMS_SYS__METHODS;

      Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

      VMS_SYS__METHODS.DAT;2

      Total of 1 file.
      $

      $ @ DMACRO_VMS  VMS_SYS__METHODS
      %DMACRO-I-MODULE, compiling module VMS_SYS__METHODS
      $ directory VMS_SYS__METHODS;

      Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

      VMS_SYS__METHODS.DAT;2                 VMS_SYS__METHODS.MAR;2

      Total of 2 files.
      $

      $ @ LINKD_PY
      ----------------------------------------------------------------
      %LINKD_PY-I-LINKPRG, linking program PYTHON_VAX.EXE
      $

      $ directory PYTHON_*.EXE;

      Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

      PYTHON_VAX.EXE;1

      Total of 1 file.
      $


  PYVMS - Python on OpenVMS -General Manual                     PAGE 6-5
  configuration: module methods


  6.3.1  format of mod__METHODS.DAT

  A comment is started by the "!" character.  It must be in column 1  on
  a comment-only line.
  A ";" in column 1 is also treated as a  comment,  however  the  entire
  line  is  also  copied to the output '.MAR' file where it is used as a
  comment as well.

  A line that begins with 'LABEL=' defines the name of that table.  This
  name  is  used  by  the  module's  initialization routine when calling
  'Py_InitModule4()' - Please lookup the  string  'vms_lib__methods'  in
  file 'VMS_LIB.C' to see how this works.

  All remaining lines define a module's methods -  their  layout  is  as
  follows:


  column 1
          The method name as seen inside Python.
          Mixed case is allowed.  One or more SPACE  characters  delimit
          this column from the next one.

  column 2
          Name of the method's routine - usually a 'C'-function.
          Mixed case is allowed, but is currently not used  on  OpenVMS.
          One or more SPACE characters delimit this column from the next
          one.

  column 3
          Method-Flags
          "MV" indicates "METH_VARARGS" - no other values are  currently
          implemented.   Mixed  case  is not allowed.  One or more SPACE
          characters delimit this column from the next one.

  column 4
          DOC-String label
          Address of a documentation string that will be attached to the
          method.   This  is  a  zero-terminated string, that is usually
          defined like:

              char meth__doc [] = "v = meth (p1, p2)\nshort description.";

          Mixed case is allowed, but is currently not used  on  OpenVMS.
          One or more SPACE characters delimit this column from the next
          one.

  column 5
          VAX/Alpha version
          The earliest version number for the VAX or Alpha  architecture
          where this method is supported.  This is usually only used for
          operation system interfaces  -  other  modules  will  use  the
          standard mechanism.


  PYVMS - Python on OpenVMS -General Manual                     PAGE 6-6
  configuration: module methods


  There is no explicit termination indicator  required  /  supported  in
  this file.

  11-JUL-1999 ZE.
  ------------------------------------------------------------------------
  11-JUL-1999 ZE.  (introduction)












                                CHAPTER 7

                     embedding the Python interpreter



  The  Python  distribution  contains  an  embedding  example   in   the
  [.DEMO.EMBED]  directory.   This  has been copied to [.VMS.DEMO.EMBED]
  and adapted for the OpenVMS environment.

  This section gives some more hints.

  ------------------------------------------------------------------------

  Comments about some files:

  BUILD_DEMO.COM
          This file contains code copied and updated from  [.VMS]DCC.COM
          and LINKD_PY.COM.  It is used to turn DEMO.C into DEMO_VAX.EXE
          or DEMO_ALPHA.EXE.

  DEMO.C
          Copied from [.DEMO.EMBED].

  DEMO_DCL_VAX.MAP or DEMO_DCL_ALPHA.MAP
          Map file from the link process.

  DEMO_VAX.EXE or DEMO_ALPHA.EXE
          Resulting executables.

  DEMO_VAX.OBJ or DEMO_ALPHA.OBJ


  The demo is linked  against  the  full  interpreter  and  all  of  its
  extension modules which creates a big '.EXE' file!

  If this isn't wanted then it is possible to copy  [.VMS]CONFIG.DAT  to
  [.VMS.DEMO.EMBED]  and  modify  it.   The  new object module should be
  stored here, too.

  Finally, BUILD_DEMO.COM need  be  updated  to  link  against  the  new
  version of CONFIG_INITTAB.OBJ.
  ------------------------------------------------------------------------
  19-AUG-1999 ZE.












                                CHAPTER 8

                        changes to Python modules



  This section explains changes to modules of the  Python  library  that
  have been made to support OpenVMS.

        -  compileall.py
        -  tempfile.py
        -  test_support




  8.1  compileall

  is used to pre-compile all modules of the Python library.

  The  default  OpenVMS  filesystem  (ODS-2)  supports  only   uppercase
  filenames.  The modification makes the module compliant.

  This module is used during the installation.   See  the  'installation
  manual', 'installing + building PYVMS', 'compile Python files'.



  8.2  tempfile

  is used to create 'temporary' filenames and  possibly  open  temporary
  files.

  The module was using an invalid filename character ("@").

  The  'TemporaryFileWrapper'  class  uses   a   construct   (os.open(),
  os.unlink()) that does not work on OpenVMS.  The port pretends to be a
  'POSIX' environment, so the appropriate check fails.   The  check  has
  been removed - the required piece of code is directly executed.



  8.3  test_support

  is used for some regression tests.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 8-2
  changes to Python modules


  The module was using an invalid filename character ("@").

  ------------------------------------------------------------------------
  21-AUG-1999 ZE.












                                CHAPTER 9

                                  Tools



  9.1  coming with PYVMS

  9.1.1  CVT_DOC - convert .HTML to final docu formats

  This procedure is used to convert  all  '.HTML'  files  to  the  final
  documentation formats:

  '.LNI'
          This file is  for  ANSI  printer  output.   Bold  printing  is
          controlled using ANSI sequences.
  '.MEM'
          This file is  for  line  printer  output.   Bold  printing  is
          controlled via carriage control and double printing.

          It is then converted to:
  '.TXT'
          This file is for  viewing  with  a  text  editor  or  printing
          without bold characters from a non-VMS system.

  CVT_DOC.COM calls the following procedures:

  CVT__HTML.COM
          convert '.HTML' files to '.RNO' files
  CVT__RNO.COM
          convert '.RNO' files to the final 3 files explained above.

  Conversion from HTML to RUNOFF can take some time on a  slow  machine.
  One can run CVT__HTML.COM parallel to an edit session and have all new
  files converted while editing a new  one.   CVT__HTML.COM  will  check
  creation  dates  and  only  convert  new  HTML  files.  After the last
  '.HTML' file was  changed  the  programmer  can  run  CVT_DOC.COM  and
  conversion will only be done for files where it is necessary.

  Format:

      $ @CVT_DOC ["*"]

  Arguments:

  P1, optional

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-2
  CVT_DOC - convert .HTML to final docu formats


          An asterisk ("*") is passed to CVT__HTML.COM  and  means  that
          all  files  will  be  translated  whether  the  '.RNO' file is
          current or not.


  ------------------------------------------------------------------------
  06-APR-1999 ZE.



  9.1.2  CVT__HTML - convert .HTML to .RNO

  CVT__HTML.COM is normally called from CVT_DOC.COM.   It  converts  all
  '.HTML' files in the [.VMS.DOC.] subdirectories except for those which
  have the '<RNO  NOCONVERT>'  tag  in  the  first  line.   Because  the
  conversion  process  takes  some  time CVT__HTML.COM does only convert
  those '.HTML'  files  which  have  a  later  creation  date  than  the
  corresponding '.RNO' file.

  Passing a "*" as parameter 1  to  the  procedure  however  means  that
  CVT__HTML  will  ignore the dates on the files and translate all files
  (except those that use the <RUN NOCONVERT> tag mentioned above).

  Beginning with version 1.5.2-V002 it is also  possible  to  specify  a
  filename  as  parameter  1 to convert a single file - no matter if the
  ".RNO" file is up to date or not.

  One can also delete all versions of a  '.RNO'  file  to  force  a  new
  translation of the '.HTML' file.

  It requires a working Python executable (named [.VMS]PYTHON_arch.EXE),
  the  procedure  SETUP.COM  and HTML2RNO.PY.  ('arch' can be "ALPHA" or
  "VAX").

  The procedure contains only minimal error checking - e.  g.  it  fails
  on an empty '.HTML' file.

  Format:

      $ @CVT__HTML ["*"|"filespec"]

  Arguments:

  P1, optional
          An asterisk ("*") means that  all  files  will  be  translated
          whether the '.RNO' file is current or not.

          A single filespecification (.HTML)  is  set  automatically  to
          translate this file only.


  Example:

  $ @CVT__HTML

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-3
  CVT__HTML - convert .HTML to .RNO


  %CVT__HTML-I-CVTFIL, converting file
   \DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]BUILDING.HTML;97\
  %CVT__HTML-I-NOCVT, converting not necessary for file
   \DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]CVT__HTML.HTML;1\
  %CVT__HTML-I-NOCVT, converting not necessary for file
   \DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]DOC_ACCESS.HTML;18\
  [...]
  %CVT__HTML-I-NOCVT, converting not necessary for file
   \DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]HTML2RNO.HTML;13\
  %CVT__HTML-W-CVTREJ, file conversion rejected due to <RNO NOCONVERT>
   \DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]IDX.HTML;32\
  %CVT__HTML-I-NOCVT, converting not necessary for file
  [...]
  %CVT__HTML-I-NOCVT, converting not necessary for file
   \DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]VMS_SYS.HTML;66\
  %CVT__HTML-I-CVTCNT, converted 1 files
  $

  $! .HTML is always set v--
  $ @CVT__HTML INSBLD.HTMX
  %CVT__HTML-I-CVTFIL, converting file
   \DKA100:[PYTHON.PYTHON-1_5_2.VMS.DOC.INSMAN]INSBLD.HTML\
  %CVT__HTML-I-CVTCNT, converted 1 files
  $

  $! .HTML is always set --------------v
  $ @CVT__HTML [-.REFMAN]VMS_LIB_ATTACH
  %CVT__HTML-I-CVTFIL, converting file
   \DKA100:[PYTHON.PYTHON-1_5_2.VMS.DOC.REFMAN]VMS_LIB_ATTACH.HTML\
  %CVT__HTML-I-CVTCNT, converted 1 files
  $

  ------------------------------------------------------------------------
  11-MAY-1999 ZE.



  9.1.3  CVT__RNO - convert .RNO to final docu

  CVT__RNO.COM is normally called from  CVT_DOC.COM.   It  converts  all
  '.RNO'  files that have been created from a prior run of CVT__HTML.COM
  to the final files ('.MEM', '.LNI',  '.TXT')  for  printer  output  or
  viewing with a text editor.

  Format:

      $ @CVT__RNO

  Arguments:

  none

  Example:


  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-4
  CVT__RNO - convert .RNO to final docu


  $ @CVT__RNO
  %CVT__RNO-I-CREINTMED, creating intermediate file
  %CVT__RNO-I-CRETOC, creating table of contents
  %CVT__RNO-I-CREIDX, creating index
  %CVT__RNO-I-CREMEM, creating final .MEM file
  %CVT__RNO-I-CVTTXT, converting .MEM to .TXT file
  318 lines deleted
  DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]PYVMSDOC-TXT.TMP;1 7276 lines
  Input file does not have standard text file format
  [EOB]
  %CVT__RNO-I-CRELNI, creating final .LNI file
  7 lines deleted
  DKA100:[PYTHON.PYTHON-1_5.VMS.DOC]PYVMSDOC.LNI;34 7414 lines
  [EOB]
  %CVT__RNO-I-DONE, RNO translation completed
  $


  Beginning with PYVMS V1.5.1-V008 there are several  manuals  and  each
  has a dedicated procedure.
  ------------------------------------------------------------------------
  27-MAR-1999 ZE.



  9.1.4  FILE_SET_DATE - alter CDT and RDT

  The FILE_SET_DATE program changes the creation + revision  date  of  a
  file.

  It is used when the VMSTAR program did not preserve the dates from the
  '.TAR'  file  or  a  '$  SET  FILE'  command has been done to Python's
  original files.  UNTAR2DATESET.COM creates a  command  procedure  that
  uses FILE_SET_DATE to change the creation + revision dates.

  Format:

      $! define a foreign command
      $ FILE_SET_DATE = "$disk:[directory.subdir]FILE_SET_DATE"

      $ FILE_SET_DATE  filespecification  date+time

  Arguments:

  filespecification
          Cannot  contain  any  wildcards  or  a   node   name   because
          FILE_SET_DATE does calls to the ACP-QIO interface.
  date+time
          Month names must be in uppercase on some versions of OpenVMS.

          Special warning:  if you ommit the hundreth of  seconds,  they
          are not automatically set to '.00'!

  Example:

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-5
  FILE_SET_DATE - alter CDT and RDT



      $ COPY  _NLA0:  FILE.TMP
      $ DIRECTORY/DATE=(CREATED,MODIFIED) FILE.TMP

      Directory DKA100:[PYTHON.PYTHON-1_5.VMS]

      FILE.TMP;1    21-FEB-1998 20:46:42.65  21-FEB-1998 20:46:44.38

      Total of 1 file.
      $ FILE_SET_DATE  FILE.TMP  "29-FEB-2000 12:34:56.78"
      $ DIRECTORY/DATE=(CREATED,MODIFIED) FILE.TMP

      Directory DKA100:[PYTHON.PYTHON-1_5.VMS]

      FILE.TMP;1    29-FEB-2000 12:34:56.78  29-FEB-2000 12:34:56.78

      Total of 1 file.
      $

  ------------------------------------------------------------------------
  23-MAY-1998 ZE.



  9.1.5  HTML2RNO.PY - convert .HTML to .RNO

  HTML2RNO.PY is a Python program, that is used  to  convert  a  '.HTML'
  file  to a '.RNO' file.  The '.RNO' file is then to be run through the
  RUNOFF text formatter that is  supplied  with  the  OpenVMS  operating
  system.

  HTML2RNO understands several HTML tags and tries to  convert  them  to
  their   RUNOFF   'equivalents'.    There  is,  however  a  fundamental
  difference:

  HTML
          describes the contents and the browser is supposed  to  decide
          how the output is rendered (e.g.  lists).

  RUNOFF
          is a text formatter where  the  user  has  a  high  number  of
          commands available that can be used to control the output.

  ------------------------------------------------------------------------
  The following HTML tags are understood by HTML2RNO which can be mapped
  quite easily to RUNOFF commands:

  <H1> + </H1> through <H6> + </H6>
          are converted to '.header level' commands.

  <PRE> + </PRE>
          is converted to '.literal' and '.end literal'

  <TITLE> + </TITLE>

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-6
  HTML2RNO.PY - convert .HTML to .RNO


          is converted to '.subtitle "title-string"'.
          This intentionally done for the PYVMS documentation.  '.title'
          defines the name of the document.

  <UL> + </UL>
          is converted to  '.list'  and  '.end  list'.   HTML2RNO  tells
          RUNOFF  the  'bullet character' to use.  You can easily change
          that - look at the implementation of start_ul().

  <OL> + </OL>
          is converted to  '.list'  and  '.end  list'.   HTML2RNO  tells
          RUNOFF to prefix the list elements with a decimal number.

  <LI>
          is converted to '.list element' which works with both <UL> and
          <OL>.

  <DL>
          is just translated into a new paragraph

  <DT>
          The left margin is re-established.

  <DD>
          moves the left margin 8 characters to the right.

  </DL>
          is translated into  a  new  paragraph.   The  left  margin  is
          re-established.

  <BR>
          is converted to '.break'

  <HR>
          does a line break.  Then  a  line  containing  dashes  (-)  is
          inserted as literal text into the RUNOFF file.

  <P>
          starts a new line and puts a '.blank' on it.

  <CENTER> + </CENTER>
          is converted to '.center;text-to-center'.

  <STRONG> + </STRONG>
          enables bold  printing  in  RUNOFF  and  inserts  the  control
          characters  for begin or end into the RUNOFF file.  After that
          bold printing is turned off again.

  <EM> + </EM>
          is usually displayed in italics within  a  browser.   HTML2RNO
          tells RUNOFF to underline the embedded text.

  ------------------------------------------------------------------------
  HTML2RNO uses the <RNO> tag to pass additional data to RUNOFF.  As far

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-7
  HTML2RNO.PY - convert .HTML to .RNO


  as I know <RNO> is not a valid HTML tag and browsers should ignore it.
  The  following  'attributes'  (@@  is  that  the  correct  name?)  are
  implemented:

  NOCONVERT
          is used to tell the procedure CVT__HTML.COM that  the  '.HTML'
          file  need  not  be  converted.  This tag must be in the first
          line of the document.

  INLINE="data"
          inserts 'data' directly into the '.RNO' file.

          Example:
          aaa<RNO INLINE="|">bbb
          Such a construct can be used to suggest a possible  line-break
          to  RUNOFF.  I'm not aware that a browser does right-justify a
          paragraph  or  that  HTML  contains  directives  to   indicate
          possible line-break in words.

  INSERT_LITERAL="data"
          inserts 'data' as a separate line into the '.RNO'  file  which
          is included between '.end literal' and '.literal' lines.  This
          prevents unnecessary empty lines from appearing  if  one  uses
          the following technice instead:
          text</PRE><RNO LINE=".test page 4"><PRE>

          Example:
          <PRE>
          text-1
          text-2<RNO INSERT_LITERAL=".test page 4">more-text-1
          more-text-2
          </PRE>

          The resulting output in the '.RNO' file looks like:

          Example:

          : .literal
          : 
          : text-1
          : text-2
          : .end literal
          : .test page 4
          : .literal
          : more-text-1
          : more-text-2
          : 
          : .end literal

          (There are currently superflowous  empty  lines  if  one  uses
          <PRE> and </PRE>.)

  LINE="data"
          inserts 'data' as a separate line into the '.RNO' file.

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-8
  HTML2RNO.PY - convert .HTML to .RNO


          Example:
          <RNO LINE=".test page 10">
          This tells RUNOFF that there must be at least 10 free lines on
          the  current  page.   If  not,  RUNOFF  starts  a new page.  A
          browser has only one huge 'page' and the user scrolls  through
          that page.

  NEWLINE
          just starts a new line in the '.RNO' file.

  ------------------------------------------------------------------------
  A test procedure is  located  in  [.VMS.TEST]HTML2RNO-TEST.COM.   This
  file         converts         [.VMS.TEST]HTML2RNO-TEST.HTML         to
  [.VMS.TMP]HTML2RNO-TEST.RNO with  [.VMS.TOOLS]HTML2RNO.PY.   Then  the
  '.RNO'  file  is converted to a '.MEM' file by running the RUNOFF text
  formatter.

  [.VMS.TEST]HTML2RNO-TEST.HTML should contain a test case for each HTML
  tag that HTML2RNO.PY understands.
  @@ to be enhanced
  ------------------------------------------------------------------------
  28-JUL-1998 ZE.



  9.1.6  UNTAR2DATESET - create procedure to change dates

  Some old versions of the VMSTAR program did not set the  creation  and
  revision  dates  of  extracted file to those in the '.TAR' file.  Even
  with a current version the instructions to  build  Python  on  OpenVMS
  contain a command that changes the revision date of all files.

  The UNTAR2DATESET.COM procedure reads the output of VMSTAR and creates
  a  new  procedure  that  changes  the  creation + revision date of the
  extracted file.  This procedure calls the FILE_SET_DATE program.

  Format:

      $ @UNTAR2DATESET inputfile outputfile

  Arguments:

  inputfile
          This is the file that  contains  the  verbose  output  of  the
          VMSTAR program.
  outputfile
          UNTAR2DATESET.COM creates this file  which  is  later  run  to
          change the extracted files' dates.

  Example:

      $! redirect output of VMSTAR
      $ DEFINE/USER_MODE SYS$OUTPUT name-UNTAR.LOG
      $! extract files from the TAR file

  PYVMS - Python on OpenVMS -General Manual                     PAGE 9-9
  UNTAR2DATESET - create procedure to change dates


      $ VMSTAR xvf name.TAR
      $! read the output file and create command procedure
      $ @UNTAR2DATESET name-UNTAR.LOG name-DATESET.COM
      $! run the created procedure
      $ @name-DATESET.COM/OUTPUT=name-DATESET.LOG
      $! search for any errors
      $ SEARCH name-DATESET.LOG "%" /WINDOW=(1,4)

  ------------------------------------------------------------------------
  17-MAR-1998 ZE.



  9.1.7  VMSDEF2MAR - convert a VMSDEF .DAT file to macro

  On OpenVMS definitions of item codes, bitmasks or constants are stored
  in  several  modules.   E.g.   for 'Device and Volume Information' the
  module name is '$DVIDEF'.

  Python on OpenVMS uses a similar construct that I call 'VMSDEF'.

  On OpenVMS there exist  different  files  for  each  language  -  e.g.
  DVIDEF.H  or DVIDEF.PAS (Caution!  some compilers store these files in
  a text library, now!).

  My first  release  of  Python  on  OpenVMS  (PYVMS_970216)  did  store
  item-codes  (and  some  more  information  that  is not available in a
  native xxxDEF module of OpenVMS) in a  number  of  '.C'  source  files
  building huge arrays.

  This data, with some more information, has been moved into a number of
  text   files   with  names  like  VMSDEF_$DVIDEF.DAT.   The  procedure
  VMSDEF2MAR.COM translates the DAT file to the file  VMSDEF_$DVIDEF.MAR
  which  is  then run through the macro assembler by using the following
  command:
      $ @DMACRO_VMS VMSDEF_$DVIDEF.MAR

  The resulting object file (VMSDEF_$DVIDEF.OBJ) is put into the  object
  library  in  [.VMS.O_architecture]VMS_MACRO.OLB.   ('architecture'  is
  either 'ALPHA' or 'VAX').

  Look in the  table  of  contents  under  'Notes  about  implementation
  details' to see a sketch of the 'VMSDEF data structures'
  ------------------------------------------------------------------------

  Format:

      $ @VMSDEF2MAR inputfile

  Arguments:

  inputfile
          Text file that contains the VMSDEF  information.   The  output
          file  is  stored  in  the  same directory with the same name -

  PYVMS - Python on OpenVMS -General Manual                    PAGE 9-10
  VMSDEF2MAR - convert a VMSDEF .DAT file to macro


          except that the file type is '.MAR'.

  Example:

      $ @VMSDEF2MAR VMSDEF_$DVIDEF.DAT
      $ directory VMSDEF_$DVIDEF.*;

      Directory DKA100:[PYTHON.PYTHON-1_5.VMS]

      VMSDEF_$DVIDEF.DAT;1        VMSDEF_$DVIDEF.MAR;1

      Total of 2 files.

  ------------------------------------------------------------------------
  27-DEC-1998 ZE.



  9.1.8  VMSDEF_BLDDIR2MAR - build VMSDEF directory

  The pyvms module provides access to all details of the  'VMSDEF'  data
  structures.   The DCL procedure VMSDEF_BLDDIR2MAR.COM creates the file
  VMSDEF_DIRECTORY.MAR that contains a list of all existing structures.

  That file is then  run  through  the  macro  assembler  by  using  the
  following command:
      $ @DMACRO_VMS VMSDEF_DIRECTORY.MAR

  The resulting object  file  (VMSDEF_DIRECTORY.OBJ)  is  put  into  the
  object library in [.VMS.O_architecture]VMS_MACRO.OLB.  ('architecture'
  is either 'ALPHA' or 'VAX').

  How to access this data is described in the Examples  section  of  the
  pyvms module documentation.

  Look in the  table  of  contents  under  'Notes  about  implementation
  details' to see a sketch of the 'VMSDEF data structures'
  ------------------------------------------------------------------------

  Format:

      $ @VMSDEF_BLDDIR2MAR

  Arguments:
      This procedure does not have any arguments.

  Example:

      $ @VMSDEF_BLDDIR2MAR
      $ directory VMSDEF_DIRECTORY.MAR

      Directory DKA100:[PYTHON.PYTHON-1_5.VMS]

      VMSDEF_DIRECTORY.MAR;1

  PYVMS - Python on OpenVMS -General Manual                    PAGE 9-11
  VMSDEF_BLDDIR2MAR - build VMSDEF directory



      Total of 1 file.

  ------------------------------------------------------------------------
  30-APR-1998 ZE.



  9.1.9  VMSVER2MAR - build VMS version table

  A single executable image of 'Python on OpenVMS' provides support  for
  multiple  versions  of  OpenVMS.   The 'VMSDEF' tables, which describe
  item-codes, bitmasks and constants have a minimum and maximum  version
  number encoded.
  @@ more explanation necessary?

  The DCL procedure VMSVER2MAR.COM converts the  file  VMSDAT_VMSVER.DAT
  to  the  file  VMSDAT_VMSVER.MAR  which  is then run through the macro
  assembler by using the following command:
      $ @DMACRO_VMS VMSDAT_VMSVER.MAR

  The resulting object file (VMSDAT_VMSVER.OBJ) is put into  the  object
  library  in  [.VMS.O_architecture]VMS_MACRO.OLB.   ('architecture'  is
  either 'ALPHA' or 'VAX').

  Access to the  data  of  this  list  is  currently  (07-MAR-1998)  not
  implemented,    however   the   pyvms   module   provides   the   item
  'vms_version_number'.  Please  read  the  module's  documentation  for
  details.

  Look in the  table  of  contents  under  'Notes  about  implementation
  details' to see a sketch of the 'VMSDEF data structures'
  ------------------------------------------------------------------------

  Format:

      $ @VMSVER2MAR inputfile

  Arguments:

  inputfile
          Text file that contains the version information.

  Example:

      $ @VMSVER2MAR VMSDAT_VMSVER.DAT
      $ directory VMSDAT_VMSVER.DAT,VMSDAT_VMSVER.MAR

      Directory DKA100:[PYTHON.PYTHON-1_5.VMS]

      VMSDAT_VMSVER.DAT;1 VMSDAT_VMSVER.MAR;1

      Total of 2 files.


  PYVMS - Python on OpenVMS -General Manual                    PAGE 9-12
  VMSVER2MAR - build VMS version table


  ------------------------------------------------------------------------
  07-MAR-1998 ZE.



  9.2  not delivered with PYVMS

  9.2.1  GZIP - (de)compress files to/from archive

  The GZIP program is required to  decompress  the  '.GZ'  file  of  the
  original  Python  distribution.   You  also need the VMSTAR program to
  extract the files from the '.TAR' file.

  This page only gives some sources where to get  GZIP  -  it  does  not
  explain  the  program!   Please read the documentation that comes with
  GZIP.
  ------------------------------------------------------------------------
  GZIP is available from several sources:

        -  the OpenVMS freeware CD
        -  DECUS SIG tapes
        -  FTP servers

           I have found sources at:
           ftp://ftp.wku.edu/vms/fileserv/gzip-1-2-4.zip

           To extract  the  files  from  the  '.ZIP'  archive,  you  can
           download UNZIP from:
           ftp://ftp.wku.edu/vms/unzip.alpha_exe for Alpha or
           ftp://ftp.wku.edu/vms/unzip.exe for VAX.

           Remember to do a 'binary' download on all these files!

  ------------------------------------------------------------------------
  04-JUN-1998 ZE.



  9.2.2  UNZIP - decompress files from archive

  The UNZIP program  is  required  to  decompress  '.ZIP'  files.   This
  program is capable to restore RMS file attributes (e.g.  indexed) when
  files are restored on an OpenVMS system.

  This page only gives some sources where to get UNZIP  -  it  does  not
  explain  the  program!   Please read the documentation that comes with
  UNZIP.
  ------------------------------------------------------------------------
  UNZIP is available from several sources:


  PYVMS - Python on OpenVMS -General Manual                    PAGE 9-13
  UNZIP - decompress files from archive


        -  the OpenVMS freeware CD
        -  DECUS SIG tapes
        -  FTP servers

           I have found executables at:
            o  For VAX:
               ftp://ftp.wku.edu/vms/unzip.exe
            o  For Alpha:
               ftp://ftp.wku.edu/vms/unzip.alpha_exe

  I cannot point you to source kits at the  moment,  however  you  might
  want to check:  ftp://ftp.wku.edu/vms/fileserv/
  ------------------------------------------------------------------------
  04-JUN-1998 ZE.



  9.2.3  VMSTAR - maintain TapeARchive file

  The VMSTAR program is required to extract all files  of  the  original
  Python  distribution  from  the  '.TAR'  file.  Because the archive is
  delivered in a compressed form you  also  need  the  GZIP  program  to
  extract the '.TAR' file from it.

  This page only gives some sources where to get VMSTAR -  it  does  not
  explain  the  program!   Please read the documentation that comes with
  VMSTAR.
  ------------------------------------------------------------------------
  VMSTAR is available from several sources:

        -  the OpenVMS freeware CD
        -  DECUS SIG tapes
        -  FTP servers

           I have found sources at:
           ftp://ftp.wku.edu/vms/fileserv/vmstar.zip
           When I did a download on 24-MAY-1998 it was version 3.3-9.

           To extract  the  files  from  the  '.ZIP'  archive,  you  can
           download UNZIP from:
           ftp://ftp.wku.edu/vms/unzip.alpha_exe for Alpha or
           ftp://ftp.wku.edu/vms/unzip.exe for VAX.

           Remember to do a 'binary' download on all these files!

  ------------------------------------------------------------------------
  26-MAY-1998 ZE.












                                CHAPTER 10

                           The history of PYVMS



  10.1  reason for this chapter

  I always enjoy  reading  about  the  history  of  a  program  package.
  Python's  history is described in the file [.MISC]HISTORY.  If you are
  interested in the history of Python on OpenVMS, then read on.



  10.2  first contact + Python V1.3

  I first heard about Python when  reading  issue  3/96  of  the  German
  'LINUX MAGAZIN' (http://www.linux-magazin.de).  Then I found out about
  the port of Python V1.2 to VMS from Donn Cave, enhanced  and  upgraded
  it to Python V1.3 (released on 13 October 1995) which was available at
  that time.

  It took quite some work to get  it  running  with  DEC  C  and  GNU  C
  (problems with function prototypes and LINK).  A lot of functions were
  missing in POSIXMODULE.



  10.3  Python V1.4

  Python V1.4 was released on 25 October 1996.  I've ported one  or  two
  1.4betas  and  was  happy  that  I  had  to make less changes from one
  version to the other.  I stopped any work with GNU C about that time.

  This was  the  first  version  which  I've  released  under  the  name
  'PYVMS_970216'.  The number suggests the date of 16 February 1997.

  I've continued working with Python on OpenVMS  about  5  month  later.
  No, it wasn't a burn-out...

                                   ---

  I've invested some time to provide additional routines like utime() or
  readdir() which are missing on older VMS versions.  Item-code handling
  has been changed totally from arrays in 'C' source files  (*_TRNTBL.C)
  to  data files (VMSDEF_*.DAT) that are translated to macro sources (by

  PYVMS - Python on OpenVMS -General Manual                    PAGE 10-2
  PYVMS - history


  VMSDEF2MAR.COM) and then run through the  MACRO  assembler  (with  the
  help of DMACRO_VMS.COM).

  A lot of routines to the  runtime  library  (LIB$,  LBR$)  and  system
  services  (SYS$)  have  been  added.   Please  note that some of these
  routines are not available in VMS  V5.5-2  or  6.0.   The  oldest  VMS
  releases I work with are OpenVMS VAX V6.1 and OpenVMS Alpha V6.2-1H3.
  When running under DCL, Python provides  a  (simple)  command  history
  that  has been implemented using the screen management library (SMG$).
  Note that Python is still line-oriented!

  The compile procedures have been somewhat enhanced - one can supply  a
  single file name as parameter_1 - I still don't use a make utility.



  10.4  Python V1.5

  I've moved the port to the beta releases of Python  V1.5  and  finally
  V1.5 which was released on 31 December 1997.  It took some time to get
  around the prefix handling.  Well,  I  still  have  no  VMS  compliant
  solution  -  I  just  created  2  dummy files in 2 directories to keep
  Python quiet and left it at that for the moment.

  Next I've started working with  callback-routines  while  implementing
  vms_lbr.output_help()      and      item-lists      while      writing
  vms_lib.set_logical().  It is amazing what one can do with Python!

  In the midth of January 1998 I've began moving the documentation  from
  a  set  of  simple  text files into HTML format.  Conversion to '.TXT'
  files was done with a (modified) Python  program  I've  found  in  the
  article  of  the  German  'LINUX  MAGAZIN',  that  got me started with
  Python.
  Great, eh?

  After some tests I've decided to change/ enhance the program to create
  output in RUNOFF format.  RUNOFF - aka DSR - Digital Standard Runoff -
  is a text formatter  that  is  supplied  with  the  OpenVMS  operating
  system.  The conversion program is now named HTML2RNO.



  10.5  Python V1.5.1

  Python V1.5.1 was released on 14-APR-1998.  I have moved the  port  to
  that  version  some  days  later and had applied almost all subsequent
  patches.  Some work has been  done  to  attack  the  'prefix  problem'
  (changed GETPATH.C), but it's not finished.

  Since then I have put  a  lot  of  work  into  the  documentation  and
  additional DCL routines to support the maintenance.

  The first snapshot (V1.5.1 V001P1) was put up on my private home  page
  on www.decus.de at ??-MAY-1998.

  PYVMS - Python on OpenVMS -General Manual                    PAGE 10-3
  PYVMS - history


  The second snapshot (V1.5.1 V001P2) was put up on my private home page
  on www.decus.de at 30-JUL-1998.

  The third snapshot (V1.5.1 V001P3) was released on  20-AUG-1998.   The
  quadword   support  is  provided  by  using  Python's  "long  integer"
  datatype.

  The fifth snapshot (V1.5.1 V001P5) has never been officially released.

  The fourth snapshot (V1.5.1 V001P4) was released on 04-OCT-1998.

  The sixth snapshot (V1.5.1 V001P6) was released on 27-DEC-1998.

  The seventh snapshot (V1.5.1  V001P7)  was  released  on  17-JAN-1999.
  Octawords  are  represented as Python long integers, too.  The code of
  the interfaces has been cleaned up heavily.

  A set of 'VMS objects' has been created during JAN/MAR-1999  and  some
  RMS  calls  have  been implemented.  The first successfull SYS$GET was
  done on 11-FEB-1999.  During that  time  the  documentation  has  been
  split into 3 manuals.

  Version 1.5.1-V008 was released on 27/28-MAR-1999.
  Version 1.5.1-V009 (an update to V008) was released on 08-APR-1999.



  10.6  Python V1.5.2

  Version  1.5.2-V001  was  released   on   10-MAY-1999.    The   Python
  distribution  is available in a repackaged format to make installation
  easier.  Documentation is now in the following 3 manuals:

        -  installation
        -  general
        -  reference


  Version 1.5.2-V002 was released on 16-MAY-1999.
  Version 1.5.2-V003 was released on 13-JUN-1999.
  Version 1.5.2-V004 was released on 11-JUL-1999.
  Version 1.5.2-V005 was released on 24-AUG-1999.

  ------------------------------------------------------------------------
  24-AUG-1999 ZE.












                                CHAPTER 11

                           The future of PYVMS



  What is planned / needs to be done for/in a future version of PYVMS:
  ------------------------------------------------------------------------
  Currently, everything is running from the 'development directory tree'
  ([PYTHON...]).   Access  to  the  library  is  just 'hacked to make it
  work'.  Multi-platform support (Alpha / VAX) is unclear.

  What needs to be done is:

        -  definition of a directory tree for a production environment
        -  multi-platform support (within a mixed architecture (Alpha  /
           VAX) and / or mixed version VMScluster) for:
            o  python code (similar to [.LIB.PLAT-xxx]
            o  executables + shareable images
           within the directory tree mentioned above.


  Some work has already been done  by  creating  a  special  version  of
  GETPATH.C in [.VMS]VMS__GETPATH.C.
  ------------------------------------------------------------------------
  Changes to the development environment so that users can make  use  of
  the   building  instructions  without  privileges.   The  'development
  directory tree' ([PYTHON...]) should be  able  to  live  in  a  user's
  subdirectory.
  ------------------------------------------------------------------------
  Better navigation between web pages:
  It should be possible to go directly from one page to  the  other  (or
  the previous one) without returning to the table of contents.
  26-DEC-1998 - Work has been started some time ago by  using  a  single
  HTML  page  for each interface routine for the 'vms_lib' and 'vms_sys'
  modules.
  ------------------------------------------------------------------------
  A set of tests for OpenVMS specific extensions should be developed.

  There are always enhancements / changes to already  existing  routines
  and data structures which can break old functions (and the DID it).
  ------------------------------------------------------------------------
  Some implementations of gmtime() in the  OpenVMS  C  run-time  library
  return  NULL  (to indicate they do not support timezones) which Python
  (in [.MODULES]TIMEMODULE.C) cannot cope  with.   A  workaround  is  in
  VMS__GMTIME.C which, however, returns just the local time.

  PYVMS - Python on OpenVMS -General Manual                    PAGE 11-2
  future


  ------------------------------------------------------------------------
  07-APR-1999 ZE.












                                CHAPTER 12

                                  Notes



  This chapter contains some notes about implementation details.



  12.1  PYVMS notes

  This section contains comments and ideas ...
  (Conversion from PYVMS_NOTES.TXT which was last updated on 26-JAN-1998
  ZE.)
  ------------------------------------------------------------------------
  Changes/additions since last release (PYVMS_970216) are marked with  a
  vertical  bar  (  ) in the leftmost column.  Some information has been
  move from this file to other, better suited places.

  ------------------------------------------------------------------------
    - compilers
      - DEC C: tested on OpenVMS Alpha and VAX
          OpenVMS VAX   V6.1     + DEC C V5.0-003
          OpenVMS Alpha V6.2-1H3 + DEC C 5.2-003
          OpenVMS Alpha V7.1     + DEC C V5.6-003

      - GNU C: my port for Python V1.3 did include 'support' for GCC
        (on VAX)
          This port does not contain any changes for files of the
          original python distribution.
          Files from my distribution contain artifacts for GCC 'support',
          but they are NOT up to date!
          I have tried to maintain the usage of shell$... vs decc$...
          compatible for people who want to try GCC or VAX C.

      - VAX C: no work done (has been replaced by DEC C anyway)

      - C++  : I have not tried any C++ compiler

      All DCC_*.COM procedures have been enhanced to allow compilation
      of a single module. E.g.:
      $ @DCC_VMS     VMSMODULE
      $ @DCC_MODULES IMAGEOP
      All PCC_*.COM procedures have been enhanced as well.
      Because PCC_VMS.COM must call DCC.COM and not all object files

  PYVMS - Python on OpenVMS -General Manual                    PAGE 12-2
  PYVMS notes


      are included they have become a bit messy... Watch out!
   
      DCC_VMS.COM allows chaining to the link procedure - please check
      the text inside this file.

    - control-c handling
      I _think_ this port uses the default handler of the C RTL with
      SIGNALMODULE when running in the POSIX environment. Python for
      DCL uses SMG$READ_COMPOSED_LINE.

    - curses
      cursesmodule does not compile with the VMS Versions (Alpha V6.2-1H3
      and VAX V6.1) that I had available. I've thought about a port of
      'ncurses' but it contains lots of UNIX specials and my time is
      limited. Perhaps this works better with a new version of VMS (V7.0
      and up) - there has been a lot of work for 'UNIX compatibility'.
      Still nothing done.

    - file names support
      well, that's a problem...
      VMS and UNIX filespecifications are quite different.
      There is some experimental code in [.VMS]POSIXMODULE.C,
      but I haven't come to a decision what to do. Lots of code uses UNIX
      type filespecifications (e.g. "abc.def.ghi" or "/tmp/@test") which
      cannot be handled directly in the DCL environment. It's even a
      problem when running in the POSIX environment but the file should
      be created in VMS' native file system.
      28-MAY-1998 - an extension to the ODS-2 filesystem (named ODS-5) is
      underway and planned for OpenVMS Alpha V7.2 which will have better
      support for unix-like filenames.
      OpenVMS Alpha V7.2 being delivered since JAN 1999 - no tests done, yet.
  |   Added interfaces for DECC$TO_VMS() and DECC$FROM_VMS() to the
  |   'pyvms' module.

    - file types, usage in this project
      .OBJ = object module for DCL environment  (DEC C)
      .OLB = object library for DCL environment (DEC C)
      .GBJ = object module for DCL environment  (GNU C) ! not currently
      .GLB = object library for DCL environment (GNU C) !  in use
      .O   = object module for POSIX environment
      .A   = object library for POSIX environment

    - gettimeofday() is usually provided by vms__gettimeofday(),
      (in VMS__GETTIMEOFDAY.C) because only very new versions of VMS +
      DEC C have it implemented.
      It's still not available in POSIX on VMS V7.1 / DECC V5.6.

    - gmtime() is superceeded by vms__gmtime() (in VMS__GMTIME.C) which
      should give a better emulation of gmtime() although it still returns
      the current time. The routine in the C library just returns NULL
      (meaning no support) which Python cannot cope with.

    - installation
      The current version of the VMS port is 'development/experimental'.

  PYVMS - Python on OpenVMS -General Manual                    PAGE 12-3
  PYVMS notes


      No code changes have been submitted back, yet.
   
      On Unix, parts of the distribution tree are copied to other directories
      (e.g. below /usr/local or other). I do feel very uncomfortable copying
      files to SYS$LIBRARY:! Currently I keep everything in the [PYTHON...]
      tree.
   
      The module search path is calculated in [.MODULES]GETPATH.C -
      perhaps one should create a VMS-specific version...
      08-MAY-1998: some work has begun on VMS__GETPATH.C but is NOT finished.

    - item codes
      They are passed as strings. (e.g: vms_lib.getsyi("SYI$_VERSION",0))
      to the function which looks up the numerical value. This version of
      Python on VMS does no longer put names like 'SYI__VERSION' into the
      dictionary of a module. Only bitmasks and constants remain (e.g.:
      QUI_M_FILE_BURST in vms_quidef). Note that the '$' from QUI$ has
      been replaced by an underscore ('_') because Python does not allow
      dollars, right?
   
      Item codes, bitmask definitions and constants are converted from a
      .DAT file to Macro-source which is further translated to an object
      module. These tables contain the VMS version which first provides
      support for the item. The translation tables of 'C' have almost
      been removed.
   
      Access to this information is possible via the 'pyvms' module.
      See 'the VMSDEF data structures' for details.
   
      There are still some problems with the current format in the .DAT
      file. Expect changes in a future version!

    - octaword (128 bit) support
      Since PYVMS V1.5.1 V001P7 the octaword support is provided by using
      Python's "long integer" datatype.

    - POSIX support
      No attempt has been made to make any calls to RTL and system services
      available for this environment, yet.
      Unfortunately, POSIX for OpenVMS has been killed by DEC!

    - quadword (64 bit) support
      Since PYVMS V1.5.1 V001P3 the quadword support is provided by using
      Python's "long integer" datatype.

      Some work has been started to support OpenVMS Alpha V7.x features,
      but *no* 64-bit adressing is used!

    - rmdir() emulation in the DCL environment (via VMS__RMDIR.C)
      It is not necessary on VMS (because you can just delete the name.DIR;1
      file), but I have tried to mimic the behaviour of rmdir() as
      implemented in VMS_POSIX. Please check VMS__RMDIR.C for details.

    - sys module

  PYVMS - Python on OpenVMS -General Manual                    PAGE 12-4
  PYVMS notes


      - The module is imported from PYTHONSTARTUP.PY and the prompts are
        changed for VMS style output when running under DCL.
      - sys.executable (=argv[0])
        This path is turned into Unix notation from PyVMS_init() when
        running under DCL.

    - TCL/TK
      Some code contains references to TCL/TK. I did some tests with a
      previous Python port and a (now) outdated version of TCL/TK. The
      URL was:    http://www.rsmas.miami.edu/vms-tcl.html
      I don't have any newer information and haven't done any work with
      Python V1.4 (or later) together with any version of TCL/TK.
      28-MAY-1998 - I've got a report back from one person who has tried
      the preview of V1.5.1 V001P1 with a newer port of TCL. Well, a
      little test did succeed...

    - threads
  |   VMS supports threads since version V5.5, but several procedures in
  |   the [.VMS] directory are very likely _NOT_ thread-save !!
  |   A small test to enable threading was done on 21-DEC-1998, but this
  |   is disabled by default - check CONFIG.H

    - utime() emulation in the DCL environment (via VMS__UTIME.C). Of
      course, the 'access time' cannot be changed because files in an
      ODS-2 file system don't have such a thing.

    - VMS vs OpenVMS
      copied from the OpenVMS FAQ:
   ------------------------------------------------------------

  VMS2.  What is the difference between VMS and OpenVMS?

  VMS  and  OpenVMS  are  two  names  for  the  same  operating  system.
  Originally,  the operating system was called VAX-11/VMS; it changed to
  VAX/VMS at around VAX/VMS V2.0.  When the  VMS  operating  system  was
  ported to the Alpha platform, it was renamed OpenVMS, for both VAX and
  Alpha, in part to signify the high  degree  of  support  for  industry
  standards such as POSIX, which provides many features of UNIX systems.
  An OpenVMS license allows you to install and run POSIX for OpenVMS  at
  no  additional  charge;  all  you  need is the media and documentation
  which can be  found  on  the  Consolidated  Distribution  and  On-Line
  Documentation  CD-ROMs.   For  more  information  on POSIX for VMS see
  question SOFT2.

  What became confusing is that the OpenVMS name  was  introduced  first
  for OpenVMS AXP V1.0 causing the widespread misimpression that OpenVMS
  was for Alpha AXP only, while "regular VMS" was  for  VAX.   In  fact,
  Digital  officially changed the name of the VAX operating system as of
  V5.5, though the name did not start to be actually used in the product
  until V6.0.

  The proper names for OpenVMS on the two  platforms  are  now  "OpenVMS
  VAX" and "OpenVMS Alpha", the latter having superseded "OpenVMS AXP".

  PYVMS - Python on OpenVMS -General Manual                    PAGE 12-5
  PYVMS notes


  This FAQ is archived in the following locations:
          comp.answers and news.answers newsgroups
          ftp://ftp.digital.com/pub/Digital/dec-faq/vms
          ftp://rtfm.mit.edu/pub/usenet/news.answers/dec-faq/vms
          CompuServe VAXFORUM, Library 0, VMSFAQ.TXT

  User-created HTML versions of the FAQ are located at:
          http://www.kjsl.com/vmsfaq
          http://eisner.decus.org/vms/faq.htm


   ------------------------------------------------------------

    - 'VMS objects'
      No work has been done to create a 'process' object or a 'queue' object.
      13-MAR-1999 - Objects have been create to be able to use RMS features,
      see 'VMS Objects - list.

    - [.VMS] directory tree structure
   
      [.VMS] - additional code and support files
        [.DEMO] - examples
        [.DOC]          - documentation about PYVMS
                             (and some support DCL files)
        [.O_ALPHA]      - object files for the Alpha architecture
        [.O_VAX]        - object files for the VAX architecture
          DCC_*.LOG       - created if DCC_name.COM is called from DCC-ALL.COM
          DMACRO_*.LOG    - created if DMACRO_name.COM is called from "
          PCC_*.LOG       - created if PCC_name.COM is called from PCC-ALL.COM
          file.A          - object library for POSIX environment
                           do not confuse them with the first file from a
                           VMSINSTAL kit which really is a BACKUP save-set
          file.OLB        - object library for dcl environment
          [.MODULES]      - object modules for directories parallel
          [.OBJECTS]      - "                             to [.VMS]
          [.PARSER]       - "
          [.PYTHON]       - "
          [.VMS]          - "
          [.VMS_TOOLS]    - object modules for files in [.VMS.TOOLS]
          
              *.OBJ = compiled with DEC C for DCL
              *.O   = compiled with DEC C for POSIX
   
        [.PATCHES]      - all patches to Python that were available
                          when PYVMS was released
        [.TEST]         - files to test out functions of PYVMS
                          (currently only HTML2RNO)
        [.TMP]          - used while building of PYVMS
        [.TOOLS]        - some tools to maintain and build PYVMS
   

  ------------------------------------------------------------------------
  22-APR-1999 ZE.

  PYVMS - Python on OpenVMS -General Manual                    PAGE 12-6
  the VMSDEF data structures


  12.2  the VMSDEF data structures

  This section shows some of the VMSDEF  data  structures.   (Conversion
  from VMSDEF.TXT which was last updated on 04-JAN-1998 ZE.)

          06-SEP-1996
  data structure changed:
  - c_typ_lib to w_typ_lib and c_typ_sys to w_typ_sys
  - removed filler element
  - moved w_bufsiz to keep natural alignments

  ------------------------------------------------------------------------

  VMSDEF_DIRECTORY.MAR
    -- array of: pointer to item descriptor, pointer to bitmask/constants
        pointer descriptor, pointer to .ASCIZ name of DEFinition

  VMSDEF_GR_DIRECTORY::
      .address VMSDEF_GR_$QUIDEF       ; ar_itmtbl
      .address VMSDEF_GR_CB_$QUIDEF    ; ar_conmsktbl
      .address VMSDEF_T_DIRECTORY__3
      ...
      .long    0 ; terminate list
      .long    0

  VMSDEF_T_DIRECTORY__3:  .asciz '$QUIDEF'
      ...
      ; no termination necessary
  ;
      .end

  ------------------------------------------------------------------------
  VMSDEF_$QUIDEF.MAR
    -- array of item descriptors
  VMSDEF_GR_$QUIDEF::
      .word    0001                ; w_itmcod - QUI$_CANCEL_OPERATION
      .word    00000               ; w_bufsiz
      .word    05520               ; w_vmsvermin
      .word    32767               ; w_vmsvermax
      .address VMSDEF_T_$QUIDEF__1 ; at_itmnam_py
      .long    0                   ; ar_bitmsk
      .long    7                   ; l_flags
      .word    ITMTYP_K_LONG       ; w_typ_lib
      .word    ITMTYP_K_LONG       ; w_typ_sys
      ...
      .word    0133                ; w_itmcod - QUI$_MANAGER_STATUS
      .word    00004               ; w_bufsiz
      .word    06000               ; w_vmsvermin
      .word    32767               ; w_vmsvermax
      .address VMSDEF_T_$QUIDEF__75 ; at_itmnam_py
      .address VMSDEF_AR_QUI_QUEUE_MGR        ; ar_bitmsk
      .long    11                  ; l_flags
      .word    ITMTYP_K_LONG       ; w_typ_lib
      .word    ITMTYP_K_LONG       ; w_typ_sys

  PYVMS - Python on OpenVMS -General Manual                    PAGE 12-7
  the VMSDEF data structures


      ...
      .word     0       ; w_itmcod - end of list
      .word     0       ; w_bufsiz
      .word     0       ; w_vmsvermin
      .word     0       ; w_vmsvermax


    -- array of bitmask/constant descriptors for a given item code
        (if applicable)
  VMSDEF_AR_QUI_QUEUE_MGR:
      .long    0008   ; QUI_M_MANAGER_FAILOVER
      .address VMSDEF_T_$QUIDEF__250
      .word    05520
      .word    32767
      .long    0004   ; QUI_M_MANAGER_RUNNING
      .address VMSDEF_T_$QUIDEF__251
      .word    05520
      .word    32767
      ...
      .long    0
      .long    0
      .word    0      ; THIS 0 terminates the BITMASK list
      .word    0


    -- array of bitmask/constants pointer descriptor
       (pointer to descriptor amd defines it's type)
  VMSDEF_GR_CB_$QUIDEF::
      .address VMSDEF_AR_QUI_QUEUE_MGR
      .long    CONMSKTBL_K_BITMASK32
      ...
      .long    0       ; terminate const/bitmsk table
      .long    0

    -- ASCII List of item code names
  VMSDEF_T_$QUIDEF__1:
      .asciz 'QUI$_CANCEL_OPERATION'
      ...
  VMSDEF_T_$QUIDEF__75:
      .asciz 'QUI$_MANAGER_STATUS'
      ; no termination necessary
  ;
      .end

  ------------------------------------------------------------------------
  14-SEP-1998 ZE.

  Index                                                     PAGE INDEX-1
   


                                  INDEX



  files                                 VMSDEF_$DVIDEF.MAR, 9-9
    CONFIG.C, 6-1                       VMSDEF_DIRECTORY.MAR, 9-10,
    CONFIG.DAT, 6-1                         12-6
      format, 6-2
    CONFIG.OPT, 6-1                   privileges
    CVT__HTML.COM, 9-2                  SETPRV, 5-5
    CVT__RNO.COM, 9-3                   Warning, 5-5
    CVT_DOC.COM, 9-1                  Python modules modified
    FILE_SET_DATE.C, 9-4                compileall, 8-1
    GETPATH.C, 4-1                      tempfile, 8-1
    mod__METHODS.DAT                    test_support, 8-1
      format, 6-5
    POSIXMODULE.C, 12-2               software
    PYTHONSTARTUP.PY, 12-3              browsers, 2-1
    PYVMS_READLINE.C, 4-2               HTTP servers, 2-1
    SETUP.COM, 9-2
    TXT.FDL, 2-2                      tools
    UNTAR2DATESET.COM, 9-8              CONFIG_INITTAB2MAR.COM, 6-1
    VMS__CVT.C, 12-3                    CVT__HTML, 9-2
    VMS__GETPATH.C, 4-1                 CVT__RNO, 9-3
    VMS__GETTIMEOFDAY.C, 12-2           CVT_DOC, 9-1
    VMS__GMTIME.C, 12-2                 FILE_SET_DATE, 9-4, 9-8
    VMS__RMDIR.C, 12-3                  GZIP, 9-12 to 9-13
    VMS__UTIME.C, 12-4                  MODULEMETHODS2MAR.COM, 6-4
    VMSDAT_VMSVER.DAT, 9-11             UNTAR2DATESET, 9-4, 9-8
    VMSDAT_VMSVER.MAR, 9-11             UNZIP, 9-12
    VMSDEF_$DVIDEF.DAT, 9-9             VMSTAR, 9-4, 9-8, 9-12 to 9-13
