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 '' 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) >>> >>> # a bit in the second longword >>> hex (vms_prvdef.PRV_M_READALL) '0x800000000L' >>> type (vms_prvdef.PRV_M_READALL) >>> 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 '' 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 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 \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:

+

through
+
are converted to '.header level' commands. 
 +
is converted to '.literal' and '.end literal' + 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.
    +
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().
    +
is converted to '.list' and '.end list'. HTML2RNO tells RUNOFF to prefix the list elements with a decimal number.
  • is converted to '.list element' which works with both
      and
        .
        is just translated into a new paragraph
        The left margin is re-established.
        moves the left margin 8 characters to the right.
        is translated into a new paragraph. The left margin is re-established.
        is converted to '.break'
        does a line break. Then a line containing dashes (-) is inserted as literal text into the RUNOFF file.

        starts a new line and puts a '.blank' on it.

        +
        is converted to '.center;text-to-center'. + 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. + is usually displayed in italics within a browser. HTML2RNO tells RUNOFF to underline the embedded text. ------------------------------------------------------------------------ HTML2RNO uses the 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 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: aaabbb 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
        
          Example:
          
                  text-1
          text-2more-text-1
          more-text-2
          
        

          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
          
         and 
        .)

  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:
          
          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