PYVMS - Python on OpenVMS PAGE 1 title page __ | \ | | _ |__/ | | - / \ -O- | \ / \_/ \_/ | | _ | | /\/\ / \ | | / || \ \_ \ / | | \ \/ | | \_/ Copyright, 1996 - 1998 by Uwe Zessin ------------------------------------------------------------------------ PYVMS - documentation August 1998 This manual contains documentation about 'Python on OpenVMS'. Revision/Update Information: This is the third preview. Software Version: PYVMS V1.5.1-V001P3 --PREVIEW-- Uwe Zessin, Germany ------------------------------------------------------------------------ 12-AUG-1998 ZE. PYVMS - Python on OpenVMS 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 PAGE 3 PYVMS copyright 0.2 The PYVMS Copyright Copyright 1996-1998, 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. ------------------------------------------------------------------------ 18-MAY-1998 ZE. PYVMS - Python on OpenVMS 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-2 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.2.1 Patches are maintained at: . . . . . . . . . . . 3-2 3.2.2 Patches commented: . . . . . . . . . . . . . . . 3-4 3.2.2.1 bltinmodule.1.txt . . . . . . . . . . . . . . . 3-5 3.2.2.2 bltinmodule.2.txt . . . . . . . . . . . . . . . 3-5 3.2.2.3 bltinmodule.3.txt . . . . . . . . . . . . . . . 3-5 3.2.2.4 ceval.1.txt . . . . . . . . . . . . . . . . . . 3-5 3.2.2.5 classobject.1.txt . . . . . . . . . . . . . . . 3-5 3.2.2.6 configure.1.txt . . . . . . . . . . . . . . . . 3-5 3.2.2.7 configure.2.txt . . . . . . . . . . . . . . . . 3-5 3.2.2.8 fileobject.1.txt . . . . . . . . . . . . . . . . 3-5 3.2.2.9 freeze.1.txt . . . . . . . . . . . . . . . . . . 3-6 3.2.2.10 gzip.1.txt . . . . . . . . . . . . . . . . . . . 3-6 3.2.2.11 imaplib.1.txt . . . . . . . . . . . . . . . . . 3-6 3.2.2.12 imaplib.2.txt . . . . . . . . . . . . . . . . . 3-6 3.2.2.13 imaplib.3.txt . . . . . . . . . . . . . . . . . 3-6 3.2.2.14 import.1.txt . . . . . . . . . . . . . . . . . . 3-6 3.2.2.15 longobject.1.txt . . . . . . . . . . . . . . . . 3-6 3.2.2.16 object.1.txt . . . . . . . . . . . . . . . . . . 3-7 3.2.2.17 parsermodule.1.txt . . . . . . . . . . . . . . . 3-7 3.2.2.18 pcre.1.txt . . . . . . . . . . . . . . . . . . . 3-7 3.2.2.19 sgmllib.1.txt . . . . . . . . . . . . . . . . . 3-7 3.2.2.20 sgmllib.2.txt . . . . . . . . . . . . . . . . . 3-7 3.2.2.21 socketserver.1.txt . . . . . . . . . . . . . . . 3-7 3.2.2.22 string.1.txt . . . . . . . . . . . . . . . . . . 3-7 3.2.2.23 stringobject.1.txt . . . . . . . . . . . . . . . 3-7 3.2.2.24 stropmodule.1.txt . . . . . . . . . . . . . . . 3-7 3.2.2.25 timemodule.1.txt . . . . . . . . . . . . . . . . 3-8 3.2.2.26 urllib.1.txt . . . . . . . . . . . . . . . . . . 3-8 3.2.2.27 urllib.2.txt . . . . . . . . . . . . . . . . . . 3-8 PYVMS - Python on OpenVMS PAGE 5 table of contents 3.2.2.28 zlibmodule.1.txt . . . . . . . . . . . . . . . . 3-8 3.2.2.29 _tkinter.1.txt . . . . . . . . . . . . . . . . . 3-8 3.3 how patching is/was done on OpenVMS . . . . . . . 3-8 CHAPTER 4 building PYVMS 4.1 get the necessary software . . . . . . . . . . . . 4-1 4.1.1 the Python distribution is available at: . . . . 4-1 4.1.2 get the PYVMS distribution from: . . . . . . . . 4-1 4.1.3 you also need the following tools... . . . . . . 4-2 4.2 create the root directory and restore the Python distribution . . . . . . . . . . . . . . . . . . . 4-2 4.3 create additional directories . . . . . . . . . . 4-3 4.4 decompress+extract the PYVMS distribution . . . . 4-3 4.5 copy PYVMS tools from temp-tree . . . . . . . . . 4-4 4.6 build tool FILE_SET_DATE . . . . . . . . . . . . . 4-4 4.7 set original date + time on files . . . . . . . . 4-4 4.8 save some original files . . . . . . . . . . . . . 4-5 4.9 move PYVMS files . . . . . . . . . . . . . . . . . 4-6 4.10 translate and compile ... . . . . . . . . . . . . 4-6 4.10.1 translate VMSDEF modules . . . . . . . . . . . . 4-6 4.10.2 compile for the DCL environment . . . . . . . . 4-7 4.10.3 compile for the POSIX environment . . . . . . . 4-7 4.11 setup and go . . . . . . . . . . . . . . . . . . . 4-7 4.12 convert documentation to RUNOFF format . . . . . . 4-8 4.13 run tests . . . . . . . . . . . . . . . . . . . . 4-8 CHAPTER 5 Python in the OpenVMS environment 5.1 path support . . . . . . . . . . . . . . . . . . . 5-1 CHAPTER 6 programming guidelines 6.1 functions . . . . . . . . . . . . . . . . . . . . 6-1 6.1.1 arguments . . . . . . . . . . . . . . . . . . . 6-1 6.1.2 keyword arguments . . . . . . . . . . . . . . . 6-1 6.1.3 functions returning no data . . . . . . . . . . 6-1 6.2 OpenVMS condition values . . . . . . . . . . . . . 6-1 6.3 special OpenVMS datatypes . . . . . . . . . . . . 6-2 6.3.1 64-bit quadword . . . . . . . . . . . . . . . . 6-2 6.3.2 128-bit octaword . . . . . . . . . . . . . . . . 6-2 6.4 processes . . . . . . . . . . . . . . . . . . . . 6-2 6.4.1 privileges . . . . . . . . . . . . . . . . . . . 6-2 6.4.2 process identification (PID) . . . . . . . . . . 6-2 CHAPTER 7 Modules 7.1 pyvms module . . . . . . . . . . . . . . . . . . . 7-1 7.2 vms_lbr module . . . . . . . . . . . . . . . . . . 7-5 7.2.1 OUTPUT_HELP - Output Help Messages . . . . . . . 7-5 PYVMS - Python on OpenVMS PAGE 6 table of contents 7.3 vms_lib module . . . . . . . . . . . . . . . . . 7-10 7.3.1 ADD_TIMES - Add Two Quadword Times . . . . . . 7-11 7.3.2 ASN_WTH_MBX - Assign Channel with Mailbox . . 7-12 7.3.3 ATTACH - Attach Terminal to Process . . . . . 7-14 7.3.4 CREATE_DIR - Create a Directory . . . . . . . 7-15 7.3.5 CURRENCY - Get System Currency Symbol . . . . 7-15 7.3.6 CVT_VECTIM - Convert 7-Word Vector to Internal Time . . . . . . . . . . . . . . . . . . . . . 7-16 7.3.7 DATE_TIME - Date and Time Returned as a String 7-17 7.3.8 DAY - Day Number Returned as a Longword Integer 7-18 7.3.9 DAY_OF_WEEK - Show Numeric Day of Week . . . . 7-19 7.3.10 DELETE_LOGICAL - Delete Logical Name . . . . . 7-20 7.3.11 DELETE_SYMBOL - Delete CLI Symbol . . . . . . 7-22 7.3.12 DIGIT_SEP - Get Digit Separator Symbol . . . . 7-24 7.3.13 DO_COMMAND - Execute Command . . . . . . . . . 7-24 7.3.14 FID_TO_NAME - Convert Device and File ID to File Specification . . . . . . . . . . . . . . 7-25 7.3.15 FIND_IMAGE_SYMBOL - Find Universal Symbol in Shareable Image File . . . . . . . . . . . . . 7-27 7.3.16 FREE_EF - Free Event Flag . . . . . . . . . . 7-28 7.3.17 GETDVI - Get Device/Volume Information . . . . 7-29 7.3.18 GETJPI - Get Job/Process Information . . . . . 7-31 7.3.19 GETQUI - Get Queue Information . . . . . . . . 7-33 7.3.20 GETSYI - Get Systemwide Information . . . . . 7-36 7.3.21 GET_COMMAND - Get Line from SYS$COMMAND . . . 7-37 7.3.22 GET_COMMON - Get String from Common . . . . . 7-39 7.3.23 GET_EF - Get Event Flag . . . . . . . . . . . 7-39 7.3.24 GET_FOREIGN - Get Foreign Command Line . . . . 7-40 7.3.25 GET_SYMBOL - Get Value of CLI Symbol . . . . . 7-42 7.3.26 GET_USERS_LANGUAGE - Return the User's Language 7-43 7.3.27 LP_LINES - Lines on Each Printer Page . . . . 7-44 7.3.28 PUT_COMMON - Put String to Common . . . . . . 7-45 7.3.29 PUT_OUTPUT - Put Line to SYS$OUTPUT . . . . . 7-45 7.3.30 RADIX_POINT - Radix Point Symbol . . . . . . . 7-46 7.3.31 RESERVE_EF - Reserve Event Flag . . . . . . . 7-47 7.3.32 RUN_PROGRAM - Run New Program . . . . . . . . 7-49 7.3.33 SET_LOGICAL - Set Logical Name . . . . . . . . 7-49 7.3.34 SET_SYMBOL - Set Value of CLI Symbol . . . . . 7-52 7.3.35 SUB_TIMES - Subtract Two Quadword Times . . . 7-54 7.3.36 WAIT - Wait a Specified Period of Time . . . . 7-56 7.4 vms_sys module . . . . . . . . . . . . . . . . . 7-57 7.4.1 ASCTIM - Convert Binary Time to ASCII String . 7-57 7.4.2 ASCTOID - Translate Identifier Name to Identifier . . . . . . . . . . . . . . . . . . 7-59 7.4.3 ASCUTC - Convert UTC to ASCII . . . . . . . . 7-60 7.4.4 BINTIM - Convert ASCII String to Binary Time . 7-61 7.4.5 BINUTC - Convert ASCII String to UTC Binary Time . . . . . . . . . . . . . . . . . . . . . 7-62 7.4.6 CANWAK - Cancel Wakeup . . . . . . . . . . . . 7-63 7.4.7 DELPRC - Delete Process . . . . . . . . . . . 7-65 7.4.8 FORCEX - Force Exit . . . . . . . . . . . . . 7-66 7.4.9 GETTIM - Returns the current system time in a 64-bit format . . . . . . . . . . . . . . . . 7-69 7.4.10 GETUTC - Get UTC Time . . . . . . . . . . . . 7-70 PYVMS - Python on OpenVMS PAGE 7 table of contents 7.4.11 HIBER - Hibernate . . . . . . . . . . . . . . 7-70 7.4.12 NUMTIM - Convert Binary Time to Numeric Time . 7-71 7.4.13 NUMUTC - Convert UTC Time to Numeric Components 7-72 7.4.14 PURGWS - Purge Working Set . . . . . . . . . . 7-73 7.4.15 RESUME - Resume Process . . . . . . . . . . . 7-74 7.4.16 SCHDWK - Schedule Wakeup . . . . . . . . . . . 7-75 7.4.17 SETDDIR - Set Default Directory . . . . . . . 7-77 7.4.18 SETPRI - Set Priority . . . . . . . . . . . . 7-79 7.4.19 SETPRN - Set Process Name . . . . . . . . . . 7-80 7.4.20 SETSWM - Set Process Swap Mode . . . . . . . . 7-82 7.4.21 SUBSYSTEM - Subsystem . . . . . . . . . . . . 7-83 7.4.22 SUSPND - Suspend Process . . . . . . . . . . . 7-84 7.4.23 TIMCON - Time Converter . . . . . . . . . . . 7-86 7.4.24 WAKE - Wake Process from Hibernation . . . . . 7-87 7.5 'VMSDEF'-related modules . . . . . . . . . . . . 7-89 7.5.1 vms_dvidef module . . . . . . . . . . . . . . 7-89 7.5.2 vms_jpidef module . . . . . . . . . . . . . . 7-89 7.5.3 vms_kgbdef module . . . . . . . . . . . . . . 7-89 7.5.4 vms_lnmdef module . . . . . . . . . . . . . . 7-90 7.5.5 vms_quidef module . . . . . . . . . . . . . . 7-90 7.5.6 vms_syidef module . . . . . . . . . . . . . . 7-90 CHAPTER 8 Tools 8.1 coming with PYVMS . . . . . . . . . . . . . . . . 8-1 8.1.1 CVT_DOC - convert .HTML to final docu formats . 8-1 8.1.2 CVT__HTML - convert .HTML to .RNO . . . . . . . 8-2 8.1.3 CVT__RNO - convert .RNO to final docu . . . . . 8-3 8.1.4 FILE_SET_DATE - alter CDT and RDT . . . . . . . 8-3 8.1.5 HTML2RNO.PY - convert .HTML to .RNO . . . . . . 8-4 8.1.6 UNTAR2DATESET - create procedure to change dates 8-7 8.1.7 VMSDEF2MAR - convert a VMSDEF .DAT file to macro 8-8 8.1.8 VMSDEF_BLDDIR2MAR - build VMSDEF directory . . . 8-9 8.1.9 VMSVER2MAR - build VMS version table . . . . . 8-10 8.2 not delivered with PYVMS . . . . . . . . . . . . 8-11 8.2.1 GZIP - (de)compress files to/from archive . . 8-11 8.2.2 UNZIP - decompress files from archive . . . . 8-12 8.2.3 VMSTAR - maintain TapeARchive file . . . . . . 8-12 CHAPTER 9 The history of PYVMS 9.1 the history of PYVMS . . . . . . . . . . . . . . . 9-1 CHAPTER 10 The future of PYVMS 10.1 the future of PYVMS . . . . . . . . . . . . . . 10-1 CHAPTER 11 Notes 11.1 PYVMS notes . . . . . . . . . . . . . . . . . . 11-1 PYVMS - Python on OpenVMS PAGE 8 table of contents 11.2 the VMSDEF data structures . . . . . . . . . . . 11-6 INDEX INDEX-1 CHAPTER 1 Introduction __ | \ | | _ |__/ | | - / \ -O- | \ / \_/ \_/ | | _ | | /\/\ / \ | | / || \ \_ \ / | | \ \/ | | \_/ 1.1 Welcome Welcome to PYVMS - the Python programming language running on the OpenVMS operating system. 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 you know why. ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 1-2 Introduction PYVMS has been configured with as much builtin modules as possible. Here is a list as of 27-APR-1998: >>> 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', 'signal', 'socket', 'soundex', 'strop', 'struct', 'sys', 'time', 'timing', 'vms_jpidef', 'vms_kgbdef', 'vms_lbr', 'vms_lib', 'vms_lnmdef', 'vms_quidef', 'vms_sys') Please note: None of the nonVMS-related modules have been thoroughly tested - some even contain compiler warnings! ------------------------------------------------------------------------ PYVMS consists of the following elements: - the original Python distribution stored in the directory tree [PYTHON.PYTHON-1_5_1...] - 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 '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. 1.2 Version numbers / file names This release of Python (Version 1.5.1) on OpenVMS (sub-version V001) provides the following files: pyvms1.5.1-v001.readme Short text file to get started. This is for people who do not have access to the full documentation, yet. pyvms1.5.1-v001src.zip The PYVMS distribution with all files. It is explained in the documentation in the chapter 'building PYVMS'. This is a binary file! PYVMS - Python on OpenVMS PAGE 1-3 Introduction pyvms1.5.1-v001doc.tlb This is an OpenVMS text library containing the PYVMS documentation for line printer (and printers understanding ANSI format) output. This is a binary file and you need access to an OpenVMS system to extract the contents from this text library! Read 'pyvms1.5.1-v001.readme' how to get started - it includes instructions how to convert the docu to file pyvms1.5.1-v001doc.txt for reading with a text editor. pyvms1.5.1-v001doc.txt The PYVMS documentation in simple text form for reading with a text editor - primary for those people who don't have access to an OpenVMS system to handle the '.TLB' files, but want to read / print the docu from a different operating system. The individual pages are separated by FormFeed characters. Maximum page size is 66 lines, but there are no empty filler lines before a FormFeed character. --- The filenames are created from the following elements: pyvms 'Python on OpenVMS' 1.5.1 The port is based on Python Version 1.5.1. v001 OpenVMS port - version 1. It will be incremented for each new release. If the Python version increments (e.g. to 1.5.2) then the OpenVMS port version will reset to 1 again. I had made previews available. The first one got the version 'V001P1'. doc / src doc = this file contains pre-build documentation. src = distribution containing source code including documentation. (Docu is in HTML format. You must first build Python and can then convert the HTML to other formats - see chapter 'building PYVMS'.) There are currently (07-JUN-1998) no pre-compiled distributions available. ------------------------------------------------------------------------ As of 25-JUL-1998 'PYVMS' is still a 'hobby' project of mine (Uwe Zessin) which I do for my own pleasure in my spare time. ------------------------------------------------------------------------ @@ to be enhanced ------------------------------------------------------------------------ 25-JUL-1998 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 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://kcgl1.eng.ohio-state.edu/www/doc/serverinfo.html o the 'WASD HTTP Server Package' is available at: http://www.vsm.com.au:8000/ or ftp:/ftp.vsm.com.au/wasd/ 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:DKA100:[PYTHON.PYTHON-1_5_1.VMS.DOC]TOC.HTML ------------------------------------------------------------------------ PYVMS - Python on OpenVMS 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. ------------------------------------------------------------------------ 19-AUG-1998 ZE. 2.2 conventions used in the documentation The documentation for PYVMS uses a number of conventions: The printed documentation (file PYVMSDOC.MEM or PYVMSDOC.LNI) contains a table of contents and an index that are generated by RUNOFF. The online version which you can read with a browser has both a simple table of contents and an index, which are manually maintained. ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 2-3 conventions used in the documentation 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 '@@'. ------------------------------------------------------------------------ 30-APR-1998 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/ 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 >>> Relinking of Python was _not_ necessary. Please check your environment. PYVMS - Python on OpenVMS PAGE 3-2 patches to Python 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. 3.2.1 Patches are maintained at: http://www.python.org/1.5/patches-1.5.1/ Here is a (slightly edited) copy of this page (as of 26-JUL-1998): ------------------------------------------------------------------------ Patches for Python 1.5.1 If you find a new bug in Python 1.5.1, please get in touch with me (guido@python.org). Make sure to mention which platform you are using and what the problem is. Here's a file containing the combined set of patches: patches.all. Some caveats: Some web browsers save this file with CRLF line endings on a Unix system; this will make the patch fail. Remove the CR characters with a plain text editor or other tool. With patch version 2.4 or 2.5 (and maybe other versions), you must set the environment variable POSIXLY_CORRECT to TRUE. Otherwise patch won't look at the "Index:" lines and it will ask for the filename for each patch. Individual Patches and Descriptions - There's an "import addpack" statement in Tools/freeze/freeze.py that shouldn't be there. Patch file: freeze.1.txt. (20-Apr-98) - The _tkinter module does not compile with Tcl 7.6 or earlier. Patch file: _tkinter.1.txt. (20-Apr-98) - The configure script sets CCSHARED to a bogus value for the SGI C compiler on IRIX 6.x. Patch file: configure.1.txt. (20-Apr-98; patch redone 24-Apr-98) - Printing an object whose repr() returns a string with a null byte in it drops the characters after the null byte. Patch file: object.1.txt. (21-Apr-98) PYVMS - Python on OpenVMS PAGE 3-3 patches to Python - On AIX, the compiler warns about some missing casts in some method tables in the parser module. Patch file: parsermodule.1.txt. (21-Apr-98) - The zlib module doesn't pass the selftest (import test.test_zlib) when linked with zlib 1.1.2. Patch file: zlibmodule.1.txt. (22-Apr-98) - The string module exports a variable 're' with value None, and it shouldn't (though "from string import " is still a bad habit!). Patch file: string.1.txt. (23-Apr-98) - Not a bug, but a cute one-line hack that speeds up range() by about 35 percent. Patch file: bltinmodule.1.txt. (23-Apr-98) - A call to mktime() inserted in the time module has bad effects when formatting non-local times. Patch file: timemodule.1.txt. (27-Apr-98) - On some platforms (HP-UX), a failing ftell() call in read() breaks reading from a pipe. The improved patch adds a work-around for a bug in ftell() on Linux. Patch file: fileobject.1.txt. (27-Apr-98; improved patch 5-May-98) - In urllib.urlopen(), some malformed URLs (http: with no host) raise an unexpected TypeError instead of the intended IOError. Patch file: urllib.1.txt. (27-Apr-98) - A tentative patch to the pcre module, with an important bugfix but also adding questionable new features (see the string-sig archives). Patch file: pcre.1.txt. (1-May-98) - Some systems really require the standard math library (-lm). I have a patch for the configure script and related files. Note that this removes the check for -lsun, an old IRIX 4.x feature. Patch file: configure.2.txt. (1-May-98) - The imaplib module's login() method requires that the sever publishes the AUTH-LOGIN or AUTH=LOGIN capability, but some servers don't publish this even though they do support LOGIN. Patch file: imaplib.1.txt. (4-May-98) - The proxy code in the urllib module is broken. Patch file: urllib.2.txt. (5-May-98) - Note that the fileobject.c patch above was improved. (5-May-98) - The sgmllib module (and hence also htmllib) doesn't always parse whitespace correctly, especially it barfs on 'r'. Patch file: sgmllib.1.txt. (6-May-98) - Note that the pcre patch patch above was improved. (7-May-98) - Embarrassingly, int(round(1450, -3)) yields 999. Patch file: bltinmodule.2.txt. (9-May-98) - Deleting an undefined local variable inside a function doesn't raise NameError like it should. Patch file: ceval.1.txt. (12-May-98) - The gzip module's readline() doesn't work quite right. Patch file: gzip.1.txt. (13-May-98) PYVMS - Python on OpenVMS PAGE 3-4 patches to Python - More small problems in the imaplib module need fixing: one to do with argument quoting, and the other to do with caching of un-tagged responses. Patch file: imaplib.2.txt. (18-May-98) - A curious problem exists in import: "import sys.time" succeeds. Patch file: import.1.txt. (19-May-98) - More minor problems with the imaplib module are fixed. Patch file: imaplib.3.txt. (29-May-98) - The string % operator can cause a core dump when %s is used for an object for which str() has a return type other than string. (This is possible though not recommended. :-) Patch file: stringobject.1.txt. (9-Jun-98) - Improved handling of entity references (they can contain '.' and '-') and support for handling processing instructions. Note: this patch patches the previous patch to sgmllib.py. Patch file: sgmllib.2.txt. (9-Jun-98) - There's a memory leak for classes that define any of the special methods __getattr__(), __setattr__() or __delattr__(). Patch file: classobject.1.txt. (23-Jul-98) - The UDP code in SocketServer.py never worked. Patch file: SocketServer.1.txt. (24-Jul-98) - Several bugs make the string-to-number conversions for ints and long ints return 0 for invalid input like "+" or +-". This affects int(), long(), string.atoi(), and string.atol(). (The patch for longobject.c also solves a problem with overlow checking.) Patch files: bltinmodule.3.txt, longobject.1.txt, stropmodule.1.txt. (25-Jul-98) Last check/download: 26-JUL-1998 10:06 CET DST. ------------------------------------------------------------------------ 3.2.2 Patches commented: ALL patch files that were available at the time of writing this have been downloaded and stored in [.VMS.PATCHES]. Note: the ODS-2 filesystem does not allow a file name with multiple dots (".") in it so names have been slightly altered: E.g.: freeze.1.txt to freeze-1.txt. Note: patch comments are listed in alphabetical order. CDT indicates the files' creation date and time that has been taken from the patch file (.TXT) and applied to the patched file using the FILE_SET_DATE tool. The process of how the patching was done on OpenVMS is described after this section. PYVMS - Python on OpenVMS PAGE 3-5 patches to Python 3.2.2.1 bltinmodule.1.txt Applied. CDT=superceeded 3.2.2.2 bltinmodule.2.txt Applied. CDT=superceeded 3.2.2.3 bltinmodule.3.txt Applied. CDT="25-JUL-1998 23:28:53" 3.2.2.4 ceval.1.txt Applied. CDT="12-MAY-1998 20:27:36" 3.2.2.5 classobject.1.txt Applied. CDT="23-JUL-1998 20:49:29" 3.2.2.6 configure.1.txt Not applied - configure is not used on OpenVMS. 3.2.2.7 configure.2.txt Not applied - configure is not used on OpenVMS. The patch to 'config.h.in' (which is stored as CONFIG.H_IN) is not necessary, either. 3.2.2.8 fileobject.1.txt Applied. CDT="05-MAY-1998 21:48:45" PYVMS - Python on OpenVMS PAGE 3-6 patches to Python 3.2.2.9 freeze.1.txt Applied. CDT="20-APR-1998 17:53:19" 3.2.2.10 gzip.1.txt Applied. CDT="13-MAY-1998 21:49:58" 3.2.2.11 imaplib.1.txt Applied. CDT=superceeded 3.2.2.12 imaplib.2.txt Applied. CDT="18-MAY-1998 14:39:42" 3.2.2.13 imaplib.3.txt Applied. CDT="29-MAY-1998 13:34:03" 3.2.2.14 import.1.txt Applied. CDT="19-MAY-1998 15:09:05" Note: IMPORT.C has been enhanced for OpenVMS since the patch has been made. On OpenVMS VAX V6.1 with patch VAXACRT11_061 it was not possible to do '>>> import test.autotest', because the stat() function did not check if files with a blank type can represent a directory file. Example: if the path is '/x/y/z/d', then stat() should check for a file '/x/y/z/d.DIR'. 3.2.2.15 longobject.1.txt Applied. CDT="25-JUL-1998 12:42:02" PYVMS - Python on OpenVMS PAGE 3-7 patches to Python 3.2.2.16 object.1.txt Applied. CDT="21-APR-1998 22:25:01" 3.2.2.17 parsermodule.1.txt Applied. CDT="21-APR-1998 22:31:45" 3.2.2.18 pcre.1.txt Applied. 3 files. CDT="07-MAY-1998 15:22:5%" pcre-int.h, pcre.h, pypcre.c 3.2.2.19 sgmllib.1.txt Applied. CDT="16-APR-1998 21:04:26" 3.2.2.20 sgmllib.2.txt Applied. CDT="26-MAY-1998 22:48:53" 3.2.2.21 socketserver.1.txt Applied. CDT="25-JUL-1998 02:27:33" 3.2.2.22 string.1.txt Applied. CDT="20-APR-1998 14:01:00" 3.2.2.23 stringobject.1.txt Applied. CDT="09-JUN-1998 15:01:53" 3.2.2.24 stropmodule.1.txt Applied. CDT="25-JUL-1998 04:23:01" PYVMS - Python on OpenVMS PAGE 3-8 patches to Python 3.2.2.25 timemodule.1.txt Applied, after edits for PYVMS done! Comments from the patch utility: Hunk 1 succeeded at 325 (offset 21 lines). Hunk 2 succeeded at 344 (offset 21 lines). 3.2.2.26 urllib.1.txt Applied. CDT=superceeded 3.2.2.27 urllib.2.txt Applied. CDT="05-MAY-1998 13:58:13" 3.2.2.28 zlibmodule.1.txt Applied. CDT="22-APR-1998 21:32:0" 3.2.2.29 _tkinter.1.txt Applied. CDT="20-APR-1998 18:19:51" 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. PYVMS - Python on OpenVMS PAGE 3-9 patches to Python $! -- 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 $ 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 PYVMS - Python on OpenVMS PAGE 3-10 patches to Python $ 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 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 'building PYVMS' chapter needs to be enhanced to include the BACKUP commands for any files never being patched before. - The procedure [.VMS.TOOLS]BUILD_DIST_SRC.COM needs to be enhanced to copy the patched file, too. ------------------------------------------------------------------------ 19-AUG-1998 ZE. CHAPTER 4 building PYVMS This chapter describes the steps to build Python V1.5.1 on OpenVMS. ------------------------------------------------------------------------ 4.1 get the necessary software 4.1.1 the Python distribution is available at: ftp://ftp.python.org/ftp/python/src/pyth151.tgz or from one of the mirror sites. Don't forget to do a 'binary' transfer! Store the file as 'PYTHON1_5_1.TAR-GZ' on your OpenVMS system. The Python documentation is there, too. Please access http://www.python.org/ for downloading. 4.1.2 get the PYVMS distribution from: ftp://ftp.python.org/pub/python/vms/pyvms1.5.1-v001src.zip Don't forget to do a 'binary' transfer! Store the file as 'PYVMS1_5_1-V001SRC.ZIP' on your OpenVMS system. PYVMS - Python on OpenVMS PAGE 4-2 building PYVMS 4.1.3 you also need the following tools... ..to extract the files from 'PYTHON1_5_1.TAR-GZ' and 'PYVMS1_5_1-V001SRC.ZIP': - GZIP - UNZIP - VMSTAR Sources are listed in the 'tools' chapter and not repeated here. 4.2 create the root directory and restore the Python distribution This example assumes that the tree will be stored on a disk named 'DKA100:'. It also assumes that the files 'PYTHON1_5_1.TAR-GZ', 'PYVMS1_5_1-V001SRC.ZIP' and the necessary tools (GZIP.EXE, UNZIP.EXE + VMSTAR.EXE) have been stored at 'DKB100:[000000]'. $! -- create top-level directory $ SET DEFAULT DKA100:[PYTHON] $ CREATE /DIRECTORY /OWNER=[1,4] /PROTECTION=(G:RE,W:RE) /LOG [] $! $! -- define foreign command for GZIP $ gzip = "$DKB100:[000000]GZIP.EXE" $! $! -- extract/decompress TapeARchive from GZIPped file $ DEFINE /USER_MODE SYS$OUTPUT DKB100:[000000]PYTHON1_5_1.TAR $ gzip -d -c DKB100:[000000]PYTHON1_5_1.TAR-GZ $! $! -- remove definition $ DELETE /SYMBOL/LOCAL gzip $! $! -- define foreign command for VMSTAR $ vmstar = "$DKA100:[000000]VMSTAR.EXE" $! $! -- list contents of TapeARchive $ DEFINE /USER_MODE SYS$OUTPUT PYTHON1_5_1.LIS $ vmstar tf DKB100:[000000]PYTHON1_5_1.TAR $! $! -- extract files from TapeARchive and restore directory tree $ SET PROTECTION= (S:RWED,O:RWED,G:RE,W:RE) /DEFAULT $ DEFINE /USER_MODE SYS$OUTPUT PYTHON1_5_1.UNTAR $ vmstar xvf DKB100:[000000]PYTHON1_5_1.TAR $! $! -- remove definition $ DELETE /SYMBOL/LOCAL vmstar $! $! -- delete the TapeARchive - please keep PYTHON1_5_1.TAR-GZ $ DELETE /LOG DKB100:[000000]PYTHON1_5_1.TAR;* $! $! -- make all files readable to all users $ SET FILE /PROTECTION=(G:RE,W:RE) /OWNER=[1,4] [PYTHON...]*.* /LOG $! PYVMS - Python on OpenVMS PAGE 4-3 building PYVMS $! -- Note: some versions of VMSTAR restore the tree as: $! -- [PYTHON.PYTHON-1.5.1...] instead of [PYTHON.PYTHON-1_5_1] $! -- The fix is to enter the following two commands: $ rename [PYTHON.PYTHON-1.5]1.DIR [PYTHON]PYTHON-1_5_1 $ delete [PYTHON.PYTHON-1]5.DIR;1,[PYTHON]PYTHON-1.DIR;1 $! $! -- correct file specifications $ edit/edt [PYTHON]PYTHON1_5_1.UNTAR * substitute/PYTHON.PYTHON-1.5.1/PYTHON.PYTHON-1_5_1/%whole/notype * exit $ purge [PYTHON]PYTHON1_5_1.UNTAR $! 4.3 create additional directories The intention is to keep the original directories as much unchanged as possible. $ SET DEFAULT DKA100:[PYTHON.PYTHON-1_5_1.VMS] $ CREDIR = "CREATE/DIRECTORY/OWNER=[1,4]/PROTECTION=(G:RE,W:RE)/LOG" $! $ CREDIR [] $ CREDIR [.O_ALPHA.MODULES] $ CREDIR [.O_ALPHA.OBJECTS] $ CREDIR [.O_ALPHA.PARSER] $ CREDIR [.O_ALPHA.PYTHON] $ CREDIR [.O_ALPHA.VMS] $ CREDIR [.O_ALPHA.VMS_TOOLS] $ CREDIR [.O_VAX.MODULES] $ CREDIR [.O_VAX.OBJECTS] $ CREDIR [.O_VAX.PARSER] $ CREDIR [.O_VAX.PYTHON] $ CREDIR [.O_VAX.VMS] $ CREDIR [.O_VAX.VMS_TOOLS] $ CREDIR [.TMP] $! All other directories will automatically be created during the restore of the PYVMS distribution. 4.4 decompress+extract the PYVMS distribution $! -- create a temporary directory tree $ set DEFAULT DKA100:[PYVMS_TMP] $ CREATE /DIRECTORY /OWNER=[1,4] /PROTECTION=(G:RE,W:RE) /LOG [] $! $! -- define foreign command for UNZIP $ unzip = "$DKB100:[000000]UNZIP.EXE" $! PYVMS - Python on OpenVMS PAGE 4-4 building PYVMS $! -- list contents of .ZIP file $ DEFINE /USER_MODE SYS$OUTPUT [PYTHON]PYVMS1_5_1-V001SRC.LIS $ unzip -l DKB100:[000000]PYVMS1_5_1-V001SRC.ZIP $! $! -- extract/decompress files/directories from ZIPped file $ SET PROTECTION= (S:RWED,O:RWED,G:RE,W:RE) /DEFAULT $ DEFINE /USER_MODE SYS$OUTPUT DKB100:[000000]PYVMS1_5_1-V001SRC.UNZIP $ unzip -e DKB100:[000000]PYVMS1_5_1-V001SRC.ZIP $! $! -- remove definition $ DELETE /SYMBOL/LOCAL unzip $! $! -- make all files readable to all users $ SET FILE /PROTECTION=(G:RE,W:RE) /OWNER=[1,4] [PYVMS_TMP...]*.* /LOG $! 4.5 copy PYVMS tools from temp-tree Some tools from the PYVMS distribution are needed now. $ BACKUP DKA100:[PYVMS_TMP...]UNTAR2DATESET.C*, FILE_SET_DATE*.C* - DKA100:[PYTHON...] /BY_OWNER=[1,4] /LOG $! 4.6 build tool FILE_SET_DATE $ set DEFAULT DKA100:[PYTHON.PYTHON-1_5_1.VMS.TOOLS] $ @ FILE_SET_DATE-BUILD.COM $! 4.7 set original date + time on files .. from the Python distribution $ set DEFAULT [PYTHON.PYTHON-1_5_1.VMS] $! $! -- create command procedure to make calls to FILE_SET_DATE $ @[.TOOLS]UNTAR2DATESET [PYTHON]PYTHON1_5_1.UNTAR - [PYTHON.PYTHON-1_5_1.VMS.TMP]PYTHON1_5_1-DATESET.COM $! $ !+ $ ! check the output file which should look like: $ ! [...] $ ! $ SET VERIFY $ ! $ FSD = "$ [...] PYVMS - Python on OpenVMS PAGE 4-5 building PYVMS $ ! $ FSD [PYTHON.PYTHON-1.5B2]BUGS "10-APR-1995 11:47:32.00" $ ! [...] $ ! $ ! otherwise you have to change UNTAR2DATESET.COM ... $ !- $! $! -- run created procedure to change files' date + time $! -- save output for later inspection $ @[.TMP]PYTHON1_5_1-DATESET.COM /OUTPUT= [.TMP]PYTHON1_5_1-DATESET.LOG $! $! -- check for any problems $ SEARCH [.TMP]PYTHON1_5_1-DATESET.LOG "%" /WINDOW=(1,4) $! $! -- delete files $ delete /LOG [.TMP]PYTHON1_5_1-DATESET.COM;*, - [.TMP]PYTHON1_5_1-DATESET.LOG;* $! 4.8 save some original files These files will be replaced with modified ones from the PYVMS distribution. A copy is made for easy access to the original files. BACKUP is used because it retains the creation and revision date + time of the files. The following type extensions are used: *.*$O - original file, superceeded by a new one with changes for PYVMS *.*$P - original file, superceeded by a new one with Python patches *.*$OP - original file, superceeded by a new one with Python patches AND changes for PYVMS $ set DEFAULT [PYTHON.PYTHON-1_5_1.MODULES] $ BACKUP MAIN.C, SELECTMODULE.C, SOCKETMODULE.C, _LOCALEMODULE.C - *.C$O /BY_OWNER=ORIGINAL /LOG $ BACKUP TIMEMODULE.C *.C$OP /BY_OWNER=ORIGINAL /LOG $ BACKUP TIMING.H *.H$O /BY_OWNER=ORIGINAL /LOG $ BACKUP PARSERMODULE.C, PYPCRE.C, STROPMODULE.C, ZLIBMODULE.C, - _TKINTER.C *.C$P /BY_OWNER=ORIGINAL /LOG $ BACKUP PCRE-INT.H, PCRE.H *.H$P /BY_OWNER=ORIGINAL /LOG $! $ set DEFAULT [PYTHON.PYTHON-1_5_1.OBJECTS] $ BACKUP CLASSOBJECT.C, FILEOBJECT.C, LONGOBJECT.C, OBJECT.C, - STRINGOBJECT.C *.C$P /BY_OWNER=ORIGINAL /LOG $! $ set DEFAULT [PYTHON.PYTHON-1_5_1.PYTHON] $ BACKUP BLTINMODULE.C, CEVAL.C *.C$P /BY_OWNER=ORIGINAL /LOG $ BACKUP IMPORT.C *.C$OP /BY_OWNER=ORIGINAL /LOG $! $ set DEFAULT [PYTHON.PYTHON-1_5_1.LIB] $ BACKUP GZIP.PY, IMAPLIB.PY, SGMLLIB.PY, SOCKETSERVER.PY, - STRING.PY, URLLIB.PY *.PY$P /BY_OWNER=ORIGINAL /LOG $! $ set DEFAULT [PYTHON.PYTHON-1_5_1.TOOLS.FREEZE] PYVMS - Python on OpenVMS PAGE 4-6 building PYVMS $ BACKUP FREEZE.PY *.PY$P /BY_OWNER=ORIGINAL /LOG $! 4.9 move PYVMS files This copies the entire PYVMS distribution 'over' the Python directory tree. $! -- delete tools from previous steps - will be recreated $ set DEFAULT [PYTHON.PYTHON-1_5_1.VMS] $ delete /LOG [...]UNTAR2DATESET.*;*, FILE_SET_DATE*.*;* $! $! -- copy PYVMS tree $ SET DEFAULT [PYTHON] $ BACKUP [PYVMS_TMP...]*.*; - [PYTHON...]*.* /BY_OWNER=[1,4] /LOG /TRUNCATE /NEW_VERSION $! $! -- delete temporary directory tree $ set FILE /PROTECTION=(O:RWED,W:RWED) - [000000]PYVMS_TMP.DIR;, [PYVMS_TMP...]*.*;* $ delete /log [PYVMS_TMP...]*.*;*, ;, ;, ;, ;, ;, ;, ;, ; $ delete /log [000000]PYVMS_TMP.DIR; $! $! -- save everything (optional) $ BACKUP [000000]PYTHON.DIR;,[PYTHON...]*.*;* - DKB100:[000000]PYVMS.BCK /SAVE_SET /GROUP=0 /VERIFY $! 4.10 translate and compile ... The PYVMS distribution does not contain any pre-translated or pre-compiled files in order to save space. 4.10.1 translate VMSDEF modules These modules contain OpenVMS version information, item-codes, bitmasks and constants: $ SET DEFAULT DKA100:[PYTHON.PYTHON-1_5_1.VMS] $ @ VMSDEF2MAR-ALL ! calls VMSDEF2MAR.COM $ @ VMSDEF_BLDDIR2MAR.COM $ @ VMSVER2MAR.COM VMSDAT_VMSVER.DAT Run the MACRO source files that have just been created through the MACRO assembler and put the resulting object files in the object library VMS_MACRO.OLB. PYVMS - Python on OpenVMS PAGE 4-7 building PYVMS $!! @ DMACRO_VMS @@ not necessary, here -- DMACRO_VMS is called from DCC-ALL 4.10.2 compile for the DCL environment $ @ DCC-ALL $! $ @ LINKD_PY $! $ @ LINKD_PGEN 4.10.3 compile for the POSIX environment $ @ PCC-ALL $! $ @ LINKP_PY @@ No attempt has been made to build 'PGEN' for POSIX - I haven't even used it in the DCL environment... 4.11 setup and go Python on OpenVMS needs some symbols: PYTHON A foreign command pointing to the executable. PYTHONPATH Information where the library is. PYTHONSTARTUP Points to a file. In VMS speak this is an 'initialization file' that Python executes on startup. PYTHONUNBUFFERED Tell Python to use unbuffered I/O. @@maintenance note: Symbol list could be moved to a different chapter. The SETUP.COM procedure defines them dynamically: $ @SETUP PYVMS - Python on OpenVMS PAGE 4-8 building PYVMS Now you can run Python on OpenVMS: $ PYTHON Python 1.5.1 (V001, May 18 1998, 21:37:16) [DECC] on vms Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam portions Copyright 1996-1998 Uwe Zessin >>> 4.12 convert documentation to RUNOFF format The PYVMS distribution contains full sources to format the files for line printer or text output. You do not need to download the files 'pyvms1.5.1-v001doc.tlb' or 'pyvms1.5.1-v001doc.txt' from the Internet if you have the 'PYVMS source distribution' and access to this chapter. $ set DEFAULT [PYTHON.PYTHON-1_5_1.VMS.DOC] $ @ CVT_DOC 4.13 run tests One of the files contains a file specification that is invalid for the ODS-2 filesystem and needs to be fixed: $ SET DEFAULT [PYTHON.PYTHON-1_5_1.LIB.TEST] $ BACKUP TEST_SUPPORT.PY;1 *.PY$O /OWNER=ORIGINAL /LOG $ edit/edt TEST_SUPPORT.PY *substitute/@test/test.test/%whole exit $ Run the tests: $ python Python 1.5.1 (V001, May 18 1998, 21:37:16) [DECC] on vms Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam portions Copyright 1996-1998 Uwe Zessin >>> import test.autotest test_grammar test_opcodes test_operations test_builtin test_exceptions test_types All 6 tests OK. >>> Note: this (and other tests) (currently) do not work with the POSIX PYVMS - Python on OpenVMS PAGE 4-9 building PYVMS version. ---------- You might need a patch to the DEC C RTL. Please see the description of patch VAXACRT11_061 in the 'Patches' chapter even if you don't run OpenVMS VAX V6.1. ------------------------------------------------------------------------ 27-JUL-1998 ZE. CHAPTER 5 Python in the OpenVMS environment This section explains how Python works in the OpenVMS environment. See also the 'programming guidelines' chapter. 5.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_1/LIB" $ python Python 1.5.1 (V001P2, Jun 22 1998, 20:34:34) [DECC] on vms Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam portions Copyright 1996-1998 Uwe Zessin >>> print sys.prefix /DKA100/PYTHON/PYTHON-1_5_1/LIB >>> PYVMS - Python on OpenVMS PAGE 5-2 Python in the OpenVMS environment >>> for idx in range(len(sys.path)): ... print sys.path[idx] ... /DKA100/PYTHON/PYTHON-1_5_1/LIB/LIB-TK /DKA100/PYTHON/PYTHON-1_5_1/LIB <-- 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 (27-JUL-1998) 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 (19-JUL-1998) NOT appended to 'sys.path'. ------------------------------------------------------------------------ @@ explain PYTHONPATH ... ------------------------------------------------------------------------ 29-JUL-1998 ZE. CHAPTER 6 programming guidelines This section gives some guidelines how to use the programming interface to OpenVMS routines. 6.1 functions 6.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. 6.1.2 keyword arguments e.g.: >>> ret = routine (p1 = val1) are not supported. 6.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. 6.2 OpenVMS condition values Using the native interfaces a programmer should _always_ check the returned condition value. Some routines also use the OpenVMS PYVMS - Python on OpenVMS PAGE 6-2 programming guidelines 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. 6.3 special OpenVMS datatypes Python on OpenVMS does not have a builtin 64-bit or 128-bit datatype. 6.3.1 64-bit quadword These are simulated by using Python's "long int" datatype. See vms_sys.gettim() or vms_sys.asctim() for examples. Using a "long int" does allow the programmer to do calculations within Python: @@ add example of date and time calculations 6.3.2 128-bit octaword These are simulated by using 32-character 'hex-strings'. See vms_sys.getutc(), or vms_sys.ascutc() for examples. 6.4 processes 6.4.1 privileges A Python on OpenVMS executable is not meant to be installed (via $INSTALL) with any privileges! Currently (08-MAR-1998) there is no way to turn off these elevated privileges and a user can always just '$RUN' the Python executable... 6.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. PYVMS - Python on OpenVMS PAGE 6-3 programming guidelines 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. ------------------------------------------------------------------------ 12-AUG-1998 ZE. CHAPTER 7 Modules 7.1 pyvms module The 'pyvms' module provides access to OpenVMS-related components: command history, item codes (fac$_name), bitmasks (fac$M_name) and other information. IMPLEMENTATION IS NOT COMPLETE. Items: vms_version_number Numeric value of vms version number that is used internally. You cannot translate the number to the string, because some strings (e.g. 'A5.5-2H4' and 'V5.5-2H4' map to the same number (05524). So, this is NOT the same as $GETSYI(SYI$_VERSION) !! Lists: definitions List of all definitions (e.g. '$DVIDEF','$QUIDEF'). Methods: - access to VMSDEF item_list returns all list of items from a definition (e.g. '$DVIDEF') item_get returns a dictionary with all details about a specific item code (e.g. 'DVI$_CYLINDERS') within a definition (e.g. '$DVIDEF'). PYVMS - Python on OpenVMS PAGE 7-2 pyvms module - access to command history history_delete delete command history history_get return current command history in a list history_size return current size of command history> history_show just output command history to screen ------------------------------------------------------------------------ Examples: >>> import pyvms >>> dir (pyvms) ['__doc__', '__name__', 'definitions', 'history_delete', 'error', 'history_get', 'item_get', 'history_size', 'item_list', 'history_show', 'vms_version_number'] >>> >>> type (pyvms.definitions) >>> type (pyvms.vms_version_number) >>> >>> print pyvms.definitions ['$DVIDEF', '$JPIDEF', '$LNMDEF', '$QUIDEF', '$SYIDEF'] >>> print pyvms.vms_version_number 6100 -- compare this with: >>> import vms_lib >>> print vms_lib.getsyi('SYI$_VERSION',0) (0, 'V6.1 ') >>> >>> import os >>> os.system('write sys$output F$GETSYI("VERSION")') V6.1 <--- output from F$GETSYI() 65537 <--- status from os.system() = RMS$_NORMAL >>> print pyvms.definitions[1] $JPIDEF >>> print len(pyvms.definitions) 4 >>> item_list = pyvms.item_list ('$DVIDEF'); >>> print len(item_list) 161 >>> print item_list ['DVI$_ACPPID', 'DVI$_ACPTYPE', 'DVI$_ALL', 'DVI$_ALLDEVNAM', 'DVI$_ALLOCLASS', 'DVI$_ALT_HOST_AVAIL', 'DVI$_ALT_HOST_NAME', PYVMS - Python on OpenVMS PAGE 7-3 pyvms module [...] 'DVI$_VPROT', 'DVI$_WCK'] >>> values = pyvms.item_get ('$DVIDEF', 'DVI$_CYLINDERS', None) >>> type (values) >>> print values {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, 'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None, 'returns_bitmask': 0, 'item_code': 40} >>> print values['vms_version_max'] 32767 >>> values = pyvms.item_get ('$SYIDEF', 'SYI$_CHECK_CLUSTER', None) >>> print values {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 0, 'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None, 'returns_bitmask': 0, 'item_code': 8243} --> 'applies_to_alpha': 0 >>> values = pyvms.item_get ('$QUIDEF', 'QUI$_FILE_FLAGS', None) >>> print values {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, 'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None, 'returns_bitmask': 1, 'item_code': 19} >>> >>> values = pyvms.item_get ('$QUIDEF', 'QUI$_FILE_FLAGS', 1) >>> print values {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, 'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': ['QUI_M_FILE_BURST', 'QUI_M_FILE_BURST_EXP', 'QUI_M_FILE_DELETE', 'QUI_M_FILE_DELETE_ALWAYS', 'QUI_M_FILE_DOUBLE_SPACE', 'QUI_M_FILE_FLAG', 'QUI_M_FILE_FLAG_EXP', 'QUI_M_FILE_PAGE_HEADER', 'QUI_M_FILE_PAGINATE', 'QUI_M_FILE_PAGINATE_EXP', 'QUI_M_FILE_PASSALL', 'QUI_M_FILE_TRAILER', 'QUI_M_FILE_TRAILER_EXP'], 'returns_bitmask': 1, 'item_code': 19} >>> >>> bitmask_list = values['bitmask'] >>> type (bitmask_list) >>> import vms_quidef >>> bit_name = bitmask_list[1] >>> print bit_name QUI_M_FILE_BURST_EXP >>> bit_value = getattr (vms_quidef,bit_name) >>> print bit_value 2 >>> print vms_quidef.QUI_M_FILE_BURST_EXP 2 >>> PYVMS - Python on OpenVMS PAGE 7-4 pyvms module >>> item_list = pyvms.item_list ('$DVIDEF'); >>> for item_code in item_list: ... print item_code ... item_data = pyvms.item_get ('$DVIDEF', item_code, None) ... print item_data ... #end ... DVI$_ACPPID {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, 'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None, 'returns_bitmask': 0, 'item_code': 64} DVI$_ACPTYPE {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, [...] DVI$_VPROT {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, 'vms_version_min': 5520, 'vms_version_max': 32767, 'bitmask': None, 'returns_bitmask': 0, 'item_code': 18} DVI$_WCK {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1, 'vms_version_min': 5520, 'vms_version_max': 32767, 'bitmask': None, 'returns_bitmask': 0, 'item_code': 124} >>> - command history related routines >>> import pyvms >>> pyvms.history_show() 1 import pyvms 2 pyvms.history_show() >>> a=1 >>> pyvms.history_show() 1 import pyvms 2 pyvms.history_show() 3 a=1 4 pyvms.history_show() >>> list = pyvms.history_get() >>> print pyvms.history_size() >>> pyvms.history_show() 1 import pyvms 2 pyvms.history_show() 3 a=1 4 pyvms.history_show() 5 list = pyvms.history_get() 6 print pyvms.history_size() 7 pyvms.history_show() >>> print list # output is manually wrapped for RUNOFF format [('\012>>> ', 'import pyvms\012'), ('\012>>> ', 'pyvms.show_histo ry()\012'), ('\012>>> ', 'a=1\012'), ('\012>>> ', 'pyvms.show_his tory()\012'), ('\012>>> ', 'list = pyvms.history_get()\012')] >>> pyvms.history_delete(0) 9 >>> pyvms.history_show() PYVMS - Python on OpenVMS PAGE 7-5 pyvms module 1 pyvms.history_show() >>> @@ to be enhanced ------------------------------------------------------------------------ 23-MAR-1998 ZE. 7.2 vms_lbr module The 'vms_lbr' module provides access to some OpenVMS LBR$ routines. (well, at the time of writing this (10-FEB-1998) it provides only access to the OUTPUT_HELP routine...). Most routines DO NOT return a status code; they raise the exception 'vms_lbr.error' when something went wrong. Routines that behave differently have it mentioned within their description. ------------------------------------------------------------------------ Alphabetical list of routines: - OUTPUT_HELP - Output Help Messages ------------------------------------------------------------------------ ------------------------------------------------------------------------ 7.2.1 OUTPUT_HELP - Output Help Messages @@ WARNING! This routine is not fully debugged !! Format: status = vms_lbr.output_help (output_routine [,output_width] [,line_desc] [,library_name] [,flags] [,input_routine] ) Returns: status @@ Arguments: output_routine If you specify 'None', then the RTL routine LIB$PUT_OUTPUT will be used internally. output_width Width of the help-text line that is passed to the user-supplied output routine. Default is 80 characters per line. line_desc The help request line without the 'HELP' and any qualifiers. Default is the empty string. PYVMS - Python on OpenVMS PAGE 7-6 vms_lbr module library_name Name of the help library. Default is an empty string which indicates the default help library (HELPLIB). If omitted, then device and directory (SYS$HELP) and file type (.HLB) are supplied. flags Currently (01-MAR-1998), symbolic values for the flags (HLP_M_name) are not available in VMSDEF. You must find out and supply the numerical values yourself, sorry. See the OpenVMS documentation for details. input_routine If you specify 'None' or ommit this argument, then the RTL routine LIB$GET_INPUT will be used internally. Examples: >>> import vms_lbr >>> # define the output_routine >>> def fnc_out(message_string): ... print "FNC_OUT(",message_string,") called" ... return 1 ... >>> >>> # define the input_routine >>> def fnc_inp(prompt_string): ... print "FNC_INP(",prompt_string,") called" ... r = (1,"SET") ... return r ... >>> >>> # use all defaults >>> vms_lbr.output_help (None) Information available: := = @ ACCOUNTING ALLOCATE ANALYZE APPEND ... WRITE Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # supply a specific output_width >>> vms_lbr.output_help (None,40) Information available: := = @ ACCOUNTING ALLOCATE ANALYZE PYVMS - Python on OpenVMS PAGE 7-7 vms_lbr module ... WAIT WRITE Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # ?? @@ need to check this >>> vms_lbr.output_help (None,None,"DIRECTORY") Information available: := = @ ACCOUNTING ALLOCATE ANALYZE APPEND ... WRITE Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # specify help item and help library >>> vms_lbr.output_help (None,None,"DIRECTORY","HELPLIB") DIRECTORY Provides a list of files or information about a file or group of ... /WIDTH /WRAP Examples DIRECTORY Subtopic? Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # specify an additional key >>> vms_lbr.output_help (None,None,"DIRECTORY/OUTPUT","HELPLIB") DIRECTORY /OUTPUT /OUTPUT[=filespec] /NOOUTPUT Controls where the output of the command is sent. By default, ... the output file name will appear in the directory listing. PYVMS - Python on OpenVMS PAGE 7-8 vms_lbr module Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # specify an invalid key >>> vms_lbr.output_help (None,None,"DIR_ECTORY","HELPLIB") Sorry, no documentation on DIR_ECTORY Additional information available: := = @ ACCOUNTING ALLOCATE ANALYZE APPEND ... TYPE UCX UCX$TRACE UNLOCK VIEW WAIT WRITE Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # specify a different help library >>> vms_lbr.output_help (None,None,"SET","NCPHELP") SET Use the SET command to create or modify parameters or components ... Additional information available: CIRCUIT EXECUTOR PROXIES LINE LOGGING MODULE NODE OBJECT SET Subtopic? Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # use a non-existing help library >>> vms_lbr.output_help (None,None,"SET","NCP_HELP") %HELP-E-OPENIN, error opening SYS$COMMON:[SYSHLP]NCP_HELP.HLB; as input -RMS-E-FNF, file not found %TRACE-E-TRACEBACK, symbolic stack dump follows ... PYTHON main 10 00000030 00018430 276172954 <-- return status from OUTPUT_HELP >>> >>> status = 276172954 # manually assign to variable >>> # build command string >>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')' >>> command 'WRITE SYS$OUTPUT F$MESSAGE(276172954)' PYVMS - Python on OpenVMS PAGE 7-9 vms_lbr module >>> import os >>> os.system (command) %HELP-E-OPENIN, error opening !AS as input <-- [1] 65537 <-- [2] >>> [1] this is the output of 'command' [2] this is the return status from os.system() 65537 = %RMS-S-NORMAL, normal successful completion >>> # use an output routine (in Python!) >>> print vms_lbr.output_help(fnc_out,40,"","HELPLIB") FNC_OUT( ) called FNC_OUT( Information available: ) called FNC_OUT( ) called FNC_OUT( := = @ ) called FNC_OUT( ACCOUNTING ALLOCATE ANALYZE ) called ... FNC_OUT( WAIT WRITE ) called FNC_OUT( ) called Topic? 1 <-- this is the status, returned from vms_lbr.output_help() >>> >>> # use an output and an input routine (both in Python!) >>> print vms_lbr.output_help(fnc_out,40,"","HELPLIB",None,fnc_inp) FNC_OUT( ) called FNC_OUT( Information available: ) called FNC_OUT( ) called FNC_OUT( := = @ ) called FNC_OUT( ACCOUNTING ALLOCATE ANALYZE ) called ... FNC_OUT( WAIT WRITE ) called FNC_OUT( ) called vms_lbr__input_routine:ar_prompt_string->dsc$a_ptr=2146335280 vms_lbr__input_routine:ar_resultant_string->dsc$w_length=512 vms_lbr__input_routine:ar_resultant_string->dsc$a_ptr=2146336892 FNC_INP( Topic? ) called inp:str=SET= vms_lbr__input_routine:ar_resultant_string=SET vms_lbr__input_routine:l_status=-1 FNC_OUT( ) called FNC_OUT( SET ) called FNC_OUT( Sorry, no documentation on SET ?AII ) called FNC_OUT( )IOI ) ,II ) ) called *INTERRUPT* $ STOP @@ Obviously there is a bug, here ... ------------------------------------------------------------------------ 08-MAR-1998 ZE. PYVMS - Python on OpenVMS PAGE 7-10 vms_lib module 7.3 vms_lib module The 'vms_lib' module provides access to some OpenVMS LIB$ routines. Most routines DO NOT return a status code; they raise the exception 'vms_lib.error' when something went wrong. Routines that behave differently have it mentioned within their description. ------------------------------------------------------------------------ Alphabetical list of routines: - ADD_TIMES - Add Two Quadword Times - ASN_WTH_MBX - Assign Channel with Mailbox - ATTACH - Attach Terminal to Process - CREATE_DIR - Create a Directory - CURRENCY - Get System Currency Symbol - CVT_VECTIM - Convert 7-Word Vector to Internal Time - DATE_TIME - Date and Time Returned as a String - DAY - Day Number Returned as a Longword Integer - DAY_OF_WEEK - Show Numeric Day of Week - DELETE_LOGICAL - Delete Logical Name - DELETE_SYMBOL - Delete CLI Symbol - DIGIT_SEP - Get Digit Separator Symbol - DO_COMMAND - Execute Command - FID_TO_NAME - Convert Device and File ID to File Specification - FIND_IMAGE_SYMBOL - Find Universal Symbol in Shareable Image File - FREE_EF - Free Event Flag - GETDVI - Get Device/Volume Information - GETJPI - Get Job/Process Information - GETQUI - Get Queue Information - GETSYI - Get Systemwide Information - GET_COMMAND - Get Line from SYS$COMMAND - GET_COMMON - Get String from Common - GET_EF - Get Event Flag - GET_FOREIGN - Get Foreign Command Line - GET_SYMBOL - Get Value of CLI Symbol - GET_USERS_LANGUAGE - Return the User's Language - LP_LINES - Lines on Each Printer Page - PUT_COMMON - Put String to Common - PUT_OUTPUT - Put Line to SYS$OUTPUT - RADIX_POINT - Radix Point Symbol - RESERVE_EF - Reserve Event Flag - RUN_PROGRAM - Run New Program - SET_LOGICAL - Set Logical Name - SET_SYMBOL - Set Value of CLI Symbol - SUB_TIMES - Subtract Two Quadword Times - WAIT - Wait a Specified Period of Time ------------------------------------------------------------------------ ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-11 vms_lib module 7.3.1 ADD_TIMES - Add Two Quadword Times Format: resultant_time = vms_lib.add_times (time1, time2) Returns: resultant_time 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Arguments: time1 + time2 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_lib >>> import vms_sys # needed for ascii/integer conversion >>> time1 = vms_sys.bintim ('29-FEB-2000 12:34:56.78') >>> print time1 44585444967800000L >>> time2 = vms_sys.bintim ('0 01:02:03.11') >>> print time2 -37231100000L >>> resultant_time = vms_lib.add_times (time1, time2) >>> print resultant_time 44585482198900000L >>> vms_sys.asctim (resultant_time); '29-FEB-2000 13:36:59.89' >>> vms_sys.asctim (time1); '29-FEB-2000 12:34:56.78' >>> resultant_time = vms_lib.add_times (time1, time1) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410020, '%LIB-F-ONEDELTIM, at least one delta time\ is required') >>> vms_sys.asctim (time2); ' 0 01:02:03.11' >>> resultant_time = vms_lib.add_times (time2, time2) >>> print resultant_time -74462200000L >>> vms_sys.asctim (resultant_time); ' 0 02:04:06.22' PYVMS - Python on OpenVMS PAGE 7-12 vms_lib module >>> resultant_time = vms_lib.add_times ('X', time2) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> resultant_time = vms_lib.add_times (time1, 'X') Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: must be long int >>> resultant_time = vms_lib.add_times () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 2 arguments; 0 given >>> resultant_time = vms_lib.add_times (time1, 2) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: must be long int >>> ------------------------------------------------------------------------ 7.3.2 ASN_WTH_MBX - Assign Channel with Mailbox Format: device-channel, mailbox-channel= vms_lib.asn_wth_mbx \ (device-name, [maximum-message-size] [,buffer-quota]) Returns: device-channel channel to device, received from SYS$ASSIGN mailbox-channel channel to mailbox, received from SYS$CREMBX Arguments: device-name name of device that will be passed to SYS$ASSIGN maximum-message-size maximum message size that can be sent to the mailbox buffer-quota number of system dynamic memory bytes that can be used to buffer messages sent to the mailbox Examples: >>> import vms_lib PYVMS - Python on OpenVMS PAGE 7-13 vms_lib module >>> devchn, mbxchn = vms_lib.asn_wth_mbx ("TT") >>> print devchn, mbxchn 240 224 >>> print vms_lib.getdvi ("DVI$_DEVNAM", devchn) _FTA13: >>> print vms_lib.getdvi ("DVI$_DEVNAM", mbxchn) _MBA233: (Note: the device name argument is ommited in vms_lib.getdvi()) $ show device/full _MBA233: Device MBA233: is online, record-oriented device, shareable, mailbox device. Error count 0 Operations completed 0 Owner process "" Owner UIC [HOME,ZESSIN] Owner process ID 00000000 Dev Prot S:RWPL,O:RWPL,G,W Reference count 2 Default buffer size 256 >>> devchn, mbxchn = vms_lib.asn_wth_mbx("TT",44,33) >>> print devchn, mbxchn 240 224 >>> print vms_lib.getdvi ("DVI$_DEVNAM", mbxchn) _MBA241: >>> $ show device/full _MBA241: Device MBA241: is online, record-oriented device, shareable, mailbox device. Error count 0 Operations completed 0 Owner process "" Owner UIC [HOME,ZESSIN] Owner process ID 00000000 Dev Prot S:RWPL,O:RWPL,G,W Reference count 2 Default buffer size 44 ** >>> # 1st call >>> devchn, mbxchn = vms_lib.asn_wth_mbx("TT") >>> # 2nd call >>> devchn, mbxchn = vms_lib.asn_wth_mbx("TT") Traceback (innermost last): File "", line 1, in ? vms_lib.error: (708, '%SYSTEM-F-DEVACTIVE, device is active') >>> devchn, mbxchn = vms_lib.asn_wth_mbx("NO_SUCH_DEV") Traceback (innermost last): File "", line 1, in ? vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name') >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-14 vms_lib module 7.3.3 ATTACH - Attach Terminal to Process Format: vms_lib.attach (process_id) Returns: None Arguments: process_id Identification of process to which the process should be attached. The PID must be a number, not a hex-string! Examples: >>> import vms_lib >>> vms_lib.attach (232) %DCL-S-RETURNED, control returned to process USERNAME $ ATTACH /IDENTIFICATION=%X2E0 ! get back to Python >>> >>> # a PID must be a number within Python >>> vms_lib.attach ('%XE8') Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> # a PID for a process that does not exist >>> vms_lib.attach(99999) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> # process does exist, but is not in current process' tree >>> vms_lib.attach(1124) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409940, '%LIB-F-ATTREQREF, attach request refused') >>> vms_lib.attach () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given >>> vms_lib.attach (None) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> PYVMS - Python on OpenVMS PAGE 7-15 vms_lib module ------------------------------------------------------------------------ 7.3.4 CREATE_DIR - Create a Directory @@ Oops, left out - will be filled in, later Format: LIB$CREATE_DIR device-directory-spec [,owner-UIC] [,protection-enable] [,protection-value] [,maximum-versions] [,relative-volume-number] ------------------------------------------------------------------------ 7.3.5 CURRENCY - Get System Currency Symbol Format: currency_string = vms_lib.currency () Returns: currency_string The value of the logical name 'SYS$CURRENCY' or, if the translation fails the default currency symbol ($). Arguments: vms_lib.currency() does not take any arguments. Examples: >>> import vms_lib >>> currency_string = vms_lib.currency() >>> currency_string '$' $ DEFINE SYS$CURRENCY "C&" >>> vms_lib.currency() 'C&' * don't forget to use '$ DEASSIGN SYS$CURRENCY' ! >>> vms_lib.currency('S') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> PYVMS - Python on OpenVMS PAGE 7-16 vms_lib module ------------------------------------------------------------------------ 7.3.6 CVT_VECTIM - Convert 7-Word Vector to Internal Time Format: resultant_time = vms_lib.cvt_vectim (input_time) Returns: resultant_time 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Arguments: input_time a tuple that consists of: (year, month, day, hour, minute, second, hundredth) Examples: >>> import vms_lib >>> input_time = (2000, 2, 29, 12, 34, 56, 78) >>> resultant_time = vms_lib.cvt_vectim (input_time) >>> print resultant_time 44585444967800000L >>> import vms_sys >>> print vms_sys.asctim (resultant_time) 29-FEB-2000 12:34:56.78 >>> resultant_time = vms_lib.cvt_vectim ((2000, 2, 29, 12, 34, 56, 78)) >>> print vms_sys.asctim (resultant_time) 29-FEB-2000 12:34:56.78 >>> # a tuple is required as argument 1 - not seven arguments >>> resultant_time = vms_lib.cvt_vectim (2000, 2, 29, 12, 34, 56, 78) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 7 given >>> >>> # wrong order of arguments >>> input_time = (78,56,34,12,29,2,2000) >>> resultant_time = vms_lib.cvt_vectim (input_time) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410012, '%LIB-F-IVTIME, invalid time passed in,\ or computed') >>> PYVMS - Python on OpenVMS PAGE 7-17 vms_lib module >>> # tuple too small #1, #2, #3, #4, #5, #6 7? >>> resultant_time = vms_lib.cvt_vectim ((2000, 2, 29, 12, 34, 56)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: must be a tuple of 7 integers >>> >>> # tuple element 2 out of range ------------vvvvv >>> resultant_time = vms_lib.cvt_vectim ((2000,65536,29,12,34,56,78)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: tuple-element:n is not a 16-bit integer >>> >>> # tuple element 2 is invalid ---------------v >>> resultant_time = vms_lib.cvt_vectim ((2000,'X',29,12,34,56,78)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: tuple-element:n is not an integer >>> ------------------------------------------------------------------------ 7.3.7 DATE_TIME - Date and Time Returned as a String Format: date_time_string = vms_lib.date_time () Returns: date_time_string Returns the date current date and time as a 23 character string. Format: 'dd-mmm-yyyy hh:mm:ss.hh'. Arguments: vms_lib.date_time() does not take any arguments. Examples: >>> import vms_lib >>> date_time_string = vms_lib.date_time () >>> date_time_string ' 2-NOV-1997 16:23:21.93' * Note that there can be a space character at the begin! >>> vms_lib.date_time () '15-MAR-1996 22:12:31.48' PYVMS - Python on OpenVMS PAGE 7-18 vms_lib module >>> vms_lib.date_time ('S') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ 7.3.8 DAY - Day Number Returned as a Longword Integer Format: number_of_days, day_time = vms_lib.day ([user-time]) Returns: number_of_days The number of days since the system zero date ('17-NOV-1858 00:00:00.00'). day_time The number of 10-millisecond units since midnight of the user_time argument. Arguments: user-time 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. If the argument is not present, then the current date + time is used. Examples: >>> import vms_lib >>> import vms_sys >>> binary_time = vms_sys.bintim ('29-FEB-2000 01:02:03.04') >>> binary_time 44585029230400000L >>> number_of_days, day_time = vms_lib.day (binary_time) >>> number_of_days 51603 >>> day_time 372304 >>> vms_lib.day (binary_time) (51603, 372304) >>> vms_lib.day (vms_sys.gettim ()) (51037, 5151320) PYVMS - Python on OpenVMS PAGE 7-19 vms_lib module >>> vms_lib.day () (51037, 5152244) >>> vms_lib.day (None) (51037, 5153719) >>> vms_lib.day ('A') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> vms_lib.day ('A','B') Traceback (innermost last): File "", line 1, in ? TypeError: function requires at most 1 argument; 2 given >>> ------------------------------------------------------------------------ 7.3.9 DAY_OF_WEEK - Show Numeric Day of Week Format: day_number = vms_lib.day_of_week ([user-time]) Returns: day_number Numeric day of week. 1 = Monday through 7 = Sunday Arguments: user-time 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. If the argument is not present, then the current date + time is used. Examples: >>> import vms_lib >>> import vms_sys >>> weekday_list = [0,'Monday','Tuesday','Wednesday','Thursday', ... 'Friday','Saturday','Sunday'] >>> binary_time = vms_sys.bintim ('29-FEB-2000 01:02:03.04') >>> binary_time 44585029230400000L PYVMS - Python on OpenVMS PAGE 7-20 vms_lib module >>> vms_lib.day_of_week (binary_time) 2 >>> day_number = vms_lib.day_of_week (binary_time) >>> day_number 2 >>> print weekday_list[day_number] Tuesday $ WRITE SYS$OUTPUT F$CVTIME("29-FEB-2000 01:02:03.04",,"WEEKDAY") Tuesday $ WRITE SYS$OUTPUT F$TIME() 12-AUG-1998 14:54:54.50 $ WRITE SYS$OUTPUT F$CVTIME(F$TIME(),,"WEEKDAY") Wednesday >>> vms_lib.day_of_week (vms_sys.gettim ()) 3 >>> vms_lib.day_of_week () 3 >>> vms_lib.day_of_week (None) 3 >>> vms_lib.day_of_week ('A') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> vms_lib.day_of_week ('A', 'B') Traceback (innermost last): File "", line 1, in ? TypeError: function requires at most 1 argument; 2 given >>> ------------------------------------------------------------------------ 7.3.10 DELETE_LOGICAL - Delete Logical Name Format: vms_lib.delete_logical (logical-name [,table-name]) Returns: None Arguments: logical-name The logical name to be deleted. PYVMS - Python on OpenVMS PAGE 7-21 vms_lib module table-name Logical name table from which the logical name is to be deleted. This parameter is optional. The default value is "LNM$PROCESS" which indicates the process logical name table. Examples: $ DEFINE /PROCESS LNM_PROCESS "process" $ DEFINE /PROCESS LNM_DEFAULT "default" $ DEFINE /PROCESS LNM_NONE "none" $ DEFINE /JOB LNM_JOB "job" $ SHOW LOGICAL LNM_* (LNM$PROCESS_TABLE) "LNM_DEFAULT" = "default" "LNM_NONE" = "none" "LNM_PROCESS" = "process" (LNM$JOB_8152D800) "LNM_JOB" = "job" (LNM$GROUP_010040) (LNM$SYSTEM_TABLE) (DECW$LOGICAL_NAMES) $ >>> import vms_lib >>> vms_lib.delete_logical ('LNM_PROCESS', 'LNM$PROCESS') >>> vms_lib.delete_logical ('LNM_JOB', 'LNM$JOB') >>> vms_lib.delete_logical ('LNM_NONE', None) >>> vms_lib.delete_logical ('LNM_DEFAULT') $ SHOW LOGICAL LNM_* (LNM$PROCESS_TABLE) (LNM$JOB_8152D800) (LNM$GROUP_010040) (LNM$SYSTEM_TABLE) (DECW$LOGICAL_NAMES) %SHOW-S-NOTRAN, no translation for logical name LNM_* $ PYVMS - Python on OpenVMS PAGE 7-22 vms_lib module >>> logical_name = 'S' * 257 >>> vms_lib.delete_logical (logical_name) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') >>> >>> vms_lib.delete_logical ('NO_LOGICAL') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (444, '%SYSTEM-F-NOLOGNAM, no logical name match') >>> >>> vms_lib.delete_logical ('NO_LOGICAL','NO_TABLE') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (444, '%SYSTEM-F-NOLOGNAM, no logical name match') >>> >>> vms_lib.delete_logical () Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 1 argument; 0 given >>> >>> vms_lib.delete_logical (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, int found >>> ------------------------------------------------------------------------ 7.3.11 DELETE_SYMBOL - Delete CLI Symbol Format: vms_lib.delete_symbol (symbol [,table-type-indicator]) Returns: None Arguments: symbol Name of the symbol to be deleted. table-type-indicator "GLOBAL" or "LOCAL", this is _not_ a numeric value as in LIB$DELETE_SYMBOL but a clear text name. This parameter is optional. The default value is "LOCAL". PYVMS - Python on OpenVMS PAGE 7-23 vms_lib module Examples: >>> import vms_lib $ VMS_LIB_SYM_DEFAULT = "VALUE_DEFAULT" $ VMS_LIB_SYM_NONE = "VALUE_NONE" $ VMS_LIB_SYM_GLOBAL == "VALUE_GLOBAL" $ VMS_LIB_SYM_LOCAL = "VALUE_LOCAL" >>> vms_lib.delete_symbol ('VMS_LIB_SYM_GLOBAL', 'GLOBAL') >>> vms_lib.delete_symbol ('VMS_LIB_SYM_LOCAL', 'LOCAL') >>> vms_lib.delete_symbol ('VMS_LIB_SYM_NONE', None) >>> vms_lib.delete_symbol ('VMS_LIB_SYM_DEFAULT') $ show symbol VMS_LIB_SYM_* %DCL-W-UNDSYM, undefined symbol - check validity and spelling $ >>> # maximum length of symbol name is 255 characters >>> symbol_name = 'S' * 256 >>> vms_lib.delete_symbol (symbol_name, 'GLOBAL') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name') >>> >>> vms_lib.delete_symbol ('SYMBOL', 'BAD') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> >>> vms_lib.delete_symbol ('NON_EXIST_SYMBOL', 'GLOBAL') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409892, '%LIB-F-NOSUCHSYM, no such symbol') >>> >>> vms_lib.delete_symbol (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, int found >>> >>> vms_lib.delete_symbol () Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 1 argument; 0 given >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-24 vms_lib module 7.3.12 DIGIT_SEP - Get Digit Separator Symbol Format: digit_separator = vms_lib.digit_sep () Returns: digit_separator The digit separator symbol as returned by LIB$DIGIT_SEP. Arguments: vms_lib.digit_sep() does not take any arguments. Examples: >>> import vms_lib >>> digit_sep_symbol = vms_lib.digit_sep () >>> digit_sep_symbol ',' $ DEFINE SYS$DIGIT_SEP "C&" >>> vms_lib.digit_sep() 'C&' * don't forget to use '$ DEASSIGN SYS$DIGIT_SEP' ! >>> vms_lib.digit_sep ('S') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> >>> vms_lib.digit_sep (None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ 7.3.13 DO_COMMAND - Execute Command This routine immediately stops the program executing (Python). Python is not able to do any cleanup! Format: vms_lib.do_command (command-string) PYVMS - Python on OpenVMS PAGE 7-25 vms_lib module Returns: There is no data returned. DO_COMMAND will terminate the current Python session and then execute 'command-string'! However, when something is wrong, then do_command() raises an exception - see the examples below. Arguments: command-string The DCL command string. Its length is limited to 255 characters. Otherwise the exception 'vms_lib.error' is raised. Examples: >>> import vms_lib >>> vms_lib.do_command ('SHOW TIME') 15-MAR-1996 20:37:25 $! Python was left and then the DCL command executed >>> command_string = 'C' * 257 >>> vms_lib.do_command (command_string) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> # an exception was raised, but Python was not aborted, here >>> vms_lib.do_command ('INVALID_COMMAND') %DCL-W-IVVERB, unrecognized command verb - check validity and spelling \INVALID_COMMAND\ $! Python was left although the DCL command is invalid! ------------------------------------------------------------------------ 7.3.14 FID_TO_NAME - Convert Device and File ID to File Specification Please note that You MUST check status and/or acp_status because FID_TO_NAME() does NOT raise an exception when something goes wrong! Format: status, acp_status, filespec = \ vms_lib.fid_to_name (device_name, file_id [,directory_id]) Returns: status The return-status from LIB$FID_TO_NAME. acp_status The status resulting from traversing the backward links. PYVMS - Python on OpenVMS PAGE 7-26 vms_lib module filespec The resulting file specification string. Arguments: device_name Name of the device on which the file resides. (64 characters or less!) file_id The file identifier. This is a tuple of 3 (16-bit) integers. directory_id The directory file identifier. Please read the description of LIB$FID_TO_NAME for details. Examples: $ COPY _NLA0: TEST.TMP $ DIRECTORY /FILE_ID TEST.TMP Directory DKA100:[PYTHON.PYTHON-1_5.VMS] TEST.TMP;1 (12621,13,0) Total of 1 file. $ python ... (Python's banner ommitted) ... >>> import vms_lib >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,13,0)) >>> print status, acp_status, filespec 1 1 DISK$D1:[PYTHON.PYTHON-1_5.VMS]TEST.TMP;1 >>> import os >>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')' >>> os.system (command) %SYSTEM-S-NORMAL, normal successful completion <-- [1] 65537 <-- [2] >>> [1] this is the output of 'command' [2] this is the return status from os.system() 65537 = %RMS-S-NORMAL, normal successful completion >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,13,999)) >>> print status, acp_status, filespec 2456 2456 DISK$D1: >>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')' >>> os.system (command) %SYSTEM-W-NOTVOLSET, volume is not part of a volume set 65537 >>> PYVMS - Python on OpenVMS PAGE 7-27 vms_lib module >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,999,0)) >>> print status, acp_status, filespec 2320 2320 DISK$D1: >>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')' >>> os.system (command) %SYSTEM-W-NOSUCHFILE, no such file 65537 >>> >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,99999,0)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: tuple-element:n is not a 16-bit integer >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,'X',0)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: tuple-element:n is not an integer >>> status, acp_status, filespec = vms_lib.fid_to_name ('DKA100:', 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: must be a tuple of 3 integers >>> >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,13,0), (12621,99,0)) >>> print status, acp_status, filespec >>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')' >>> os.system (command) %SYSTEM-W-NOSUCHFILE, no such file 1 >>> ------------------------------------------------------------------------ 7.3.15 FIND_IMAGE_SYMBOL - Find Universal Symbol in Shareable Image File Any signals from LIB$FIND_IMAGE_SYMBOL are trapped by an internal condition handler and then are converted to a condition value which is returned in 'status'. An error does _not_ raise a Python exception - you _must_ check 'status'! Please note, that there is currently (23-MAY-1998) no way to CALL a routine in a shareable image that has been mapped by LIB$FIND_IMAGE_SYMBOL. Format: PYVMS - Python on OpenVMS PAGE 7-28 vms_lib module symbol_value, status = \ vms_lib.find_image_symbol (filename, symbol [,image_name]) Returns: symbol_value the value that LIB$FIND_IMAGE_SYMBOL has located status condition value that is returned from LIB$FIND_IMAGE_SYMBOL Arguments: filename only the name of a file specification no device, type, version symbol name of the symbol to look up image_name remaining parts of the file specification default = 'SYS$SHARE:.EXE' Examples: >>> import vms_lib >>> symbol_value, status = vms_lib.find_image_symbol ( ... 'EDTSHR', 'EDT$_NONSTDFIL') >>> print symbol_value, status 8749395 1 >>> $ SEARCH SYS$MESSAGE:*.EXE NONSTDFIL /WINDOW=0 SYS$COMMON:[SYSMSG]SHRIMGMSG.EXE;1 $! --> these messages are shared by several facilities $ SET MESSAGE SYS$COMMON:[SYSMSG]SHRIMGMSG.EXE;1 $ WRITE SYS$OUTPUT F$MESSAGE(8749395) %EDT-I-NONSTDFIL, Input file does not have standard text file format $ @@ no more tests done, yet (01-MAR-1998) @@ ------------------------------------------------------------------------ 7.3.16 FREE_EF - Free Event Flag Format: vms_lib.free_ef (event_flag_number) Returns: None PYVMS - Python on OpenVMS PAGE 7-29 vms_lib module Arguments: event_flag_number number of the event flag to be freed Examples: >>> import vms_lib >>> # event flags 1 - 23 are initially reserved >>> # (compatibility to the RSX operating system) >>> print vms_lib.free_ef (1) None >>> print vms_lib.free_ef (1) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409692, '%LIB-F-EF_ALRFRE, event flag already free') >>> >>> # event flags 24 - 31 are reserved to OpenVMS >>> print vms_lib.free_ef (24) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409708, '%LIB-F-EF_RESSYS, event flag reserved to system') >>> >>> # event flags 32 - 63 are initially free >>> print vms_lib.free_ef (32) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409692, '%LIB-F-EF_ALRFRE, event flag already free') >>> ------------------------------------------------------------------------ 7.3.17 GETDVI - Get Device/Volume Information Format: import vms_dvidef, vms_lib item_value = vms_lib.getdvi \ (item_name, channel_number [,device_name]) Returns: item_value Return information requested from 'item_name'. Note: this can be an integer _or_ a string value. 'Boolean' values (TRUE/FALSE) are returned as integers 1/0. Arguments: PYVMS - Python on OpenVMS PAGE 7-30 vms_lib module item_name Text-string of item to retrieve (e.g. 'DVI$_OWNUIC'). channel_number I/O channel, assigned to the device about which the information should be retrieved. Use 'None' to skip the channel parameter and use device_name instead. device_name Name of device to get information about. Note: normally channel_number overrides device_name! Use channel_number = 'None' to force usage of device_name. Examples: >>> import vms_lib >>> vms_lib.getdvi ("DVI$_OWNUIC",None,"DKA100:") '[G1,SYSTEM]' >>> vms_lib.getdvi ("DVI$_LOGVOLNAM",None,"DKA100:") 'DISK$D1' >>> vms_lib.getdvi ("DVI$_FREEBLOCKS",None,"DKA100:") 528888 >>> vms_lib.getdvi ("DVI$_FREEBLOCKS",32,None) 528888 >>> vms_lib.getdvi ("DVI$_FREEBLOCKS",32) 528888 * 32 is a channel number that was learned via SDA> show process/channel >>> used_blocks = vms_lib.getdvi ("DVI$_MAXBLOCK",None,"DKA100:") - \ ... vms_lib.getdvi ("DVI$_FREEBLOCKS",None,"DKA100:") >>> used_blocks 1562256 >>> vms_lib.getdvi ("DVI$_TT_HOSTSYNC",None,"SYS$COMMAND:") 1 <-- means TRUE >>> vms_lib.getdvi ("DVI$_TT_DIALUP",None,"SYS$COMMAND:") 0 <-- means FALSE >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,"SYS$COMMAND:") '_HERE$FTA10:' >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,"NO_DEVICE") Traceback (innermost last): File "", line 1, in ? vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name') >>> vms_lib.getdvi ("INVALID_ITEM",None,"SYS$COMMAND:") Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: unknown DVI$_ item code >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",'X',"SYS$COMMAND:") PYVMS - Python on OpenVMS PAGE 7-31 vms_lib module Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: channel number must be integer or None >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,None) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (316, '%SYSTEM-F-IVCHAN, invalid I/O channel') >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: device_name must be string or None >>> vms_lib.getdvi ('DVI$_LOGVOLNAM',None,sys) Traceback (innermost last): File "", line 1, in ? TypeError: device_name must be string or None >>> ------------------------------------------------------------------------ 7.3.18 GETJPI - Get Job/Process Information Note: the 'vms_jpidef' module contains constants and bitmasks that are defined in '$JPIDEF'. Access to the item-codes ("JPI$_name") is possible via the 'pyvms' module. Format: ctx_out, item_value = \ vms_lib.getjpi (item_name, pid_ctx [,process_name]) Returns: ctx_out pid of the target process or a pid-context that can be used for the next step in a wildcard lookup item_value Return information requested from 'item_name'. Note: all items are returned as string values _except_ for item 'PID' which is always returned as integer. This eases wildcard lookups and other usages. Arguments: item_name Text-string of item to retrieve (e.g. 'JPI$_BIOLM'). pid_ctx PID of process to lookup or context-value for the next wildcard lookup. process_name PYVMS - Python on OpenVMS PAGE 7-32 vms_lib module Name of process to lookup. Note: normally pid_ctx overrides process_name! Use pid_ctx = 'None' to force usage of process_name. Examples: >>> import vms_lib >>> pid, state = vms_lib.getjpi ('JPI$_STATE',0) >>> pid, state (232, 'CUR') >>> vms_lib.getjpi ('JPI$_PRCNAM',65) (65, 'SWAPPER') >>> vms_lib.getjpi ('JPI$_PID',None,'DEST_PROC') (1058, 1058) >>> vms_lib.getjpi ('JPI$_PRCNAM',1058) (1058, 'DEST_PROC') >>> vms_lib.getjpi ('JPI$_PID',1234) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_lib.getjpi ('JPI$_PID',sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: process_id must be integer or None >>> vms_lib.getjpi ('JPI$_PID',None,None) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') >>> vms_lib.getjpi ('JPI$_PID',None,sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: process_name must be string or None >>> vms_lib.getjpi ('JPI$_PID',None,1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: process_name must be string or None *** example of wildcard lookup *** >>> ctx = -1 >>> while 1: ... ctx,pid = vms_lib.getjpi ('JPI$_PID',ctx) ... x,pn = vms_lib.getjpi ('JPI$_PRCNAM',pid) ... x,li = vms_lib.getjpi ('JPI$_LOGINTIM',pid) ... print ctx,pid,pn,li,'\n' PYVMS - Python on OpenVMS PAGE 7-33 vms_lib module ... #-while ... -65535 65 SWAPPER 17-NOV-1858 00:00:00.00 -65531 69 IPCACP 10-MAR-1996 13:23:00.36 -65530 70 ERRFMT 10-MAR-1996 13:23:02.14 [...] -65527 73 JOB_CONTROL 10-MAR-1996 13:23:08.72 -65526 74 QUEUE_MANAGER 10-MAR-1996 13:23:09.25 -65525 75 SECURITY_SERVER 10-MAR-1996 13:23:12.84 Traceback (innermost last): File "", line 2, in ? vms_lib.error: (2472, '%SYSTEM-W-NOMOREPROC, no more processes') >>> The date of 10-MAR-1996 is not faked! This really is one of the oldest examples. ------------------------------------------------------------------------ 7.3.19 GETQUI - Get Queue Information Note: the 'vms_quidef' module contains constants and bitmasks that are defined in '$QUIDEF'. Access to the item-codes ("QUI$_name") is possible via the 'pyvms' module. Format: import vms_quidef, vms_lib result = vms_lib.getqui (function_code, item_name, \ search_number, search_name, search_flags) Returns: result Return information requested from 'item_name'. Arguments: function_code Text-string of function to perform (e.g. 'QUI$_CANCEL_OPERATION' or 'QUI$_DISPLAY_ENTRY'). item_name Text-string of item to retrieve (e.g. 'QUI$_JOB_NAME'). search_number Numeric value (e.g. an entry number) used to process the request. Use 'None' to signal an empty parameter. search_name Character string (e.g. a queue name) used to process the request. PYVMS - Python on OpenVMS PAGE 7-34 vms_lib module search_flags Optional bit mask. Constants are containted in the vms_quidef module (e.g. vms_quidef.QUI_M_SEARCH_ALL_JOBS). Examples: >>> import vms_quidef, vms_lib >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_JOB_NAME",5) 'X2' >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_PRIORITY",5) 100 >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_NOTE",5) '' >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_QUEUE_NAME",5) 'HERE_BACKUP' >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_MANAGER_NAME", ... None,"HERE_SYSTEM") 'SYS$QUEUE_MANAGER' >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_PENDING_JOB_COUNT", ... None,"HERE_SYSTEM") 0 >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_PENDING_JOB_COUNT", ... None,"UUCP_BATCH") 2 >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_AUTOSTART_ON",None, ... "HERE_SYSTEM") '' >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_NOTE",9999) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (295386, '%JBC-E-NOSUCHENT, no such entry') >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_PENDING_JOB_COUNT", ... None,"NO-QUEUE") Traceback (innermost last): File "", line 1, in ? vms_lib.error: (294970, '%JBC-E-NOSUCHQUE, no such queue') >>> vms_lib.getqui ("BAD-FUNCTION") Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: unknown QUI$_ function code >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","BAD-ITEM") Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: unknown QUI$_ item code >>> vms_lib.getqui ("QUI$_NOTE","QUI$_NOTE",None) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: not a QUI$_ request function code PYVMS - Python on OpenVMS PAGE 7-35 vms_lib module >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_DISPLAY_QUEUE",None) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: wrong QUI$_ item name for this argument >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_MANAGER_NAME",sys, ... "HERE_SYSTEM") Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: search_number must be number or None *** example of wildcard lookup *** >>> import vms_quidef, vms_lib >>> vms_lib.getqui ("QUI$_CANCEL_OPERATION") >>> while 1: ... queue_name = '' ... try: ... queue_name = vms_lib.getqui("QUI$_DISPLAY_QUEUE", ... "QUI$_QUEUE_NAME",None,'*') ... except vms_lib.error: ... break ... queue_desc = vms_lib.getqui("QUI$_DISPLAY_QUEUE", ... "QUI$_QUEUE_DESCRIPTION",None,'*', ... vms_quidef.QUI_M_SEARCH_FREEZE_CONTEXT) ... print 'Queue:', queue_name, '<', queue_desc, '>' ... while 1: ... try: ... js = vms_lib.getqui("QUI$_DISPLAY_JOB", ... "QUI$_JOB_STATUS",-1,'*', ... vms_quidef.QUI_M_SEARCH_ALL_JOBS) ... except vms_lib.error: ... break ... jn = vms_lib.getqui("QUI$_DISPLAY_JOB", ... "QUI$_JOB_NAME",-1,'*', ... vms_quidef.QUI_M_SEARCH_ALL_JOBS+ ... vms_quidef.QUI_M_SEARCH_FREEZE_CONTEXT) ... en = vms_lib.getqui("QUI$_DISPLAY_JOB", ... "QUI$_ENTRY_NUMBER",-1,'*', ... vms_quidef.QUI_M_SEARCH_ALL_JOBS+ ... vms_quidef.QUI_M_SEARCH_FREEZE_CONTEXT) ... print 'Job:', jn, '(', en, ')' ... #end ... Queue: BATQ_BACKUP < > Queue: BATQ_BATCH < > Job: Q ( 833 ) Job: Q ( 834 ) Queue: BATQ_RAYTRACE01 < > Queue: BATQ_RAYTRACE02 < > Queue: BATQ_SYSTEM < > Job: Q ( 832 ) Queue: HERE_BACKUP < > Queue: HERE_BATCH < > PYVMS - Python on OpenVMS PAGE 7-36 vms_lib module Queue: HERE_RAYTRACE01 < Raytracing, PRIO:1 > Queue: HERE_RAYTRACE02 < Raytracing, PRIO:2 > Queue: HERE_SYSTEM < > Queue: UUCP_BATCH < UUCP Daemons and Administrative Processing > Job: UUXQT_BATCH ( 753 ) Job: UUXQT_BATCH ( 761 ) Job: UUXQT_BATCH ( 784 ) >>> vms_lib.getqui("QUI$_CANCEL_OPERATION") >>> vms_lib.getqui("QUI$_CANCEL_OPERATION") >>> queue_name = vms_lib.getqui("QUI$_DISPLAY_QUEUE", ... "QUI$_QUEUE_NAME",None,'*') >>> queue_name = vms_lib.getqui("QUI$_DISPLAY_QUEUE", ... "QUI$_QUEUE_NAME",None,'*') >>> print 'Queue:', queue_name, '<', queue_desc, '>' Queue: BATQ_BATCH < > >>> # (queue does not have a description) >>> vms_lib.getqui ("QUI$_CANCEL_OPERATION") >>> ------------------------------------------------------------------------ 7.3.20 GETSYI - Get Systemwide Information Note: the 'vms_syidef' module contains constants and bitmasks that are defined in '$SYIDEF'. Access to the item-codes ("SYI$_name") is possible via the 'pyvms' module. @@ As of 01-MAR-1998 this function has not been tested in a VMScluster. Format: import vms_syidef, vms_lib ctx_out, item_value = vms_lib.getsyi (item_name, \ csid_ctx [,node_name]) Returns: csid_ctx cluster system id (CSID) of nodename or a csid-context that can be used for the next step in a wildcard lookup item_value Return information requested from 'item_name'. Note: whenever possible items are returned as integer values. This eases wildcard lookups and other usages. 'Boolean' values (TRUE/FALSE) are returned as integers 1/0. Arguments: item_name Text-string of item to retrieve (e.g. 'SYI$_NODENAME'). csid_ctx PYVMS - Python on OpenVMS PAGE 7-37 vms_lib module cluster system id (CSID) of nodename to lookup or context-value for the next wildcard lookup. node_name Name of node to retrieve information from. Note: normally csid_ctx overrides node_name! Use csid_ctx = 'None' to force usage of node_name. Examples: >>> import vms_syidef, vms_lib >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',0) >>> csid, item (0, 'HERE') >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,'HERE') (-2, 'HERE') >>> vms_lib.getsyi ("SYI$_PAGFILCNT",0) (0, 4) >>> vms_lib.getsyi ("SYI$_NODE_SWTYPE",0) (0, 'VMS ') >>> vms_lib.getsyi ("SYI$_VERSION",0) (0, 'V6.1 ') >>> vms_lib.getsyi ("SYI$_RMS_GBLBUFQUO",0) (0, 1024) >>> vms_lib.getsyi (sys,0) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, module found >>> vms_lib.getsyi ("SYI$_RMS_GBLBUFQUO",sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: cluster system id must be number or None >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: expected string, module found >>> ------------------------------------------------------------------------ 7.3.21 GET_COMMAND - Get Line from SYS$COMMAND Format: data_from_command, resultant_length = \ PYVMS - Python on OpenVMS PAGE 7-38 vms_lib module vms_lib.get_command ([prompt] [,buffer_length]) Returns: data_from_command String that LIB$GET_COMMAND gets from SYS$COMMAND. resultant_length Length of 'data_from_command'. Arguments: prompt Prompt message to be displayed. Optional. buffer_length This argument is optional, default=65535. By specifying buffer_length you can limit the input that LIB$GET_COMMAND accepts. If string truncation occured, then 'resultant_length' is negative to indicate this! This behaviour is different than LIB$GET_COMMAND. Examples: >>> import vms_lib >>> # (text that is entered is either in italics or underlined) >>> vms_lib.get_command () input-text ('input-text', 10) >>> vms_lib.get_command (None,5) input2-text2 ('input', -5) >>> vms_lib.get_command ('Yes?') Yes?3input-3text ('3input-3text', 12) >>> vms_lib.get_command ('Yes?',7) Yes?4input-4text ('4input-', -7) >>> vms_lib.get_command ('INPUT> ',None) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-39 vms_lib module 7.3.22 GET_COMMON - Get String from Common Retrieves a maximum of 252 characters from the common area. This includes the \0 character. The data is stored with vms_lib.put_common() in the common area. Format: resultant_string, resultant_length = vms_lib.get_common () Returns: resultant_string A copy of the data that was stored by vms_lib.put_common() in the common area. resultant_length Number of characters that were retrieved from the common area. Arguments: vms_lib.get_common() does not take any arguments. Examples: >>> import vms_lib >>> data = '1234ABC' >>> length_put = vms_lib.put_common (data) >>> print length_put 7 >>> resultant_string, resultant_length = vms_lib.get_common () >>> print resultant_string 1234ABC >>> print len (resultant_string) 7 >>> print resultant_length 7 >>> ------------------------------------------------------------------------ 7.3.23 GET_EF - Get Event Flag get_ef() allocates an arbitrary event flag that is free while vms_lib.reserve_ef() allocates a specific event flag (which must be free). Format: event_flag_number = vms_lib.get_ef () PYVMS - Python on OpenVMS PAGE 7-40 vms_lib module Returns: event_flag_number Number of the local event flag that was allocated. Arguments: vms_lib.get_ef() does not take any arguments. Examples: >>> import vms_lib >>> event_flag_number = vms_lib.get_ef () >>> print event_flag_number 62 >>> print vms_lib.get_ef () 61 >>> # event flags 1 - 23 are initially reserved >>> # (compatibility to the RSX operating system) >>> vms_lib.free_ef (1) >>> print vms_lib.get_ef () 60 >>> while (1): ... print vms_lib.get_ef () ... 59 58 ... 33 32 1 Traceback (innermost last): File "", line 2, in ? vms_lib.error: (1409684, '%LIB-F-INSEF, insufficient event flags') >>> (this example intentionally lets the loop be terminated by an exception) ------------------------------------------------------------------------ 7.3.24 GET_FOREIGN - Get Foreign Command Line Format: resultant_string, flags_out = vms_lib.get_foreign \ ([prompt_string] [,flags]) Returns: PYVMS - Python on OpenVMS PAGE 7-41 vms_lib module resultant_string String that was received from the foreign command line. Note: in some situations this text is uppercased - please read the documentation! flags_out the 'flags' argument of LIB$GET_FOREIGN is passed 'by reference' because it can be modified. 'flags_out' returns the value from 'flags' after the call to LIB$GET_FOREIGN. Please check the examples and read the documentation for more details! Arguments: prompt_string Optional text which is used for prompting when no command line is available. flags Please read the documentation to understand the usage of this argument. Examples: ----- $ python Python 1.5.1 (V001, May 8 1998, 19:23:14) [DECC] on vms Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam portions Copyright 1996-1998 Uwe Zessin >>> import vms_lib >>> print vms_lib.get_foreign () ('', 0) >>> # (text that is entered is either in italics or underlined) >>> print vms_lib.get_foreign ('$.') $.data ('DATA', 0) >>> print vms_lib.get_foreign ('$.',None) $.text ('TEXT', 1) ----- $ type VMS_LIB_GET_FOREIGN1.PY import vms_lib print vms_lib.get_foreign() print vms_lib.get_foreign('?>') print vms_lib.get_foreign('!>',None) $ python VMS_LIB_GET_FOREIGN1.PY ('VMS_LIB_GET_FOREIGN1.PY', 0) ('VMS_LIB_GET_FOREIGN1.PY', 0) ('VMS_LIB_GET_FOREIGN1.PY', 1) $ PYVMS - Python on OpenVMS PAGE 7-42 vms_lib module ----- $ type VMS_LIB_GET_FOREIGN2.PY import vms_lib print vms_lib.get_foreign('in: ',1) $ python VMS_LIB_GET_FOREIGN2.PY in: Xx ('XX', 1) $ ----- ------------------------------------------------------------------------ 7.3.25 GET_SYMBOL - Get Value of CLI Symbol Format: resultant_string, table_type = vms_lib.get_symbol (symbol) Returns: resultant_string contents of 'symbol' table-type-indicator "GLOBAL" or "LOCAL" - this is _not_ a numeric value as in LIB$GET_SYMBOL. It is a text string. Arguments: symbol name of the symbol Examples: >>> import vms_lib >>> print vms_lib.get_symbol ('$STATUS') ('%X00000001', 'GLOBAL') >>> >>> symbol, table = vms_lib.get_symbol ('$STATUS') >>> print symbol, '-', table %X00000001 - GLOBAL >>> >>> t = vms_lib.get_symbol ('$STATUS') >>> t ('%X00000001', 'GLOBAL') >>> type(t) PYVMS - Python on OpenVMS PAGE 7-43 vms_lib module >>> print vms_lib.get_symbol ('$STATUS')[0] %X00000001 >>> >>> vms_lib.get_symbol () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given >>> vms_lib.get_symbol (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, int found >>> vms_lib.get_symbol (None) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, None found >>> ------------------------------------------------------------------------ 7.3.26 GET_USERS_LANGUAGE - Return the User's Language Format: users_language = vms_lib.users_language () Returns: users_language Translation of the logical name "SYS$LANGUAGE". If the translation fails, then 'ENGLISH' is returned. Arguments: vms_lib.users_language() does not take any arguments. Examples: >>> import vms_lib >>> users_language = vms_lib.get_users_language () >>> users_language 'ENGLISH' $ DEFINE SYS$LANGUAGE "GERMAN" >>> vms_lib.get_users_language () 'GERMAN' * don't forget to use '$ DEASSIGN SYS$LANGUAGE' ! PYVMS - Python on OpenVMS PAGE 7-44 vms_lib module >>> vms_lib.get_users_language ('S') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> vms_lib.get_users_language (None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ 7.3.27 LP_LINES - Lines on Each Printer Page Format: lp_line_count = vms_lib.lp_lines () Returns: lp_line_count The default number of lines on a physical printer page. If the logical name ("LIB$LP_LINES") translation or conversion to binary fails, a default value of 66 is returned. Arguments: vms_lib.lp_lines() does not take any arguments. Examples: >>> import vms_lib >>> lp_line_count = vms_lib.lp_lines () >>> lp_line_count 66 $ DEFINE SYS$LP_LINES "_INVALID_" >>> vms_lib.lp_lines () 66 $ DEFINE SYS$LP_LINES "72" >>> vms_lib.lp_lines () 72 * don't forget to use '$ DEASSIGN SYS$LP_LINES' ! >>> vms_lib.lp_lines ('S') Traceback (innermost last): File "", line 1, in ? PYVMS - Python on OpenVMS PAGE 7-45 vms_lib module TypeError: function requires no arguments >>> ------------------------------------------------------------------------ 7.3.28 PUT_COMMON - Put String to Common Stores a maximum of 252 characters into the common area. This includes the \0 character. The data can be retrieved with vms_lib.get_common(). Format: resultant_length = vms_lib.put_common (source_string) Returns: resultant_length The actual number of characters copied to the common area - maximum = 252. Arguments: source_string Source string to be copied to the common area. Examples: >>> import vms_lib >>> data = '1234ABC' >>> length_put = vms_lib.put_common (data) >>> print length_put 7 >>> resultant_string, resultant_length = vms_lib.get_common () >>> print resultant_string 1234ABC >>> print len (resultant_string) 7 >>> print resultant_length 7 >>> ------------------------------------------------------------------------ 7.3.29 PUT_OUTPUT - Put Line to SYS$OUTPUT The Put Line to SYS$OUTPUT routine writes a record to the current controlling output device, specified by SYS$OUTPUT using the RMS $PUT PYVMS - Python on OpenVMS PAGE 7-46 vms_lib module service. Format: vms_lib.put_output (message_string) Returns: None Arguments: message_string Message string written to the current controlling output device. RMS handles all formatting, so the message does not need to include such ASCII formatting instructions as carriage return (CR). Examples: >>> import vms_lib >>> message_string = 'data 1234' >>> print vms_lib.put_output (message_string) data 1234 <-- output from LIB$PUT_OUTPUT None <-- return-value from put_output() >>> print vms_lib.put_output () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given >>> print vms_lib.put_output (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, int found >>> print vms_lib.put_output ("1", "2") Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 2 given >>> ------------------------------------------------------------------------ 7.3.30 RADIX_POINT - Radix Point Symbol Format: radix_point_string = vms_lib.radix_point () Returns: PYVMS - Python on OpenVMS PAGE 7-47 vms_lib module radix_point_string The system's radix point symbol that is used inside a digit string to separate the integer part from the fraction part. Arguments: vms_lib.radix_point() does not take any arguments. Examples: >>> import vms_lib >>> radix_point_string = vms_lib.radix_point () >>> radix_point_string '.' $ DEFINE SYS$RADIX_POINT "," >>> vms_lib.radix_point () ',' $ DEFINE SYS$RADIX_POINT "XYZ" >>> vms_lib.radix_point () 'XYZ' * don't forget to use '$ DEASSIGN SYS$RADIX_POINT' ! >>> vms_lib.radix_point ('S') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> vms_lib.radix_point (None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ 7.3.31 RESERVE_EF - Reserve Event Flag Allocates a specific event flag while vms_lib.get_ef() allocates an arbitrary event flag that is free. Format: vms_lib.reserve_ef (event_flag_number) Returns: None PYVMS - Python on OpenVMS PAGE 7-48 vms_lib module Arguments: event_flag_number Number of the event flag that is to be allocated. Examples: >>> import vms_lib >>> # event flags 1 - 23 are initially reserved >>> # (compatibility to the RSX operating system) >>> print vms_lib.reserve_ef (1) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409700, '%LIB-F-EF_ALRRES, event flag already reserved') >>> # event flags 24 - 31 are reserved to OpenVMS >>> print vms_lib.reserve_ef (24) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409708, '%LIB-F-EF_RESSYS, event flag reserved to system') >>> # event flags 32 - 63 are initially free >>> print vms_lib.reserve_ef (32) None >>> # an already allocated event flag cannot be allocate a second time >>> print vms_lib.reserve_ef (32) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409700, '%LIB-F-EF_ALRRES, event flag already reserved') >>> # an allocated event flag can be freed ... >>> print vms_lib.free_ef (32) None >>> # ... and re-allocated again >>> print vms_lib.reserve_ef (32) None >>> # event flags 1 - 23 are initially reserved ... >>> print vms_lib.reserve_ef (1) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409700, '%LIB-F-EF_ALRRES, event flag already reserved') >>> # ... but can be freed >>> print vms_lib.free_ef (1) None >>> # ... and then re-allocated >>> print vms_lib.reserve_ef (1) None >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-49 vms_lib module 7.3.32 RUN_PROGRAM - Run New Program Note that you will not be returned to Python. Not even when the program you wish to run does not exist! Please read the documentation for details. Format: vms_lib.run_program (program_name) Returns: None Arguments: program_name File name of the program to run in place of the current program (Python). Examples: >>> import vms_lib >>> vms_lib.run_program ('SYS$SYSTEM:NCP.EXE') NCP> >>> vms_lib.run_program ('') $ >>> vms_lib.run_program (None) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, None found >>> vms_lib.run_program ('no-file') %DCL-W-ACTIMAGE, error activating image NO-FILE -CLI-E-IMAGEFNF, image file not found DKA100:[PYTHON.PYTHON-1.4.VMS]NO-FILE.EXE; $ ------------------------------------------------------------------------ 7.3.33 SET_LOGICAL - Set Logical Name This routine is used to set a supervisor-mode logical name. vms_lib.set_logical() does _not_ raise an exception when the LIB$SET_LOGICAL routine returns an error. You must check 'status' in the dictionary that is returned. Format: PYVMS - Python on OpenVMS PAGE 7-50 vms_lib module dict = vms_lib.set_logical (logical-name, [value-string] [,table] \ [,attributes] [,item-list]) Returns: dict A dictionary that has the following keys: 'status' the condition value returned from LIB$SET_LOGICAL. 'LNM$_name' Any output items that have been specified in the item-list and that are supported by LIB$SET_LOGICAL. Arguments: logical-name Logical name to be defined or redefined. value-string Value to be given to the logical name. For multiple values use the item-list parameter. table Name of the table in which to create the logical name. If omitted, LNM$PROCESS is used. attributes Logical name or translation attributes. Please see the VMS documentation for details. item-list Item list describing the equivalence names for this logical name. You can also specify 'LNM$_TABLE' as an output item. Examples: >>> import vms_lib >>> import os # only for testing >>> vms_lib.set_logical('LNM1','VAL1') {'status': 1} <-- return status from LIB$SET_LOGICAL >>> os.system ('show logical /full LNM1') "LNM1" [super] = "VAL1" (LNM$PROCESS_TABLE) 1 <-- return status from os.system() >>> >>> vms_lib.set_logical('LNM2','VAL2','LNM$JOB') {'status': 1} <-- return status from LIB$SET_LOGICAL >>> os.system('show logical /full LNM2') "LNM2" [super] = "VAL2" (LNM$JOB_814E0700) 1 <-- return status from os.system() >>> PYVMS - Python on OpenVMS PAGE 7-51 vms_lib module >>> import vms_lnmdef >>> vms_lib.set_logical('LNM3','VAL3','LNM$JOB',vms_lnmdef.LNM_M_CONCEALED) {'status': 1} <-- return status from LIB$SET_LOGICAL >>> os.system('show logical /full LNM3') "LNM3" [super] = "VAL3" [concealed] (LNM$JOB_814E0700) 1 <-- return status from os.system() >>> >>> vms_lib.set_logical('LNM3','VAL3','LNM$JOB',vms_lnmdef.LNM_M_CONCEALED+ ... vms_lnmdef.LNM_M_TERMINAL) {'status': 1585} <-- return status from LIB$SET_LOGICAL >>> os.system('write sys$output f$message(1585)') %SYSTEM-S-SUPERSEDE, logical name superseded 65537 <-- return status from os.system() due to '$WRITE' >>> * Note: the logical name LNM3 has been replaced >>> vms_lib.set_logical('LNM5',None,'LNM$GROUP',None, ... ( ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED), ... ('LNM$_STRING','S5A'),('LNM$_STRING','S5B') ... ) ... ) {'status': 1} <-- return status from LIB$SET_LOGICAL >>> os.system('show logical /full LNM5') "LNM5" [super] = "S5A" [concealed] (LNM$GROUP_010040) = "S5B" [concealed] 1 <-- return status from os.system() >>> >>> vms_lib.set_logical('LNM6',None,'LNM$GROUP',None, ... ( ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED), ... ('LNM$_STRING','S6A'), ... ('LNM$_ATTRIBUTES',0), ... ('LNM$_STRING','S6B') ... ) ... ) {'status': 1} <-- return status from LIB$SET_LOGICAL >>> os.system('show logical /full LNM6') "LNM6" [super] = "S6A" [concealed] (LNM$GROUP_010040) = "S6B" 1 <-- return status from os.system() >>> >>> d = vms_lib.set_logical('LNM7',None,'LNM$GROUP',None, ... ( ('LNM$_TABLE','X'), ... ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED), ... ('LNM$_STRING','S7A'), ... ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED), ... ('LNM$_STRING','S7B'), PYVMS - Python on OpenVMS PAGE 7-52 vms_lib module ... ('LNM$_ATTRIBUTES',0), ... ('LNM$_STRING','S7C') ... ) ... ) >>> d {'LNM$_TABLE': 'LNM$GROUP_010040', 'status': 1} -- 'LNM$_TABLE' is an output-item -- 'status' is the condition value returned from LIB$SET_LOGICAL >>> os.system('show logical /full LNM7') "LNM7" [super] = "S7A" [concealed] (LNM$GROUP_010040) = "S7B" [concealed] = "S7C" 1 <-- return status from os.system() >>> >>> vms_lib.set_logical('LNM8',None,'LNM$GROUP',None, ... ( ('LNM$_ACMODE',3), ... ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED), ... ('LNM$_STRING','S7A'), ... ('LNM$_ATTRIBUTES',0), ... ('LNM$_STRING','S7B') ... ) ... ) {'status': 20} <-- return status from LIB$SET_LOGICAL >>> os.system('write sys$output f$message(20)') %SYSTEM-F-BADPARAM, bad parameter value 65537 <-- return status from os.system() due to '$WRITE' >>> ------------------------------------------------------------------------ 7.3.34 SET_SYMBOL - Set Value of CLI Symbol Format: vms_lib.set_symbol (symbol, value-string [,table-type-indicator]) Returns: None Arguments: symbol name of the symbol value-string contents of 'symbol' table-type-indicator "GLOBAL" or "LOCAL" - this is _not_ a numeric value as in LIB$SET_SYMBOL. You must specify a text string. This PYVMS - Python on OpenVMS PAGE 7-53 vms_lib module parameter is optional. The default value is "LOCAL". Examples: >>> import vms_lib >>> vms_lib.set_symbol ('VMS_LIB_SYM_GLOBAL', 'VALUE_GLOBAL', 'GLOBAL') >>> vms_lib.set_symbol ('VMS_LIB_SYM_LOCAL', 'VALUE_LOCAL', 'LOCAL') >>> vms_lib.set_symbol ('VMS_LIB_SYM_NONE', 'VALUE_NONE', None) >>> vms_lib.set_symbol ('VMS_LIB_SYM_DEFAULT', 'VALUE_DEFAULT') $ show symbol VMS_LIB_SYM_* VMS_LIB_SYM_DEFAULT = "VALUE_DEFAULT" <-- local symbol VMS_LIB_SYM_GLOBAL == "VALUE_GLOBAL" VMS_LIB_SYM_LOCAL = "VALUE_LOCAL" <-- local symbol VMS_LIB_SYM_NONE = "VALUE_NONE" <-- local symbol $ * don't forget to delete these symbols! $ delete/symbol/local VMS_LIB_SYM_DEFAULT $ delete/symbol/global VMS_LIB_SYM_GLOBAL $ delete/symbol/local VMS_LIB_SYM_LOCAL $ delete/symbol/local VMS_LIB_SYM_NONE >>> symbol_name = 'S' * 257 >>> vms_lib.set_symbol (symbol_name, 'VALUE_STRING', 'GLOBAL') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name') >>> >>> value_string = 'V' * 257 >>> vms_lib.set_symbol ('SYMBOL', value_string, 'GLOBAL') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> >>> vms_lib.set_symbol ('SYMBOL', 'VALUE_STRING', 'BAD') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> >>> vms_lib.set_symbol () Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 2 arguments; 0 given >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-54 vms_lib module 7.3.35 SUB_TIMES - Subtract Two Quadword Times Format: resultant_time = vms_lib.sub_times (time1, time2) Returns: resultant_time The result of subtracting time2 from time1. 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Arguments: time1 First time, from which LIB$SUB_TIMES subtracts the second time. 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. time2 Second time, which LIB$SUB_TIMES subtracts from the first time. 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_lib >>> import vms_sys # needed for ascii/integer conversion >>> time1 = vms_sys.bintim ('29-FEB-2000 12:34:56.78') >>> print time1 44585444967800000L >>> time2 = vms_sys.bintim ('0 01:02:03.11') >>> print time2 -37231100000L >>> time3 = vms_sys.bintim ('01-JAN-2000 12:56:34.89') >>> print time3 44534481948900000L >>> time4 = vms_sys.bintim ('0 04:03:02.11') >>> print time4 -145821100000L >>> resultant_time = vms_lib.sub_times (time1, time2) >>> print resultant_time, vms_sys.asctim (resultant_time); 44585407736700000L 29-FEB-2000 11:32:53.67 >>> resultant_time = vms_lib.sub_times (time1, time3) >>> print resultant_time, vms_sys.asctim (resultant_time); -50963018900000L 58 23:38:21.89 PYVMS - Python on OpenVMS PAGE 7-55 vms_lib module >>> resultant_time = vms_lib.sub_times (time4, time2) >>> print resultant_time, vms_sys.asctim (resultant_time); -108590000000L 0 03:00:59.00 >>> resultant_time = vms_lib.sub_times (time2, time1) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410036, '%LIB-F-INVARGORD, invalid argument order') >>> >>> resultant_time = vms_lib.sub_times (time2, time4) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410028, '%LIB-F-NEGTIM, a negative time was computed') >>> >>> resultant_time = vms_lib.sub_times (time1, time1) >>> print resultant_time, vms_sys.asctim (resultant_time); -1L 0 00:00:00.00 * Note: VMS cannot express a delta-time of '0 00:00:00.00'. This is really a delta time of 100 nanoseconds! >>> resultant_time = vms_lib.sub_times (time2, time2) >>> print resultant_time, vms_sys.asctim (resultant_time); -1L 0 00:00:00.00 * Note: VMS cannot express a delta-time of '0 00:00:00.00'. This is really a delta time of 100 nanoseconds! >>> resultant_time = vms_lib.sub_times ('X', time2) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> >>> resultant_time = vms_lib.sub_times (time1, 'X') Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: must be long int >>> >>> resultant_time = vms_lib.sub_times () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 2 arguments; 0 given >>> >>> resultant_time = vms_lib.sub_times (time1, 2) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: must be long int PYVMS - Python on OpenVMS PAGE 7-56 vms_lib module >>> ------------------------------------------------------------------------ 7.3.36 WAIT - Wait a Specified Period of Time Format: vms_lib.wait (seconds) Returns: None Arguments: seconds Number of seconds to wait. This is a floating point value. Examples: >>> import vms_lib >>> vms_lib.wait (5.5) >>> delay = 3 >>> wait_returns = vms_lib.wait (delay) >>> print wait_returns None >>> ------------------------------------------------------------------------ 12-AUG-1998 ZE. PYVMS - Python on OpenVMS PAGE 7-57 vms_sys module 7.4 vms_sys module The 'vms_sys' module provides access to some OpenVMS SYS$ routines. Most functions DO NOT return a status code; they raise the exception 'vms_sys.error' when something went wrong. Functions that behave differently have it mentioned at their description. ------------------------------------------------------------------------ Alphabetical list of routines: - ASCTIM - Convert Binary Time to ASCII String - ASCTOID - Translate Identifier Name to Identifier - ASCUTC - Convert UTC to ASCII - BINTIM - Convert ASCII String to Binary Time - BINUTC - Convert ASCII String to UTC Binary Time - CANWAK - Cancel Wakeup - DELPRC - Delete Process - FORCEX - Force Exit - GETTIM - Returns the current system time in a 64-bit format - GETUTC - Get UTC Time - HIBER - Hibernate - NUMTIM - Convert Binary Time to Numeric Time - NUMUTC - Convert UTC Time to Numeric Components - PURGWS - Purge Working Set - RESUME - Resume Process - SCHDWK - Schedule Wakeup - SETDDIR - Set Default Directory - SETPRI - Set Priority - SETPRN - Set Process Name - SETSWM - Set Process Swap Mode - SUBSYSTEM - Subsystem - SUSPND - Suspend Process - TIMCON - Time Converter - WAKE - Wake Process from Hibernation ------------------------------------------------------------------------ ------------------------------------------------------------------------ 7.4.1 ASCTIM - Convert Binary Time to ASCII String Format: timbuf = vms_sys.asctim (timadr [,cvtflg]) Returns: timbuf Converted Date and Time as an ASCII string. Arguments: timadr 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. PYVMS - Python on OpenVMS PAGE 7-58 vms_sys module cvtflg Conversion indicator. Please consult the system reference manual for details. Examples: >>> import vms_sys >>> vms_sys.asctim () '12-AUG-1998 10:32:12.47' >>> vms_sys.asctim (None) '12-AUG-1998 10:32:17.69' >>> vms_sys.asctim (None,0) '12-AUG-1998 10:32:47.51' >>> vms_sys.asctim (None,1) '10:33:01.12' >>> vms_sys.asctim (0x009A0070B0CB6D60L) '28-MAR-1996 20:50:41.59' >>> print 0x009A0070B0CB6D60L 43347630415900000L >>> vms_sys.asctim (43347630415900000L, 0) '28-MAR-1996 20:50:41.59' >>> vms_sys.asctim (0x009A0070B0CB6D60L, 1) '20:50:41.59' >>> vms_sys.asctim (0x009A0070B0CB6D60L, None) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> vms_sys.asctim ('0x009A0070B0CB6D60L', 1) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> vms_sys.asctim ('string') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> # this is only an int, not a long int >>> vms_sys.asctim (0x12345) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int PYVMS - Python on OpenVMS PAGE 7-59 vms_sys module >>> # 'None' for argument 2 is not supported >>> vms_sys.asctim (None,None) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> ------------------------------------------------------------------------ 7.4.2 ASCTOID - Translate Identifier Name to Identifier Format: id, attrib = vms_sys.asctoid (name) Returns: id identifier value (integer) attrib Attributes that are associated with the identifier. The bit values are defined in the module vms_kgbdef. Arguments: name Identifier name to be translated. Examples: >>> import vms_sys >>> id_value, id_attribute = vms_sys.asctoid ('SYSTEM') >>> print 'ID-value=', id_value, 'ID-attribute=', id_attribute ID-value= 65540 ID-attribute= 0 >>> uic_group = id_value / 65536 >>> uic_member = id_value - (uic_group * 65536) >>> uic_spec = 'UIC= [' + str(uic_group) + ',' + str(uic_member) + ']' >>> print uic_spec UIC= [1,4] >>> id_name = 'BATCH' >>> vms_sys.asctoid (id_name) (-2147483647, 0) >>> hex (-2147483647) '0x80000001' >>> import os >>> os.system('WRITE SYS$OUTPUT F$IDENTIFIER("BATCH","NAME_TO_NUMBER")') -2147483647 <-- output from '$ WRITE' PYVMS - Python on OpenVMS PAGE 7-60 vms_sys module 65537 <-- status from os.system() = RMS$_NORMAL >>> vms_sys.asctoid () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given >>> vms_sys.asctoid (None) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected string, None found >>> vms_sys.asctoid ('NON_EXIST') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> vms_sys.asctoid ('-') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8740, '%SYSTEM-F-IVIDENT, invalid identifier format') >>> ------------------------------------------------------------------------ 7.4.3 ASCUTC - Convert UTC to ASCII Format: timbuf = vms_sys.ascutc (utcadr [,cvtflg]) Returns: timbuf ASCII String Arguments: utcadr 128-bit UTC value - an ASCII string of 32 hex characters. cvtflg conversion indicator 0 = return full date and time 1 = return only hour, minute, second, hundredths-of-second Examples: >>> import vms_sys >>> utc_tim = vms_sys.getutc () >>> print utc_tim 103CFFFFFFFFFFFF01D177D7D9B13B80 PYVMS - Python on OpenVMS PAGE 7-61 vms_sys module >>> print vms_sys.ascutc (utc_tim) 18-DEC-1997 19:41:52.44 >>> print vms_sys.asctim () 18-DEC-1997 19:41:53.41 >>> utc_tim = vms_sys.binutc ('29-FEB-2000 12:34:56.78') >>> print utc_tim 103CFFFFFFFFFFFF01D3EE9C3F46F4C0 >>> print vms_sys.ascutc (utc_tim) 29-FEB-2000 12:34:56.78 >>> print vms_sys.ascutc () 18-DEC-1997 19:43:55.99 >>> print vms_sys.ascutc (None) 18-DEC-1997 19:44:18.72 >>> # non-hex character ---v >>> print vms_sys.ascutc ('X03CFFFFFFFFFFFF01D177D7D9B13B80') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be 32 hex characters >>> # string to long 12345678901234567890123456789012 >>> print vms_sys.ascutc ('103CFFFFFFFFFFFF01D177D7D9B13B80F') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be 32 hex characters >>> # string to short 12345678901234567890123456789012 >>> print vms_sys.ascutc ('03CFFFFFFFFFFFF01D177D7D9B13B80') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be 32 hex characters >>> # bad datatype >>> print vms_sys.ascutc (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, int found >>> ------------------------------------------------------------------------ 7.4.4 BINTIM - Convert ASCII String to Binary Time Format: timadr = vms_sys.bintim (timbuf) Returns: PYVMS - Python on OpenVMS PAGE 7-62 vms_sys module timadr 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Arguments: timbuf ASCII date + time to be converted. Examples: >>> import vms_sys >>> vms_sys.bintim ('29-FEB-2000 12:34:56.78') 44585444967800000L >>> vms_sys.asctim (44585444967800000L) '29-FEB-2000 12:34:56.78' >>> vms_sys.bintim ('0 01:03:04.45') -37844500000L >>> vms_sys.asctim (-37844500000L) ' 0 01:03:04.45' >>> vms_sys.bintim () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given >>> vms_sys.bintim (None) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, None found >>> vms_sys.bintim ('INVALID') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time') >>> vms_sys.bintim (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, int found >>> ------------------------------------------------------------------------ 7.4.5 BINUTC - Convert ASCII String to UTC Binary Time Format: PYVMS - Python on OpenVMS PAGE 7-63 vms_sys module utcadr = vms_sys.binutc (timbuf) Returns: utcadr 128-bit UTC value - an ASCII string of 32 hex characters. Arguments: timbuf ASCII (date +) time to be converted. Examples: >>> import vms_sys >>> utc_tim = vms_sys.binutc ('29-FEB-2000 12:34:56.78') >>> print utc_tim 103CFFFFFFFFFFFF01D3EE9C3F46F4C0 >>> print vms_sys.ascutc (utc_tim) 29-FEB-2000 12:34:56.78 >>> utc_tim = vms_sys.binutc ('30-FEB-2000 12:34:56.78') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time') >>> utc_tim = vms_sys.binutc () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given >>> ------------------------------------------------------------------------ 7.4.6 CANWAK - Cancel Wakeup Removes all scheduled wakeup requests for a process from the timer queue, including those made by the caller or by other processes. The Schedule Wakeup ($SCHDWK) service makes scheduled wakeup requests. Format: targpid = vms_sys.canwak ([pidadr] [,prcnam]) Returns: targpid Process identification of process for which wakeups have been canceled. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.canwak() raises a PYVMS - Python on OpenVMS PAGE 7-64 vms_sys module Python exception. Arguments: pidadr Process identification of process for which wakeups are to be canceled. prcnam Process name of process for which wakeups are to be canceled. Examples: >>> import vms_sys >>> print vms_sys.canwak () 341 <-- CANWAK on current process >>> print vms_sys.canwak (None,None) 341 <-- CANWAK on current process >>> print vms_sys.canwak (387) 387 >>> vms_sys.canwak (None,'TARG_PRC') 387 >>> vms_sys.canwak (0,'TARG_PRC') 387 >>> print vms_sys.canwak (0) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') --> Argument 1 = 0 or None means that Argument 2 should have a valid process name. >>> print vms_sys.canwak (None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') --> Argument 1 = 0 or None means that Argument 2 should have a valid process name. >>> vms_sys.canwak (1,2) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: expected read-only buffer, int found >>> nonexist_pid = 99 >>> vms_sys.canwak (nonexist_pid) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.canwak (None,'NONEXPRC') Traceback (innermost last): PYVMS - Python on OpenVMS PAGE 7-65 vms_sys module File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> ------------------------------------------------------------------------ 7.4.7 DELPRC - Delete Process Format: targpid = vms_sys.delprc ([pidadr] [,prcnam]) Returns: targpid Process identification of process which has been deleted - unless, of course the process has deleted itself ... The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.delprc() raises a Python exception. Arguments: pidadr Process identification of process to be deleted. prcnam Process name of process to be deleted. Examples: >>> import vms_sys >>> print vms_sys.delprc () (current process is deleted) >>> print vms_sys.delprc (None,None) (current process is deleted) >>> print vms_sys.delprc (353) 353 (target process is deleted + its PID is returned) $ cmd = "import vms_sys; print 'a'; print 'b'" $ spawn python -c "''cmd'" %DCL-S-SPAWNED, process ZESSIN_1 spawned %DCL-S-ATTACHED, terminal now attached to process ZESSIN_1 a b %DCL-S-RETURNED, control returned to process ZESSIN_FTA17 $ PYVMS - Python on OpenVMS PAGE 7-66 vms_sys module $ cmd = "import vms_sys; print 'a'; vms_sys.delprc (); print 'b'" $ spawn python -c "''cmd'" %DCL-S-SPAWNED, process ZESSIN_1 spawned %DCL-S-ATTACHED, terminal now attached to process ZESSIN_1 a %DCL-S-RETURNED, control returned to process ZESSIN_FTA17 $! --> 'b' is not printed because subprocess is deleted by delprc() >>> print vms_sys.delprc (0,"TARG_PRC") 355 (target process is deleted + its PID is returned) >>> print vms_sys.delprc (None,"TARG_PRC") 476 (target process is deleted + its PID is returned) >>> no_such_pid = 12345 >>> print vms_sys.delprc (no_such_pid) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> no_such_prcnam = "NO_PRCNAM" >>> print vms_sys.delprc (0,no_such_prcnam) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> audit_server_pid = 265 >>> print vms_sys.delprc (265) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (9020, '%SYSTEM-F-NODELETE, object cannot be deleted') >>> # the AUDIT_SERVER process cannot be deleted ------------------------------------------------------------------------ 7.4.8 FORCEX - Force Exit Causes an Exit ($EXIT) service call to be issued on behalf of a specified process. Format: targpid = vms_sys.forcex ([pidadr] [,prcnam] [,code]) Returns: PYVMS - Python on OpenVMS PAGE 7-67 vms_sys module targpid Process identification of process that has been forced to exit - unless, of course the process has forced itself to exit ... The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.forcex() raises a Python exception. Arguments: pidadr Process identification of process to be forced to exit. prcnam Process name of process to be forced to exit. code Completion code value to be used as the exit parameter. Examples: >>> import vms_sys >>> print vms_sys.forcex () %NONAME-W-NOMSG, Message number 00000000 $ ! current process forced to exit >>> print vms_sys.forcex (0) %NONAME-W-NOMSG, Message number 00000000 $ ! current process forced to exit >>> print vms_sys.forcex (None) %NONAME-W-NOMSG, Message number 00000000 $ ! current process forced to exit >>> print vms_sys.forcex (0,'') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') >>> print vms_sys.forcex (None,'') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') >>> print vms_sys.forcex (None,None) %NONAME-W-NOMSG, Message number 00000000 $ ! current process forced to exit >>> print vms_sys.forcex (None,None,None) %NONAME-W-NOMSG, Message number 00000000 $ ! current process forced to exit >>> print vms_sys.forcex (None,None,0) %NONAME-W-NOMSG, Message number 00000000 $ ! current process forced to exit PYVMS - Python on OpenVMS PAGE 7-68 vms_sys module >>> print vms_sys.forcex (None,None,44) %SYSTEM-F-ABORT, abort $ ! current process forced to exit - 44 == SS$_ABORT >>> pid = 360 >>> prcnam = 'TARG_PRC' >>> print vms_sys.forcex (pid) 360 <-- this is the target PID :TARG_PRC output: %NONAME-W-NOMSG, Message number 00000000 >>> vms_sys.forcex (pid,None,44) 360 <-- this is the target PID :TARG_PRC output: %SYSTEM-F-ABORT, abort >>> vms_sys.forcex (0,prcnam,44) 360 <-- this is the target PID Note that the process name was used, not PID 0. 0 means the target process should be returned. :TARG_PRC output: %SYSTEM-F-ABORT, abort Note: 'None' for Argument 1 is internally changed to 0! >>> vms_sys.forcex (None,prcnam,44) 360 <-- this is the target PID Note that the process name was used, not PID 0 :TARG_PRC output: %SYSTEM-F-ABORT, abort >>> vms_sys.forcex (999) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.forcex (None,'NO_SUCH_PRC') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.forcex (None,'PROCESS_NAME_TO_LONG') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') >>> vms_sys.forcex ('BAD') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: pidadr must be integer or None >>> vms_sys.forcex (None,1) Traceback (innermost last): File "", line 1, in ? PYVMS - Python on OpenVMS PAGE 7-69 vms_sys module TypeError: argument 2: expected None or string, int found >>> vms_sys.forcex (None,None,'BAD') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: code must be integer or None >>> ------------------------------------------------------------------------ 7.4.9 GETTIM - Returns the current system time in a 64-bit format Format: timadr = vms_sys.gettim () Returns: timadr 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Arguments: vms_sys.gettim() does not take any arguments. Examples: >>> import vms_sys >>> vms_bintim = vms_sys.gettim () >>> vms_bintim 44096363555600000L >>> vms_sys.asctim (vms_bintim) '12-AUG-1998 10:59:15.56' >>> vms_sys.gettim (None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> vms_sys.gettim (1) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-70 vms_sys module 7.4.10 GETUTC - Get UTC Time Returns the current time in 128-bit UTC format. Format: utcadr = vms_sys.getutc () Returns: utcadr 128-bit UTC value - an ASCII string of 32 hex characters. Arguments: vms_sys.getutc() does not take any arguments. Examples: >>> import vms_sys >>> utc_tim = vms_sys.getutc () >>> print utc_tim 103CFFFFFFFFFFFF01D1732D81027700 >>> print vms_sys.ascutc (utc_tim) 12-DEC-1997 21:12:24.56 >>> print vms_sys.asctim () 12-DEC-1997 21:12:25.35 >>> vms_sys.getutc (None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> vms_sys.getutc (1) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ 7.4.11 HIBER - Hibernate Allows a process to make itself inactive. There are two ways for the hibernated process to wake up from inside the Python interpreter: 1 PYVMS - Python on OpenVMS PAGE 7-71 vms_sys module The process must be waked up via vms_sys.wake() or SYS$WAKE() from a different process. 2 The process uses the vms_sys.schdwk() routine. Format: vms_sys.hiber () Returns: None Arguments: vms_sys.hiber() does not take any arguments. Examples: >>> import vms_sys >>> vms_sys.hiber () * the current process hibernates >>> vms_sys.hiber (None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> vms_sys.hiber (1) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> ------------------------------------------------------------------------ 7.4.12 NUMTIM - Convert Binary Time to Numeric Time Format: timbuf = vms_sys.numtim ([timadr]) Returns: timbuf a tuple of 7 (16-bit) integers consisting of: (year, month, day, hour, minute, second, hundredth) Arguments: PYVMS - Python on OpenVMS PAGE 7-72 vms_sys module timadr 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_sys >>> vms_sys.bintim ('29-FEB-2000 12:34:56.78') 44585444967800000L >>> vms_sys.numtim (44585444967800000L) (2000, 2, 29, 12, 34, 56, 78) >>> # (year, month, day, hour, minute, second, hundredth) >>> vms_sys.asctim () '12-AUG-1998 11:09:11.45' >>> vms_sys.numtim () (1998, 8, 12, 11, 9, 14, 69) >>> vms_sys.numtim (None) (1998, 8, 12, 11, 9, 19, 69) >>> # (year, month, day, hour, minute, second, hundredth) >>> vms_sys.numtim (vms_sys.bintim ('0 01:02:03.45')) (0, 0, 0, 1, 2, 3, 45) >>> # (year, month, day, hour, minute, second, hundredth) >>> vms_sys.numtim ('X') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> ------------------------------------------------------------------------ 7.4.13 NUMUTC - Convert UTC Time to Numeric Components Format: timbuf = vms_sys.numtim ([utcadr]) Returns: timbuf a tuple of 7 (16-bit) integers consisting of: (year, month, day, hour, minute, second, hundredth, inaccuracy-days, in-hours, in-minutes, in-seconds in-hundredth, TDF-in-minutes) Arguments: utcadr 128-bit UTC value - an ASCII string of 32 hex characters. PYVMS - Python on OpenVMS PAGE 7-73 vms_sys module Examples: >>> import vms_sys >>> vms_sys.binutc ('29-FEB-2000 12:34:56.78') '103CFFFFFFFFFFFF01D3EE9C3F46F4C0' >>> vms_sys.numutc ('103CFFFFFFFFFFFF01D3EE9C3F46F4C0') (2000, 2, 29, 12, 34, 56, 78, -1, -1, -1, -1, -1, 60) >>> vms_sys.asctim () '12-DEC-1997 21:48:11.90' >>> vms_sys.numutc () (1997, 12, 12, 21, 48, 11, 94, -1, -1, -1, -1, -1, 60) >>> vms_sys.numutc (None) (1997, 12, 12, 21, 48, 36, 59, -1, -1, -1, -1, -1, 60) The tuple consists of: ( year_since_0, month_of_year, day_of_month, hour_of_day, minute_of_hour, second_of_minute, hundredths_of_second, inacc_days, inacc_hours, inacc_minutes, inacc_seconds, inacc_hundredths_of_second, tdf_in_minutes ) >>> vms_sys.numutc (vms_sys.binutc ('0 01:02:03.45')) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time') >>> vms_sys.numutc ('X') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1 must be 32 hex characters >>> ------------------------------------------------------------------------ 7.4.14 PURGWS - Purge Working Set Format: vms_sys.purgws (start-addr, end-addr) Returns: None Arguments: start-addr Starting virtual address of the range of pages to be purged. end-addr Ending virtual address of the range of pages to be purged. Note: the original system service accepts one argument that points to PYVMS - Python on OpenVMS PAGE 7-74 vms_sys module two longwords in memory. The Python function requires two separate arguments, not one argument or a tuple. Examples: >>> import vms_sys >>> NODE::PRCNAM 19:06:29 PYTHON CPU=00:08:06.24 PF=101647 IO=7846 MEM=1201 >>> allocate_memory = range (50000) >>> NODE::PRCNAM 19:07:13 PYTHON CPU=00:08:09.52 PF=103644 IO=7860 MEM=2886 >>> vms_sys.purgws (0,2147483647) >>> NODE::PRCNAM 19:07:42 PYTHON CPU=00:08:09.93 PF=103850 IO=7867 MEM=331 ^^^ >>> vms_sys.purgws () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 2 arguments; 0 given >>> vms_sys.purgws (1) Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 2 arguments; 1 given >>> vms_sys.purgws (1,None) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> ------------------------------------------------------------------------ 7.4.15 RESUME - Resume Process Causes a process previously suspended by the Suspend Process ($SUSPND) service to resume execution or cancels the effect of a subsequent suspend request. Format: targpid = vms_sys.resume ([pidadr] [,prcnam]) Returns: targpid Process identification of process that has been resumed. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.resume() raises a Python exception. PYVMS - Python on OpenVMS PAGE 7-75 vms_sys module Arguments: pidadr Process identification of process to be resumed. prcnam Process name of process to be resumed. Examples: >>> import vms_sys >>> print vms_sys.resume (464) 464 >>> vms_sys.resume (None,'TARG_PRC') 476 >>> vms_sys.resume (0,'TARG_PRC') 476 >>> vms_sys.resume (1,2) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: expected None or string, int found >>> nonexist_pid = 99 >>> vms_sys.resume (nonexist_pid) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.resume (None,'NONEXPRC') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.resume () 352 <-- set RESUME on current process - the next $ SET PROCESS/SUSPEND ! continues immediately >>> vms_sys.resume (None,None) 352 <-- set RESUME on current process - the next $ SET PROCESS/SUSPEND ! continues immediately ------------------------------------------------------------------------ 7.4.16 SCHDWK - Schedule Wakeup Schedules the awakening (restarting) of a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service. Format: targpid = vms_sys.schdwk ([pidadr], [prcnam], daytim [,reptim]) PYVMS - Python on OpenVMS PAGE 7-76 vms_sys module Returns: targpid Process identification of process for which a wakeup has been scheduled. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.schdwk() raises a Python exception. Arguments: pidadr Process identification of process for which a wakeup is to be scheduled. prcnam Process name of process for which a wakeup is to be scheduled. daytim Time at which the process is to be awakened. 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. reptim Time interval at which the wakeup request is to be repeated. 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_sys >>> # translate ASCII delta time to 'binary quadword' equivalent. >>> ten_seconds = vms_sys.bintim ('0 00:00:10.00') >>> ten_seconds -100000000L >>> # wait a single 10 second shot >>> vms_sys.asctim () '12-AUG-1998 11:29:38.73' >>> vms_sys.schdwk (0, None, ten_seconds) 96 <-- PID of current process >>> vms_sys.hiber () >>> vms_sys.asctim () '12-AUG-1998 11:29:48.91' >>> # repeated wakeup with 5 seconds interval >>> vms_sys.asctim () '12-AUG-1998 11:29:49.08' >>> vms_sys.schdwk (0, None, ten_seconds, \ ... vms_sys.bintim ('0 00:00:05.00')) 96 <-- PID of current process >>> vms_sys.hiber () >>> vms_sys.asctim () '12-AUG-1998 11:29:59.33' PYVMS - Python on OpenVMS PAGE 7-77 vms_sys module >>> vms_sys.hiber () >>> vms_sys.asctim () '12-AUG-1998 11:30:04.35' >>> vms_sys.hiber () >>> vms_sys.asctim () '12-AUG-1998 11:30:09.33' >>> vms_sys.canwak () 96 <-- PID of current process >>> vms_sys.hiber () --> process 'hangs' because wakeup was cancelled use to exit >>> # None + None means this process as well as (0,None,LongInt) >>> vms_sys.schdwk (None, None, 0xFFFFFFFFFA0A1F00L) 96 <-- PID of current process >>> # first 'None' skips PID, second argument is process name >>> vms_sys.schdwk (None, 'NOSUCHPROC', 0xFFFFFFFFFA0A1F00L) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.schdwk (None, 1, 0xFFFFFFFFFA0A1F00L) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: expected read-only buffer, int found >>> vms_sys.schdwk (None, None, 'not-a-long-int') Traceback (innermost last): File "", line 1, in ? ValueError: argument 3 must be long int >>> vms_sys.schdwk (None, None, 0xFFFFFFFFFA0A1F00L, 1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 4: must be long int >>> ------------------------------------------------------------------------ 7.4.17 SETDDIR - Set Default Directory Allows you to read and change the default directory string for the process. Please note that the device name is stored in the logical name SYS$DISK! You can use vms_lib.set_logical() to change this logical name. PYVMS - Python on OpenVMS PAGE 7-78 vms_sys module Format: cur-dir = vms_sys.setddir ([new-dir]) Returns: cur-dir Current /old default directory. Note that this is always returned! Arguments: new-dir New default directory. Examples: >>> import vms_sys >>> vms_sys.setddir () '[PYTHON.PYTHON-1.4.VMS]' >>> vms_sys.setddir (None) '[PYTHON.PYTHON-1.4.VMS]' >>> vms_sys.setddir ('[-]') '[PYTHON.PYTHON-1.3.VMS]' * Note: setddir() returns the _old_ directory >>> vms_sys.setddir () '[PYTHON.PYTHON-1.4]' * the directory _has_ changed >>> vms_sys.setddir (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected None or string, int found >>> vms_sys.setddir (None,2) Traceback (innermost last): File "", line 1, in ? TypeError: function requires at most 1 argument; 2 given >>> vms_sys.setddir ('BAD#DIRECTORY#SYNTAX#') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (100052, '%RMS-F-SYN, file specification syntax error') >>> # only 8 levels supported >>> vms_sys.setddir ('[----------]') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (99532, '%RMS-F-DIR, error in directory name') >>> PYVMS - Python on OpenVMS PAGE 7-79 vms_sys module ------------------------------------------------------------------------ 7.4.18 SETPRI - Set Priority Changes the base priority of the process. The base priority is used to determine the order in which executable processes are to run. @@ Argument 4 not tested yet (23-MAY-1998) on OpenVMS Alpha. Format: targpid, previous_priority, previous_policy = vms_sys.setpri ( [pid], [prcnam], priority [, policy]) Returns: targpid Process identification of process for which the priority has been changed. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.setpri() raises a Python exception. previous_priority Previous process base priority. previous_policy Previous process policy (Alpha only - on VAX the function always returns 0 for consistency). Arguments: pid Process identification of the process for which the priority and / or policy is to be changed and / or retrieved. prcnam Process name of the process for which the priority and / or policy is to be changed and / or retrieved. priority New base priority for the target process. policy New scheduling policy for the target process. (Alpha only - this argument is ignored on VAX) Examples: >>> import vms_sys >>> # lower priority using explicit PID >>> print vms_sys.setpri (91,None,3) (91, 4, 0) PYVMS - Python on OpenVMS PAGE 7-80 vms_sys module >>> # set back old priority usind default PID >>> vms_sys.setpri (0,None,4) (91, 3, 0) >>> vms_sys.setpri (None,None,3) (91, 4, 0) >>> vms_sys.setpri (None,"TARG_PRC",3) (93, 4, 0) ^^ <-- PID of target process returned even if name was given >>> vms_sys.setpri () Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 3 arguments; 0 given >>> vms_sys.setpri (0,None) Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 2 arguments; 0 given >>> vms_sys.setpri (1,2,3) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: expected None or string, int found >>> nonexist_pid = 9999 >>> vms_sys.setpri (nonexist_pid,None,4) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.setpri (None,'NONEXPRC',4) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.setpri (__name__,'X',4) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: pidadr must be integer or None >>> ------------------------------------------------------------------------ 7.4.19 SETPRN - Set Process Name Format: vms_sys.setprn ([prcnam]) Returns: PYVMS - Python on OpenVMS PAGE 7-81 vms_sys module None. But you can get the current process name using vms_lib.getjpi() with the 'JPI$_PRCNAM' item code - see example below. Arguments: prcnam Process name to be given to the calling process. Examples: $ SET PROCESS/NAME="OLD_PRCNAM" >>> import vms_lib >>> import vms_sys >>> vms_lib.getjpi ('JPI$_PRCNAM',0) (160, 'OLD_PRCNAM') >>> vms_sys.setprn ('NEW_PRCNAM') >>> vms_lib.getjpi ('JPI$_PRCNAM',0) (160, 'NEW_PRCNAM') >>> vms_sys.setprn () >>> vms_lib.getjpi ('JPI$_PRCNAM',0) (160, '') >>> # an empty argument results in a process with no name. >>> vms_sys.setprn ('NEW_PRCNAM') >>> vms_lib.getjpi ('JPI$_PRCNAM',0) (160, 'NEW_PRCNAM') >>> vms_sys.setprn (None) >>> vms_lib.getjpi ('JPI$_PRCNAM',0) (160, '') >>> vms_sys.setprn (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected None or string, int found >>> vms_sys.setprn (None,2) Traceback (innermost last): File "", line 1, in ? TypeError: function requires at most 1 argument; 2 given >>> vms_sys.setprn ('THIS_PROCESS_NAME_IS_INVALID') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name') >>> # Note: a process with the name 'DUP_PRCNAM' does >>> # already exist in the same UIC group. >>> vms_sys.setprn ('DUP_PRCNAM') Traceback (innermost last): File "", line 1, in ? PYVMS - Python on OpenVMS PAGE 7-82 vms_sys module vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name') >>> ------------------------------------------------------------------------ 7.4.20 SETSWM - Set Process Swap Mode Format: oldflg = vms_sys.setswm ([swpflg]) Returns: oldflg This is the 'condition value returned' from the system service. The values of 'SS$_WASSET' or 'SS$_WASCLR' are returned as numbers 0 or 1 - other conditions result in a Python exception. Arguments: swpflg Indicator specifying whether the process can be swapped. Examples: $ SET PROCESS/PRIVILEGE=PSWAPM >>> import vms_sys >>> # 1= disable swapping >>> vms_sys.setswm (1) 0 >>> # 0= enable swapping >>> vms_sys.setswm (0) 1 >>> vms_sys.setswm (0) 0 >>> # None = disable swapping >>> vms_sys.setswm (None) 0 >>> # 0= enable swapping >>> vms_sys.setswm (0) 1 >>> vms_sys.setswm () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given PYVMS - Python on OpenVMS PAGE 7-83 vms_sys module >>> vms_sys.setswm ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: swpflg must be integer or None $ SET PROCESS/PRIVILEGE=NOPSWAPM ... >>> vms_sys.setswm (0) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (36, '%SYSTEM-F-NOPRIV, insufficient privilege or object protection violation') >>> ------------------------------------------------------------------------ 7.4.21 SUBSYSTEM - Subsystem Format: oldflg = vms_sys.subsystem ([enbflg]) Returns: oldflg This is the 'condition value returned' from the system service. The values of 'SS$_WASSET' or 'SS$_WASCLR' are returned as numbers 0 or 1 - other conditions result in a Python exception. Arguments: enbflg Value specifying whether the protected subsystem identifiers are to be saved (=0) or restored (=1). Examples: >>> import vms_sys >>> vms_sys.subsystem (1) 0 >>> vms_sys.subsystem (0) 1 >>> vms_sys.subsystem (None) >>> vms_sys.subsystem () Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 1 argument; 0 given PYVMS - Python on OpenVMS PAGE 7-84 vms_sys module >>> vms_sys.subsystem ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: enbflg must be integer or None >>> ------------------------------------------------------------------------ 7.4.22 SUSPND - Suspend Process Allows a process to suspend itself or another process. Execution can be resumed with the vms_lib.resume() service. Warning! A process that has suspended itself can only be resumed from a different one. Format: targpid = vms_sys.suspnd ([pidadr] [,prcnam] [,flags]) Returns: targpid Process identification of process that has been suspended. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.suspnd() raises a Python exception. Please note: if you do a SUSPND on your own process, then it will 'hang'. You must issue a resume() from a different process to continue. And _after that_, you will get the 'targpid' value back (which, of course, is your own PID). Arguments: pidadr Process identification of process to be suspended. prcnam Process name of process to be suspended. flags Bit flags specifying options for the suspend operation. Examples: >>> import vms_sys >>> # suspend current process >>> # Note: resume can only be done from a different process! >>> print vms_sys.suspnd () (process 'hangs') 91 <-- PID of current process it was resumed via: >>> vms_sys.resume(91) from a different process PYVMS - Python on OpenVMS PAGE 7-85 vms_sys module >>> print vms_sys.suspnd (None) (process 'hangs') 91 <-- PID of current process is printed after it was resumed via: >>> vms_sys.resume(91) from a different process >>> targ_pid = 93 >>> print vms_sys.suspnd (targ_pid) 93 <-- PID of target process this process now 'hangs' >>> vms_sys.resume (targ_pid) 93 <-- PID of target process this process now continues >>> print vms_sys.suspnd (0,"TARG_PRC") 93 <-- PID of target process this process now 'hangs' >>> vms_sys.resume (targ_pid) 93 <-- PID of target process this process now continues >>> # this example uses the PID that is returned >>> targ_pid = vms_sys.suspnd (None,"TARG_PRC") (target process 'hangs') >>> print targ_pid 95 <-- PID of target process >>> vms_sys.resume (targ_pid) 95 <-- PID of target process this process now continues * the flags argument cannot be used from Python because it runs in all user-mode code. >>> nonexist_pid = 9999 >>> print vms_sys.suspnd (nonexist_pid) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> print vms_sys.suspnd (None,"NO_SUCH_PRC") Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> ------------------------------------------------------------------------ PYVMS - Python on OpenVMS PAGE 7-86 vms_sys module 7.4.23 TIMCON - Time Converter Converts 128-bit Coordinated Universal Time (UTC) format to 64-bit system format or 64-bit system format to 128-bit UTC format based on the value of the convert flag. Format: utcadr = vms_sys.timcon ([timadr] , cvtflg=1) timadr = vms_sys.timcon ([utcadr] , cvtflg=0) Returns: timadr 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. utcadr 128-bit UTC value - an ASCII string of 32 hex characters. Arguments: timadr 64-bit system time - a Python 'long integer'. See 'Programming', 'special OpenVMS datatypes' for details. utcadr 128-bit UTC value - an ASCII string of 32 hex characters. cvtflg conversion flag indicating the direction of the conversion. Examples: >>> import vms_sys >>> utc_tim = vms_sys.getutc () >>> print vms_sys.ascutc (utc_tim) 12-AUG-1998 12:21:50.37 >>> utc_tim '103CFFFFFFFFFFFF01D231D6A4BBD020' >>> >>> bin_tim = vms_sys.timcon (utc_tim,0) >>> print vms_sys.asctim (bin_tim) 12-AUG-1998 12:21:50.37 >>> bin_tim 44096413103700000L >>> bin_tim = vms_sys.gettim () >>> print vms_sys.asctim (bin_tim) 12-AUG-1998 12:22:38.89 >>> bin_tim 44096413588900000L >>> >>> utc_tim = vms_sys.timcon (bin_tim,1) >>> print vms_sys.ascutc (utc_tim) 12-AUG-1998 12:22:38.89 PYVMS - Python on OpenVMS PAGE 7-87 vms_sys module >>> utc_tim '103CFFFFFFFFFFFF01D231D6C1A760A0' >>> bin_tim = vms_sys.gettim () >>> print vms_sys.asctim (bin_tim) 12-AUG-1998 12:23:23.05 >>> bin_tim 44096414030500000L >>> utc_tim = vms_sys.timcon (bin_tim,99) >>> print vms_sys.ascutc (utc_tim) 12-AUG-1998 12:23:23.05 >>> utc_tim '103CFFFFFFFFFFFF01D231D6DBF9A8A0' >>> bin_tim = vms_sys.timcon (None,0) >>> print vms_sys.asctim (bin_tim) 12-AUG-1998 12:23:59.63 >>> bin_tim = vms_sys.timcon ("",0) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be 32 hex characters >>> utc_tim = vms_sys.timcon (None,1) >>> print vms_sys.ascutc (utc_tim) 12-AUG-1998 12:24:49.06 >>> >>> utc_tim = vms_sys.timcon ("",1) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be long int >>> # bad chr -v >>> utc_tim = 'X103CFFFFFFFFFFFF01D1757F00EEC740' >>> bin_tim = vms_sys.timcon (utc_tim,0) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: must be 32 hex characters >>> ------------------------------------------------------------------------ 7.4.24 WAKE - Wake Process from Hibernation Activates a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service. Format: targpid = vms_sys.wake ([pidadr] [,prcnam]) Returns: PYVMS - Python on OpenVMS PAGE 7-88 vms_sys module targpid Process identification of process which has been waked. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.wake() raises a Python exception. Arguments: pidadr Process identification of process to be activated. prcnam Process name of process to be activated. Examples: >>> import vms_sys >>> print vms_sys.wake () 96 <-- PID of current process >>> wake_pid = 532 >>> print vms_sys.wake (wake_pid) 532 <-- PID of target process >>> print vms_sys.wake (wake_pid,None) 532 >>> vms_sys.wake (None,'TARG_PRC') 532 >>> vms_sys.wake (0,'TARG_PRC') 532 >>> nonexist_pid = 999 >>> vms_sys.wake (nonexist_pid) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.wake (None,'NONEXPRC') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> vms_sys.wake (1,2) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: expected None or string, int found >>> vms_sys.wake ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: pidadr must be integer or None >>> ------------------------------------------------------------------------ 12-AUG-1998 ZE. PYVMS - Python on OpenVMS PAGE 7-89 vms_sys module 7.5 'VMSDEF'-related modules 7.5.1 vms_dvidef module The 'vms_dvidef' module contains constants and bitmasks that are defined in '$DVIDEF'. Access to details of the item-codes is possible from the 'pyvms' module. The file VMSDEF_$DVIDEF.DAT is converted by the DCL procedure VMSDEF2MAR.COM to the file VMSDEF_$DVIDEF.MAR. This file 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'). @@ to be enhanced ------------------------------------------------------------------------ 01-MAR-1998 ZE. 7.5.2 vms_jpidef module The 'vms_jpidef' module contains constants and bitmasks that are defined in '$JPIDEF'. Access to details of the item-codes is possible from the 'pyvms' module. The file VMSDEF_$JPIDEF.DAT is converted by the DCL procedure VMSDEF2MAR.COM to the file VMSDEF_$JPIDEF.MAR. This file is then run through the macro assembler by using the following command: $ @DMACRO_VMS VMSDEF_$JPIDEF.MAR The resulting object file (VMSDEF_$JPIDEF.OBJ) is put into the object library in [.VMS.O_architecture]VMS_MACRO.OLB. ('architecture' is either 'ALPHA' or 'VAX'). @@ to be enhanced ------------------------------------------------------------------------ 01-MAR-1998 ZE. 7.5.3 vms_kgbdef module The 'vms_kgbdef' module contains constants and bitmasks that are defined in '$KGBDEF'. The current implementation of the 'vms_kgbdef' module uses the old-style C-tables! Access from the 'pyvms' module is currently not possible. @@ to be enhanced PYVMS - Python on OpenVMS PAGE 7-90 vms_kgbdef module ------------------------------------------------------------------------ 21-FEB-1998 ZE. 7.5.4 vms_lnmdef module The 'vms_lnmdef' module contains constants and bitmasks that are defined in '$LNMDEF'. Access to details of the item-codes is possible from the 'pyvms' module. The file VMSDEF_$LNMDEF.DAT is converted by the DCL procedure VMSDEF2MAR.COM to the file VMSDEF_$LNMDEF.MAR. This file is then run through the macro assembler by using the following command: $ @DMACRO_VMS VMSDEF_$LNMDEF.MAR The resulting object file (VMSDEF_$LNMDEF.OBJ) is put into the object library in [.VMS.O_architecture]VMS_MACRO.OLB. ('architecture' is either 'ALPHA' or 'VAX'). @@ to be enhanced ------------------------------------------------------------------------ 01-MAR-1998 ZE. 7.5.5 vms_quidef module The 'vms_quidef' module contains constants and bitmasks that are defined in '$QUIDEF'. Access to details of the item-codes is possible from the 'pyvms' module. The file VMSDEF_$QUIDEF.DAT is converted by the DCL procedure VMSDEF2MAR.COM to the file VMSDEF_$QUIDEF.MAR. This file is then run through the macro assembler by using the following command: $ @DMACRO_VMS VMSDEF_$QUIDEF.MAR The resulting object file (VMSDEF_$QUIDEF.OBJ) is put into the object library in [.VMS.O_architecture]VMS_MACRO.OLB. ('architecture' is either 'ALPHA' or 'VAX'). @@ to be enhanced ------------------------------------------------------------------------ 01-MAR-1998 ZE. 7.5.6 vms_syidef module The 'vms_syidef' module contains constants and bitmasks that are defined in '$SYIDEF'. Access to details of the item-codes is possible from the 'pyvms' module. PYVMS - Python on OpenVMS PAGE 7-91 vms_syidef module The file VMSDEF_$SYIDEF.DAT is converted by the DCL procedure VMSDEF2MAR.COM to the file VMSDEF_$SYIDEF.MAR. This file is then run through the macro assembler by using the following command: $ @DMACRO_VMS VMSDEF_$SYIDEF.MAR The resulting object file (VMSDEF_$SYIDEF.OBJ) is put into the object library in [.VMS.O_architecture]VMS_MACRO.OLB. ('architecture' is either 'ALPHA' or 'VAX'). @@ to be enhanced ------------------------------------------------------------------------ 01-MAR-1998 ZE. CHAPTER 8 Tools 8.1 coming with PYVMS 8.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: none PYVMS - Python on OpenVMS PAGE 8-2 CVT_DOC - convert .HTML to final docu formats ------------------------------------------------------------------------ 07-JUN-1998 ZE. 8.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] subdirectory 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. One can delete all versions of a '.RNO' file to force a new translation of the '.HTML' file. The [.VMS.DOC] directory also contains a procedure named CLEANUP.COM which deletes all files that will be created from running CVT_DOC.COM. 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 Arguments: none Example: $ @CVT__HTML %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 $ PYVMS - Python on OpenVMS PAGE 8-3 CVT__HTML - convert .HTML to .RNO ------------------------------------------------------------------------ 26-JUL-1998 ZE. 8.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: $ @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 $ ------------------------------------------------------------------------ 19-MAY-1998 ZE. 8.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. PYVMS - Python on OpenVMS PAGE 8-4 FILE_SET_DATE - alter CDT and RDT 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: $ 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. 8.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: PYVMS - Python on OpenVMS PAGE 8-5 HTML2RNO.PY - convert .HTML to .RNO 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' + 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' PYVMS - Python on OpenVMS PAGE 8-6 HTML2RNO.PY - convert .HTML to .RNO
        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 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
          
        

  PYVMS - Python on OpenVMS                                     PAGE 8-7
  HTML2RNO.PY - convert .HTML to .RNO


          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.

          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.



  8.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.

  PYVMS - Python on OpenVMS                                     PAGE 8-8
  UNTAR2DATESET - create procedure to change dates


  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
      $ 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.



  8.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 (the second)  release  moves  the  data,  again  with  some  more
  information,   into   a   number   of   text  files  with  names  like

  PYVMS - Python on OpenVMS                                     PAGE 8-9
  VMSDEF2MAR - convert a VMSDEF .DAT file to macro


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

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



  8.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').

  PYVMS - Python on OpenVMS                                    PAGE 8-10
  VMSDEF_BLDDIR2MAR - build VMSDEF directory


  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

      Total of 1 file.

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



  8.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'

  PYVMS - Python on OpenVMS                                    PAGE 8-11
  VMSVER2MAR - build VMS version table


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

  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.

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



  8.2  not delivered with PYVMS

  8.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!

  PYVMS - Python on OpenVMS                                    PAGE 8-12
  GZIP - (de)compress files to/from archive


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



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




  8.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

  PYVMS - Python on OpenVMS                                    PAGE 8-13
  VMSTAR - maintain TapeARchive file


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

                           The history of PYVMS



  9.1  the history of PYVMS

  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.

                                   ---

  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.

  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
  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

  PYVMS - Python on OpenVMS                                     PAGE 9-2
  PYVMS - history


  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.

  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.

  Python V1.5.1 was release 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 decus.decus.de at ??-MAY-1998.  @@
  The second snapshot (V1.5.1 V001P2) was put up on my private home page
  on decus.decus.de at 30-JUL-1998.
  The third snapshot (V1.5.1 V001P3) was released on 20-AUG-1998.
  ------------------------------------------------------------------------
  19-AUG-1998 ZE.












                                CHAPTER 10

                           The future of PYVMS



  10.1  the future of PYVMS

  What is planned for 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.
  ------------------------------------------------------------------------
  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.
  ------------------------------------------------------------------------
  12-AUG-1998 ZE.












                                CHAPTER 11

                                  Notes



  This chapter contains some notes about implementation details.



  11.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.

  ------------------------------------------------------------------------
    - command line editing
  |   The DCL environment uses an enhanced readline function from module
  |   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

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


  PYVMS - Python on OpenVMS                                    PAGE 11-2
  PYVMS notes


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

    - dynamic loading
      Nothing done. 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 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
  |   (08-MAR-1998) no way to call a routine in this image.

    - embedding Python
      No (real) work has been done to make 'callable Python'. I think one
      has to rip some things out of MAIN.C and put them into the resulting
      PYTHONSHR.EXE
  |   Python V1.5 might make things easier but currently (23-AUG-1997) it
  |   is not ready.
  |   19-DEC-1997: V1.5B2 is running, but I have not done anything.

    - 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.
  |   Some *experimental* code is in the [.VMS.EXPERIMENTAL] subdirectory.
  |   Experiments were done only on OpenVMS VAX.

  PYVMS - Python on OpenVMS                                    PAGE 11-3
  PYVMS notes


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

    - 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'.
  |   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

  PYVMS - Python on OpenVMS                                    PAGE 11-4
  PYVMS notes


  |   file. Expect changes in a future version!

  | - octaword (128 bit) support
  |   As far as I know Python does not support a 64 bit datatype nor a 128
  |   bit one. My workaround for some system services is to use a 'string
  |   of hex digits' and translate it internally (file VMS__CVT.C).

    - 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 int" datatype.

  |   Some work has been started to support OpenVMS Alpha V7.x features,
  |   but *no* 64-bit adressing is currently 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
  |   - 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 I haven't done anything
      in that area.
  |   Several procedures in the [.VMS] directory are very likely _NOT_
  |   thread-save !!

  | - 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:
  |------------------------------------------------------------

  PYVMS - Python on OpenVMS                                    PAGE 11-5
  PYVMS notes



  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".


  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.

  | - [.VMS] directory tree structure
  |
  |   [.VMS] - additional code and support files
  |     [.DEMO] - examples
  |     [.DOC]          - documentation about PYVMS
  |                          (and some support DCL files)
  |     [.EXPERIMENTAL] - ideas + tests for path conversions
  |     [.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

  PYVMS - Python on OpenVMS                                    PAGE 11-6
  PYVMS notes


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

  ------------------------------------------------------------------------
  15-AUG-1998 ZE.



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

  VMSDEF_DIRECTORY.MAR
    VMSDEF_GR_DIRECTORY::
    -- array of: pointer to item descriptor, pointer to bitmask/constants
        pointer descriptor, pointer to .ASCIZ name of DEFinition
        -> .address VMSDEF_GR_$QUIDEF
        -> .address VMSDEF_GR_CB_$QUIDEF
        -> .address VMSDEF_T_DIRECTORY__3
        ...
        -> .long    0 ; terminate list
        -> .long    0

        VMSDEF_T_DIRECTORY__3:  .asciz '$QUIDEF'
        ...
        (no termination necessary)

  ------------------------------------------------------------------------
  VMSDEF_$QUIDEF.MAR
    VMSDEF_GR_$QUIDEF::
    -- array of item descriptors
        -> .word    0001   ; QUI$_CANCEL_OPERATION
        -> .word    05520

  PYVMS - Python on OpenVMS                                    PAGE 11-7
  the VMSDEF data structures


        -> .word    32767
        -> .word    0
        -> .address VMSDEF_T_$QUIDEF__1
        -> .long    0
        -> .long    7
        -> .word    00000
        -> .byte    ^A'L'
        -> .byte    ^A'L'
        ...
        .word    0133   ; QUI$_MANAGER_STATUS
        .word    06000
        .word    32767
        .word    0
        .address VMSDEF_T_$QUIDEF__75
        .address VMSDEF_AR_QUI_QUEUE_MGR        ; --->
        .long    11
        .word    00004
        .byte    ^A'L'
        .byte    ^A'L'
        ...
        .word    0
        .word    0      ; THIS 0 terminates the ITEM list

    -- 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    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        1               <-- type (1=bitmask)
        ...
        -> .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)

  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS                                    PAGE 11-8
  the VMSDEF data structures


  07-JUN-1998 ZE.

  Index                                                     PAGE INDEX-1
   


                                  INDEX



  files                                 VMSDEF_$DVIDEF.DAT, 7-89, 8-8
    CLEANUP.COM, 8-2                    VMSDEF_$DVIDEF.MAR, 7-89, 8-9
    CVT__HTML.COM, 8-2                  VMSDEF_$JPIDEF.DAT, 7-89
    CVT__RNO.COM, 8-3                   VMSDEF_$JPIDEF.MAR, 7-89
    CVT_DOC.COM, 8-1                    VMSDEF_$LNMDEF.DAT, 7-90
    FILE_SET_DATE.C, 8-3                VMSDEF_$LNMDEF.MAR, 7-90
    GETPATH.C, 5-1                      VMSDEF_$QUIDEF.DAT, 7-90
    IMPORT.C, 3-6                       VMSDEF_$QUIDEF.MAR, 7-90
    POSIXMODULE.C, 11-2                 VMSDEF_$SYIDEF.DAT, 7-91
    python1.5.1.tar.gz, 4-1             VMSDEF_$SYIDEF.MAR, 7-91
    PYTHON1_5_1.TAR-GZ, 4-1             VMSDEF_DIRECTORY.MAR, 8-9, 11-6
    PYTHONSTARTUP.PY, 11-4
    pyvms1.5.1-v001.readme, 1-2       software
    pyvms1.5.1-v001doc.tlb, 1-3,        browsers, 2-1
        4-8                             HTTP servers, 2-1
    pyvms1.5.1-v001doc.txt, 1-3,      symbols
        4-8                             PYTHON, 4-7
    pyvms1.5.1-v001src.zip, 1-2,        PYTHONPATH, 4-7
        4-1                             PYTHONSTARTUP, 4-7
    PYVMS1_5_1-V001SRC.ZIP, 4-1         PYTHONUNBUFFERED, 4-7
    PYVMS_READLINE.C, 11-1
    SETUP.COM, 4-7, 8-2
    TXT.FDL, 2-2                      tools
    UNTAR2DATESET.COM, 8-7              CVT__HTML, 8-2
    VMS__CVT.C, 11-4                    CVT__RNO, 8-3
    VMS__GETPATH.C, 5-1                 CVT_DOC, 8-1
    VMS__GETTIMEOFDAY.C, 11-3           FILE_SET_DATE, 4-4, 8-3, 8-8
    VMS__GMTIME.C, 11-3                 GZIP, 4-2, 8-11 to 8-12
    VMS__RMDIR.C, 11-4                  UNTAR2DATESET, 4-4, 8-3, 8-7
    VMS__UTIME.C, 11-4                  UNZIP, 4-2, 8-12
    VMSDAT_VMSVER.DAT, 8-10             VMSTAR, 4-2, 8-3, 8-7, 8-11 to
    VMSDAT_VMSVER.MAR, 8-10                 8-12