Python for OpenVMS -Reference Manual PAGE 1 title page __ | \ | | _ |__/ | | - / \ -O- | \ / \_/ \_/ | | ___ / / | \/ / | /\ |- ( )--| \/ / /\ | / / --- Copyright, 1996 - 2001 by Uwe Zessin ------------------------------------------------------------------------ Python for OpenVMS - Reference Manual July 2001 This manual is of special interest for the programmer. It explains which modules exist, what interface routines to OpenVMS routines are available and how to work with them. Finally it shows how to work with special 'VMS objects'. Software Version: 2.1.1-V001 Uwe Zessin, Germany ------------------------------------------------------------------------ 27-JUL-2001 ZE. Python for OpenVMS -Reference Manual PAGE 2 the Python license 0.1 the Python license (copied from LICENSE.) A. HISTORY OF THE SOFTWARE ========================== Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI) in the Netherlands as a successor of a language called ABC. Guido is Python's principal author, although it includes many contributions from others. The last version released from CWI was Python 1.2. In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI) in Reston, Virginia where he released several versions of the software. Python 1.6 was the last of the versions released by CNRI. In 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. Python 2.0 was the first and only release from BeOpen.com. Following the release of Python 1.6, and after Guido van Rossum left CNRI to work with commercial software developers, it became clear that the ability to use Python with software available under the GNU Public License (GPL) was very desirable. CNRI and the Free Software Foundation (FSF) interacted to develop enabling wording changes to the Python license. Python 1.6.1 is essentially the same as Python 1.6, with a few minor bug fixes, and with a different license that enables later versions to be GPL-compatible. Python 2.1 is a derivative work of Python 1.6.1, as well as of Python 2.0. After Python 2.0 was released by BeOpen.com, Guido van Rossum and the other PythonLabs developers joined Digital Creations. All intellectual property added from this point on, starting with Python 2.1 and its alpha and beta releases, is owned by the Python Software Foundation (PSF), a non-profit modeled after the Apache Software Foundation. See http://www.python.org/psf/ for more information about the PSF. Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible. B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON =============================================================== PSF LICENSE AGREEMENT --------------------- 1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using Python 2.1.1 software in source or binary form and its associated documentation. 2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide Python for OpenVMS -Reference Manual PAGE 3 the Python license license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.1.1 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2001 Python Software Foundation; All Rights Reserved" are retained in Python 2.1.1 alone or in any derivative version prepared by Licensee. 3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.1.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.1.1. 4. PSF is making Python 2.1.1 available to Licensee on an "AS IS" basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.1.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.1.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.1.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. 6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. 7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. 8. By copying, installing or otherwise using Python 2.1.1, Licensee agrees to be bound by the terms and conditions of this License Agreement. BEOPEN.COM TERMS AND CONDITIONS FOR PYTHON 2.0 ---------------------------------------------- BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization ("Licensee") accessing and otherwise using this software in source or binary form and its associated documentation ("the Software"). 2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and Python for OpenVMS -Reference Manual PAGE 4 the Python license otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee. 3. BeOpen is making the Software available to Licensee on an "AS IS" basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. 4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. 5. This License Agreement will automatically terminate upon a material breach of its terms and conditions. 6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the "BeOpen Python" logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page. 7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement. CNRI OPEN SOURCE GPL-COMPATIBLE LICENSE AGREEMENT ------------------------------------------------- 1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 ("CNRI"), and the Individual or Organization ("Licensee") accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation. 2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., "Copyright (c) 1995-2001 Corporation for National Research Initiatives; All Rights Reserved" are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the Python for OpenVMS -Reference Manual PAGE 5 the Python license quotes): "Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013". 3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1. 4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. 5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. 6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. 7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. 8. By clicking on the "ACCEPT" button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement. ACCEPT CWI PERMISSIONS STATEMENT AND DISCLAIMER Python for OpenVMS -Reference Manual PAGE 6 the Python license ---------------------------------------- Copyright (c) 1991 - 1995, 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 name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM 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. ------------------------------------------------------------------------ 22-JUL-2001 ZE. Python for OpenVMS -Reference Manual PAGE 7 the Python for OpenVMS license 0.2 The Python for OpenVMS license Copyright 1996-2001, 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. ------------------------------------------------------------------------ 22-JUL-2001 ZE. Python for OpenVMS -Reference Manual PAGE 8 table of contents CONTENTS 0.1 the Python license . . . . . . . . . . . . . . . . 2 0.2 The Python for OpenVMS license . . . . . . . . . . 7 CHAPTER 1 Introduction 1.1 Welcome . . . . . . . . . . . . . . . . . . . . . 1-1 CHAPTER 2 Modules 2.1 pyvms module . . . . . . . . . . . . . . . . . . . 2-1 2.1.1 PYLIB_GETPASS - get password from terminal . . . 2-6 2.1.2 CRTL_FROM_VMS - call decc$from_vms() routine . . 2-7 2.1.3 CRTL_OPEN - call C RTL open() routine . . . . 2-10 2.1.4 CRTL_TO_VMS - call decc$to_vms() routine . . . 2-13 2.1.5 FILE_OPEN - call C RTL fopen() routine . . . . 2-17 2.1.6 UAF_GET_USERNAMES - Get list of usernames from authorization file . . . . . . . . . . . . . . 2-19 2.2 vms_lbr module . . . . . . . . . . . . . . . . . 2-22 2.2.1 OUTPUT_HELP - Output Help Messages . . . . . . 2-23 2.3 vms_lib module . . . . . . . . . . . . . . . . . 2-28 2.3.1 ADD_TIMES - Add Two Quadword Times . . . . . . 2-29 2.3.2 ASN_WTH_MBX - Assign Channel with Mailbox . . 2-31 2.3.3 ATTACH - Attach Terminal to Process . . . . . 2-33 2.3.4 CONVERT_DATE_STRING - Convert Date String to Quadword . . . . . . . . . . . . . . . . . . . 2-34 2.3.5 CREATE_DIR - Create a Directory . . . . . . . 2-36 2.3.6 CURRENCY - Get System Currency Symbol . . . . 2-37 2.3.7 CVTF_FROM_INTERNAL_TIME - Convert Internal Time to External Time . . . . . . . . . . . . . . . 2-37 2.3.8 CVTF_TO_INTERNAL_TIME - Convert External Time to Internal Time . . . . . . . . . . . . . . . 2-40 2.3.9 CVT_FROM_INTERNAL_TIME - Convert Internal Time to External Time . . . . . . . . . . . . . . . 2-42 2.3.10 CVT_TO_INTERNAL_TIME - Convert External Time to Internal Time . . . . . . . . . . . . . . . . 2-45 2.3.11 CVT_VECTIM - Convert 7-Word Vector to Internal Time . . . . . . . . . . . . . . . . . . . . . 2-47 2.3.12 DATE_TIME - Date and Time Returned as a String 2-48 2.3.13 DAY - Day Number Returned as a Longword Integer 2-49 2.3.14 DAY_OF_WEEK - Show Numeric Day of Week . . . . 2-50 2.3.15 DELETE_FILE - Delete One or More Files . . . . 2-51 2.3.16 DELETE_LOGICAL - Delete Logical Name . . . . . 2-55 2.3.17 DELETE_SYMBOL - Delete CLI Symbol . . . . . . 2-58 2.3.18 DIGIT_SEP - Get Digit Separator Symbol . . . . 2-59 2.3.19 DO_COMMAND - Execute Command . . . . . . . . . 2-60 2.3.20 FID_TO_NAME - Convert Device and File ID to File Specification . . . . . . . . . . . . . . 2-61 2.3.21 FIND_FILE - Find File . . . . . . . . . . . . 2-63 2.3.22 FIND_FILE_END - End of Find File . . . . . . . 2-67 Python for OpenVMS -Reference Manual PAGE 9 table of contents 2.3.23 FIND_IMAGE_SYMBOL - Find Universal Symbol in Shareable Image File . . . . . . . . . . . . . 2-67 2.3.24 FORMAT_DATE_TIME - Format Date and/or Time . . 2-68 2.3.25 FORMAT_SOGW_PROT - Translate a protection mask into a formatted . . . . . . . . . . . . . . . 2-70 2.3.26 FREE_DATE_TIME_CONTEXT - Free the Context Area Used When . . . . . . . . . . . . . . . . . . 2-71 2.3.27 FREE_EF - Free Event Flag . . . . . . . . . . 2-72 2.3.28 GETDVI - Get Device/Volume Information . . . . 2-73 2.3.29 GETJPI - Get Job/Process Information . . . . . 2-75 2.3.30 GETQUI - Get Queue Information . . . . . . . . 2-78 2.3.31 GETSYI - Get Systemwide Information . . . . . 2-82 2.3.32 GET_ACCNAM - Get Access Name Table for Protected Object Class . . . . . . . . . . . . 2-84 2.3.33 GET_ACCNAM_BY_CONTEXT - Get Access Name Table for Protected Object . . . . . . . . . . . . . 2-85 2.3.34 GET_COMMAND - Get Line from SYS$COMMAND . . . 2-86 2.3.35 GET_COMMON - Get String from Common . . . . . 2-88 2.3.36 GET_DATE_FORMAT - Get the User's Date Input Format . . . . . . . . . . . . . . . . . . . . 2-88 2.3.37 GET_EF - Get Event Flag . . . . . . . . . . . 2-89 2.3.38 GET_FOREIGN - Get Foreign Command Line . . . . 2-90 2.3.39 GET_MAXIMUM_DATE_LENGTH - Retrieve the Maximum Length of a . . . . . . . . . . . . . . . . . 2-92 2.3.40 GET_SYMBOL - Get Value of CLI Symbol . . . . . 2-93 2.3.41 GET_USERS_LANGUAGE - Return the User's Language 2-95 2.3.42 INIT_DATE_TIME_CONTEXT - Initialize the Context Area Used in . . . . . . . . . . . . . . . . . 2-96 2.3.43 LP_LINES - Lines on Each Printer Page . . . . 2-98 2.3.44 PARSE_ACCESS_CODE - Parse Access Encoded Name String . . . . . . . . . . . . . . . . . . . . 2-98 2.3.45 PARSE_SOGW_PROT - Parse Protection String . . 2-100 2.3.46 PUT_COMMON - Put String to Common . . . . . . 2-102 2.3.47 PUT_OUTPUT - Put Line to SYS$OUTPUT . . . . . 2-103 2.3.48 RADIX_POINT - Radix Point Symbol . . . . . . . 2-104 2.3.49 RENAME_FILE - Rename One or More Files . . . . 2-105 2.3.50 RESERVE_EF - Reserve Event Flag . . . . . . . 2-110 2.3.51 RUN_PROGRAM - Run New Program . . . . . . . . 2-111 2.3.52 SET_LOGICAL - Set Logical Name . . . . . . . . 2-112 2.3.53 SET_SYMBOL - Set Value of CLI Symbol . . . . . 2-115 2.3.54 SUB_TIMES - Subtract Two Quadword Times . . . 2-117 2.3.55 TRIM_FILESPEC - Fit Long File Specification into Fixed Field . . . . . . . . . . . . . . . 2-119 2.3.56 WAIT - Wait a Specified Period of Time . . . . 2-121 2.4 vms_mail module . . . . . . . . . . . . . . . . 2-122 2.5 vms_smg module . . . . . . . . . . . . . . . . . 2-123 2.5.1 BEGIN_DISPLAY_UPDATE - Begin Batching of Display Updates . . . . . . . . . . . . . . . 2-125 2.5.2 BEGIN_PASTEBOARD_UPDATE - Begin Batching of Pasteboard Updates . . . . . . . . . . . . . . 2-127 2.5.3 CHANGE_PBD_CHARACTERISTICS - Change Pasteboard Characteristics . . . . . . . . . . . . . . . 2-129 2.5.4 CHANGE_RENDITION - Change Default Rendition . 2-131 Python for OpenVMS -Reference Manual PAGE 10 table of contents 2.5.5 CHANGE_VIEWPORT - Change Viewport associated with a Virtual . . . . . . . . . . . . . . . . 2-134 2.5.6 CHANGE_VIRTUAL_DISPLAY - Change Virtual Display . . . . . . . . . . . . . . . . . . . 2-137 2.5.7 CHECK_FOR_OCCLUSION - Check for Occlusion . . 2-139 2.5.8 CONTROL_MODE - Control mode . . . . . . . . . 2-142 2.5.9 COPY_VIRTUAL_DISPLAY - Copy Virtual Display . 2-144 2.5.10 CREATE_PASTEBOARD - Create a Pasteboard . . . 2-146 2.5.11 CREATE_VIEWPORT - Create a Virtual Viewport . 2-149 2.5.12 CREATE_VIRTUAL_DISPLAY - Create a Virtual Display . . . . . . . . . . . . . . . . . . . 2-152 2.5.13 CREATE_VIRTUAL_KEYBOARD - Create a Virtual Keyboard . . . . . . . . . . . . . . . . . . . 2-153 2.5.14 DELETE_CHARS - Delete Characters . . . . . . . 2-154 2.5.15 DELETE_LINE - Delete Line . . . . . . . . . . 2-157 2.5.16 DELETE_PASTEBOARD - Delete Pasteboard . . . . 2-159 2.5.17 DELETE_VIEWPORT - Delete a Viewport . . . . . 2-160 2.5.18 DELETE_VIRTUAL_DISPLAY - Delete Virtual Display . . . . . . . . . . . . . . . . . . . 2-162 2.5.19 DELETE_VIRTUAL_KEYBOARD - Delete Virtual Keyboard . . . . . . . . . . . . . . . . . . . 2-163 2.5.20 DRAW_CHAR - Draw a Character in a Virtual Display . . . . . . . . . . . . . . . . . . . 2-164 2.5.21 DRAW_LINE - Draw a horizontal or vertical line 2-166 2.5.22 DRAW_RECTANGLE - Draw a Rectangle . . . . . . 2-168 2.5.23 END_DISPLAY_UPDATE - End Display Update . . . 2-170 2.5.24 END_PASTEBOARD_UPDATE - End Pasteboard Update 2-171 2.5.25 ERASE_CHARS - Erase Characters . . . . . . . . 2-171 2.5.26 ERASE_COLUMN - Erase Column from Display . . . 2-174 2.5.27 ERASE_DISPLAY - Erase Virtual Display . . . . 2-176 2.5.28 ERASE_LINE - Erase Line . . . . . . . . . . . 2-178 2.5.29 ERASE_PASTEBOARD - Erase Pasteboard . . . . . 2-181 2.5.30 FIND_CURSOR_DISPLAY - Find Display that Contains the Cursor . . . . . . . . . . . . . 2-182 2.5.31 FLUSH_BUFFER - Flush Buffer . . . . . . . . . 2-185 2.5.32 FLUSH_DISPLAY_UPDATE - Flush Display Update . 2-185 2.5.33 VMS_SMG_GET_CHAR_AT_PHYSICAL_CURSOR - Return Character at Cursor . . . . . . . . . . . . . 2-188 2.5.34 VMS_SMG_GET_DISPLAY_ATTR - Return Character at Cursor . . . . . . . . . . . . . . . . . . . . 2-189 2.5.35 VMS_SMG_GET_KEYBOARD_ATTRIBUTES - Get Keyboard Attributes . . . . . . . . . . . . . . . . . . 2-191 2.5.36 GET_PASTEBOARD_ATTRIBUTES - Get Pasteboard Attributes . . . . . . . . . . . . . . . . . . 2-193 2.5.37 GET_PASTING_INFO - Return Pasting Information 2-194 2.5.38 GET_VIEWPORT_CHAR - Get Characteristics of Display Viewport . . . . . . . . . . . . . . . 2-197 2.5.39 HOME_CURSOR - Home Cursor . . . . . . . . . . 2-199 2.5.40 INSERT_CHARS - Insert Characters . . . . . . . 2-201 2.5.41 INSERT_LINE - Insert Line . . . . . . . . . . 2-204 2.5.42 INVALIDATE_DISPLAY - Mark a Display as Invalid 2-207 2.5.43 KEYCODE_TO_NAME - Translate a Key Code into a Key Name . . . . . . . . . . . . . . . . . . . 2-209 2.5.44 LABEL_BORDER - Label a Virtual Display Border 2-210 Python for OpenVMS -Reference Manual PAGE 11 table of contents 2.5.45 LIST_PASTEBOARD_ORDER - Return Pasting Information . . . . . . . . . . . . . . . . . 2-213 2.5.46 LIST_PASTING_ORDER - Return Virtual Display Pasting Information . . . . . . . . . . . . . 2-216 2.5.47 LOAD_VIRTUAL_DISPLAY - Load a Virtual Display from a File . . . . . . . . . . . . . . . . . 2-219 2.5.48 MOVE_TEXT - Move Text from One Virtual Display to Another . . . . . . . . . . . . . . . . . . 2-222 2.5.49 MOVE_VIRTUAL_DISPLAY - Move Virtual Display . 2-225 2.5.50 NAME_TO_KEYCODE - Translate a Key Name into a Key Code . . . . . . . . . . . . . . . . . . . 2-228 2.5.51 PASTE_VIRTUAL_DISPLAY - Paste a Virtual Display . . . . . . . . . . . . . . . . . . . 2-229 2.5.52 POP_VIRTUAL_DISPLAY - Delete a Series of Virtual Displays . . . . . . . . . . . . . . . 2-231 2.5.53 PRINT_PASTEBOARD - Print Pasteboard Using a Print Queue . . . . . . . . . . . . . . . . . 2-234 2.5.54 PUT_CHARS - Write Characters to a Virtual Display . . . . . . . . . . . . . . . . . . . 2-236 2.5.55 PUT_CHARS_HIGHWIDE - Write Double-Height Double-Width Characters . . . . . . . . . . . 2-238 2.5.56 PUT_CHARS_MULTI - Put Text with Multiple Renditions to Display . . . . . . . . . . . . 2-240 2.5.57 PUT_CHARS_WIDE - Write Double-Width Characters 2-242 2.5.58 VMS_SMG_PUT_HELP_TEXT - Output Help Text to the Display . . . . . . . . . . . . . . . . . 2-244 2.5.59 PUT_LINE - Write Line to Virtual Display . . . 2-249 2.5.60 PUT_LINE_HIGHWIDE - Write Double-Height and Double-Width Line . . . . . . . . . . . . . . 2-253 2.5.61 PUT_LINE_MULTI - Write Line with Multiple Renditions to Display . . . . . . . . . . . . 2-256 2.5.62 PUT_LINE_WIDE - Write Double-Width Line . . . 2-259 2.5.63 PUT_STATUS_LINE - Output Line of Text to Hardware Status Line . . . . . . . . . . . . . 2-263 2.5.64 READ_FROM_DISPLAY - Read Text from Display . . 2-265 2.5.65 READ_KEYSTROKE - Read a Single Character . . . 2-268 2.5.66 READ_STRING - Read String . . . . . . . . . . 2-272 2.5.67 REMOVE_LINE - Remove a Line from a Virtual Display . . . . . . . . . . . . . . . . . . . 2-276 2.5.68 REPAINT_LINE - Repaint One or More Lines on the Current Pasteboard . . . . . . . . . . . . 2-278 2.5.69 REPAINT_SCREEN - Repaint Current Pasteboard . 2-281 2.5.70 REPASTE_VIRTUAL_DISPLAY - Repaste Virtual Display . . . . . . . . . . . . . . . . . . . 2-283 2.5.71 RESTORE_PHYSICAL_SCREEN - Restore Physical Pasteboard . . . . . . . . . . . . . . . . . . 2-286 2.5.72 RETURN_CURSOR_POS - Return Cursor Position . . 2-288 2.5.73 RING_BELL - Ring the Terminal Bell or Buzzer . 2-290 2.5.74 SAVE_PHYSICAL_SCREEN - Save Physical Screen . 2-291 2.5.75 SAVE_VIRTUAL_DISPLAY - Save the Virtual Display to a File . . . . . . . . . . . . . . 2-292 2.5.76 SCROLL_DISPLAY_AREA - Scroll Display Area . . 2-293 2.5.77 SCROLL_VIEWPORT - Scroll a Display Under a Viewport . . . . . . . . . . . . . . . . . . . 2-296 Python for OpenVMS -Reference Manual PAGE 12 table of contents 2.5.78 SET_CURSOR_ABS - Set Absolute Cursor Position 2-300 2.5.79 SET_CURSOR_MODE - Set the Cursor Mode . . . . 2-301 2.5.80 SET_CURSOR_REL - Move Cursor Relative . . . . 2-303 2.5.81 SET_DISPLAY_SCROLL_REGION - Create Display Scrolling Region . . . . . . . . . . . . . . . 2-305 2.5.82 SET_KEYPAD_MODE - Set Keypad Mode . . . . . . 2-308 2.5.83 SET_PHYSICAL_CURSOR - Set Cursor on Physical Screen . . . . . . . . . . . . . . . . . . . . 2-312 2.5.84 UNPASTE_VIRTUAL_DISPLAY - Remove a Virtual Display . . . . . . . . . . . . . . . . . . . 2-314 2.6 vms_sys module . . . . . . . . . . . . . . . . . 2-317 2.6.1 ADD_HOLDER - Add Holder Record to Rights Database . . . . . . . . . . . . . . . . . . . 2-318 2.6.2 ADD_IDENT - Add Identifier to Rights Database 2-321 2.6.3 ADD_PROXY - Add or Modify Proxy . . . . . . . 2-322 2.6.4 ASCEFC - Associate Common Event Flag Cluster . 2-324 2.6.5 ASCTIM - Convert Binary Time to ASCII String . 2-324 2.6.6 ASCTOID - Translate Identifier Name to Identifier . . . . . . . . . . . . . . . . . . 2-326 2.6.7 ASCUTC - Convert UTC to ASCII . . . . . . . . 2-327 2.6.8 BINTIM - Convert ASCII String to Binary Time . 2-328 2.6.9 BINUTC - Convert ASCII String to UTC Binary Time . . . . . . . . . . . . . . . . . . . . . 2-329 2.6.10 BRKTHRUW - Breakthrough and Wait . . . . . . . 2-330 2.6.11 CANWAK - Cancel Wakeup . . . . . . . . . . . . 2-332 2.6.12 CLREF - Clear Event Flag . . . . . . . . . . . 2-334 2.6.13 CRELNM - Create Logical Name . . . . . . . . . 2-336 2.6.14 CRELNT - Create Logical Name Table . . . . . . 2-339 2.6.15 CREPRC - Create Process . . . . . . . . . . . 2-341 2.6.16 DACEFC - Disassociate Common Event Flag Cluster . . . . . . . . . . . . . . . . . . . 2-347 2.6.17 DASSGN - Deassign I/O Channel . . . . . . . . 2-348 2.6.18 DELETE_INTRUSION - Delete Intrusion Records . 2-349 2.6.19 DELETE_PROXY - Delete or Modify Proxy . . . . 2-350 2.6.20 DELLNM - Delete Logical Name . . . . . . . . . 2-351 2.6.21 DELPRC - Delete Process . . . . . . . . . . . 2-353 2.6.22 DEQ - Dequeue Lock Request . . . . . . . . . . 2-355 2.6.23 DEVICE_SCAN - Scan for Devices . . . . . . . . 2-356 2.6.24 DISMOU - Dismount Volume . . . . . . . . . . . 2-359 2.6.25 DISPLAY_PROXY - Display Proxy Information . . 2-360 2.6.26 DLCEFC - Delete Common Event Flag Cluster . . 2-362 2.6.27 ENQW - Enqueue Lock Request . . . . . . . . . 2-362 2.6.28 FILESCAN - Scan String for File Specification 2-365 2.6.29 FIND_HELD - Find Identifiers Held by User . . 2-368 2.6.30 FIND_HOLDER - Find Holder of Identifier . . . 2-371 2.6.31 FINISH_RDB - Terminate Rights Database Context 2-374 2.6.32 FORCEX - Force Exit . . . . . . . . . . . . . 2-375 2.6.33 FORMAT_ACL - Format Access Control List Entry 2-377 2.6.34 GETJPIW - Get Job/Process Information . . . . 2-379 2.6.35 GETMSG - Get Message . . . . . . . . . . . . . 2-383 2.6.36 GETQUIW - Get Queue Information . . . . . . . 2-385 2.6.37 GETTIM - Returns the current system time in a 64-bit format . . . . . . . . . . . . . . . . 2-393 2.6.38 GETUAI - Get User Authorization Information . 2-393 Python for OpenVMS -Reference Manual PAGE 13 table of contents 2.6.39 GETUTC - Get UTC Time . . . . . . . . . . . . 2-403 2.6.40 GET_SECURITY - Get Security Characteristics . 2-404 2.6.41 GRANTID - Grant Identifier to Process . . . . 2-409 2.6.42 HIBER - Hibernate . . . . . . . . . . . . . . 2-412 2.6.43 IDTOASC - Translate Identifier to Identifier Name . . . . . . . . . . . . . . . . . . . . . 2-413 2.6.44 INIT_VOL - Initialize Volume . . . . . . . . . 2-415 2.6.45 MOD_HOLDER - Modify Holder Record in Rights Database . . . . . . . . . . . . . . . . . . . 2-417 2.6.46 MOD_IDENT - Modify Identifier in Rights Database . . . . . . . . . . . . . . . . . . . 2-419 2.6.47 MOUNT - Mount Volume . . . . . . . . . . . . . 2-421 2.6.48 NUMTIM - Convert Binary Time to Numeric Time . 2-422 2.6.49 NUMUTC - Convert UTC Time to Numeric Components . . . . . . . . . . . . . . . . . . 2-423 2.6.50 PARSE_ACL - Parse Access Control List Entry . 2-425 2.6.51 PERSONA_ASSUME - Assume Persona . . . . . . . 2-426 2.6.52 PERSONA_CREATE - Create Persona . . . . . . . 2-427 2.6.53 PERSONA_DELETE - Create Persona . . . . . . . 2-428 2.6.54 PROCESS_SCAN - Process Scan . . . . . . . . . 2-428 2.6.55 PURGWS - Purge Working Set . . . . . . . . . . 2-433 2.6.56 READEF - Read Event Flags . . . . . . . . . . 2-434 2.6.57 REM_HOLDER - Remove Holder Record from Rights Database . . . . . . . . . . . . . . . . . . . 2-436 2.6.58 REM_IDENT - Remove Identifier from Rights Database . . . . . . . . . . . . . . . . . . . 2-438 2.6.59 RESUME - Resume Process . . . . . . . . . . . 2-440 2.6.60 REVOKID - Revoke Identifier from Process . . . 2-441 2.6.61 SCAN_INTRUSION - Scan Intrusion Database . . . 2-444 2.6.62 SCHDWK - Schedule Wakeup . . . . . . . . . . . 2-446 2.6.63 SETDDIR - Set Default Directory . . . . . . . 2-448 2.6.64 SETDFPROT - Set Default File Protection . . . 2-450 2.6.65 SETEF - Set Event Flag . . . . . . . . . . . . 2-451 2.6.66 SETPRI - Set Priority . . . . . . . . . . . . 2-453 2.6.67 SETPRN - Set Process Name . . . . . . . . . . 2-455 2.6.68 SETPRV - Set Privilege . . . . . . . . . . . . 2-456 2.6.69 SETSWM - Set Process Swap Mode . . . . . . . . 2-460 2.6.70 SETUAI - Set User Authorization Information . 2-461 2.6.71 SET_RESOUCE_DOMAIN - Set Resource Domain . . . 2-469 2.6.72 SET_SECURITY - Set Security Characteristics . 2-471 2.6.73 SHOW_INTRUSION - Show Intrusion Information . 2-473 2.6.74 SNDJBCW - Send to Job Controller . . . . . . . 2-476 2.6.75 SUBSYSTEM - Subsystem . . . . . . . . . . . . 2-482 2.6.76 SUSPND - Suspend Process . . . . . . . . . . . 2-483 2.6.77 TIMCON - Time Converter . . . . . . . . . . . 2-485 2.6.78 TRNLNM - Translate Logical Name . . . . . . . 2-487 2.6.79 VERIFY_PROXY - Verify a Proxy . . . . . . . . 2-491 2.6.80 WAITFR - Wait for Single Event Flag . . . . . 2-492 2.6.81 WAKE - Wake Process from Hibernation . . . . . 2-493 2.6.82 WFLAND - Wait for Logical AND of Event Flags . 2-494 2.6.83 WFLOR - Wait for Logical OR of Event Flags . . 2-495 2.7 vms__struct module . . . . . . . . . . . . . . . 2-496 2.7.1 CALCSIZE - Calculate buffer size from format string . . . . . . . . . . . . . . . . . . . . 2-496 Python for OpenVMS -Reference Manual PAGE 14 table of contents 2.7.2 PACK - Compose list of Python objects into string . . . . . . . . . . . . . . . . . . . . 2-497 2.7.3 UNPACK - DeCompose a string or a 'vmsobj__membuf' object into a . . . . . . . . 2-501 2.7.4 format string description . . . . . . . . . . 2-501 2.8 'VMSDEF'-related modules . . . . . . . . . . . . 2-505 2.8.1 maintaining VMSDEF modules . . . . . . . . . . 2-505 2.8.2 vms_brkdef module . . . . . . . . . . . . . . 2-506 2.8.3 vms_ciadef module . . . . . . . . . . . . . . 2-506 2.8.4 vms_dcdef module . . . . . . . . . . . . . . . 2-507 2.8.5 vms_dmtdef module . . . . . . . . . . . . . . 2-507 2.8.6 vms_dvidef module . . . . . . . . . . . . . . 2-507 2.8.7 vms_dvsdef module . . . . . . . . . . . . . . 2-508 2.8.8 vms_fabdef module . . . . . . . . . . . . . . 2-508 2.8.9 vms_fscndef module . . . . . . . . . . . . . . 2-508 2.8.10 vms_initdef module . . . . . . . . . . . . . . 2-509 2.8.11 vms_jpidef module . . . . . . . . . . . . . . 2-509 2.8.12 vms_kgbdef module . . . . . . . . . . . . . . 2-510 2.8.13 vms_lbrdef module . . . . . . . . . . . . . . 2-510 2.8.14 vms_lckdef module . . . . . . . . . . . . . . 2-510 2.8.15 vms_lnmdef module . . . . . . . . . . . . . . 2-511 2.8.16 vms_maildef module . . . . . . . . . . . . . . 2-511 2.8.17 vms_mntdef module . . . . . . . . . . . . . . 2-512 2.8.18 vms_namdef module . . . . . . . . . . . . . . 2-512 2.8.19 vms_ossdef module . . . . . . . . . . . . . . 2-512 2.8.20 vms_prcdef module . . . . . . . . . . . . . . 2-513 2.8.21 vms_prvdef module . . . . . . . . . . . . . . 2-513 2.8.22 vms_pscandef module . . . . . . . . . . . . . 2-514 2.8.23 vms_quidef module . . . . . . . . . . . . . . 2-514 2.8.24 vms_rabdef module . . . . . . . . . . . . . . 2-514 2.8.25 vms_rsdmdef module . . . . . . . . . . . . . . 2-515 2.8.26 vms_sjcdef module . . . . . . . . . . . . . . 2-515 2.8.27 vms_smgdef module . . . . . . . . . . . . . . 2-515 2.8.28 vms_statedef module . . . . . . . . . . . . . 2-516 2.8.29 vms_syidef module . . . . . . . . . . . . . . 2-516 2.8.30 vms_trmdef module . . . . . . . . . . . . . . 2-516 2.8.31 vms_uaidef module . . . . . . . . . . . . . . 2-517 2.8.32 vms_xaballdef module . . . . . . . . . . . . . 2-517 2.8.33 vms_xabdatdef module . . . . . . . . . . . . . 2-517 2.8.34 vms_xabfhcdef module . . . . . . . . . . . . . 2-517 2.8.35 vms_xabitmdef module . . . . . . . . . . . . . 2-518 2.8.36 vms_xabkeydef module . . . . . . . . . . . . . 2-518 2.8.37 vms_xabprodef module . . . . . . . . . . . . . 2-519 CHAPTER 3 VMS Objects 3.0.1 vmsobj_fab object . . . . . . . . . . . . . . . 3-3 3.0.2 vmsobj_iosb object . . . . . . . . . . . . . . . 3-8 3.0.3 vmsobj_lksb object . . . . . . . . . . . . . . 3-11 3.0.4 vmsobj_nam object . . . . . . . . . . . . . . 3-13 3.0.5 vmsobj_rab object . . . . . . . . . . . . . . 3-16 3.0.6 vmsobj_xaball object . . . . . . . . . . . . . 3-21 3.0.7 vmsobj_xabdat object . . . . . . . . . . . . . 3-23 Python for OpenVMS -Reference Manual PAGE 15 table of contents 3.0.8 vmsobj_xabfhc object . . . . . . . . . . . . . 3-25 3.0.9 vmsobj_xabitm object . . . . . . . . . . . . . 3-27 3.0.10 vmsobj_xabkey object . . . . . . . . . . . . . 3-32 3.0.11 vmsobj_xabpro object . . . . . . . . . . . . . 3-35 3.0.12 vmsobj_xabrdt object . . . . . . . . . . . . . 3-38 3.0.13 vmsobj_xabsum object . . . . . . . . . . . . . 3-40 3.0.14 vmsobj__access_names object . . . . . . . . . 3-42 3.0.15 vmsobj__floating_f object . . . . . . . . . . 3-44 3.0.16 vmsobj__membuf object . . . . . . . . . . . . 3-45 3.0.17 vmsobj__ownership_names object . . . . . . . . 3-47 INDEX INDEX-1 CHAPTER 1 Introduction __ | \ | | _ |__/ | | - / \ -O- | \ / \_/ \_/ | | _ | | /\/\ / \ | | / || \ \_ \ / | | \ \/ | | \_/ 1.1 Welcome Welcome to the Python programming language running on the OpenVMS operating system. This is the 'Reference Manual'. It describes modules with their interface routines, defined symbols and VMS objects. Other documentation is in the 'Installation Manual' and the 'General Manual'. More examples are in the 'Demoes Manual'. ------------------------------------------------------------------------ 12-JUN-2000 ZE. CHAPTER 2 Modules 2.1 pyvms module The 'pyvms' module provides access to OpenVMS-related components: C-RTL functions, command history, item codes (fac$_name), bitmasks (fac$M_name), constants (fac$C_name or fac$K_name) and other information. IMPLEMENTATION IS NOT COMPLETE. Items: float Floating point format specifier. "D" and "G" (VAX) or "T" (IEEE). 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 SYS$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'). Python for OpenVMS -Reference Manual PAGE 2-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 - access to the user authorisation file (UAF) uaf_get_usernames return a list of all usernames from SYSUAF.DAT - RMS file I/O crtl_from_vms call the C RTL decc$from_vms() function to translate a file specification from OpenVMS format into Unix style. crtl_open call the C RTL open() function with the possibility to specify additional keywords for RMS. crtl_to_vms call the C RTL decc$to_vms() function to translate a file specification from Unix style into OpenVMS format. file_open call the C RTL fopen() function with the possibility to specify additional keywords for RMS. It returns a Python file object like the 'open()' builtin. - Python library support pylib_getpass get password with no-echo from terminal ------------------------------------------------------------------------ Examples: >>> import pyvms >>> dir (pyvms) ['__doc__', '__name__', 'crtl_from_vms', 'crtl_open', 'crtl_to_vms', 'definitions', 'error', 'file_open', 'float', 'history_delete', 'history_get', 'history_show', 'history_size', 'item_get', 'item_list', 'test__o2pyl', 'test__pyl2o', 'test__pyl2q', 'test__q2pyl', 'test__uq2pyl', 'uaf_get_usernames', 'vms_version_number', 'vmsobj__membuf', 'vmsobj__ownership_names', 'vmsobj_fab', 'vmsobj_iosb', 'vmsobj_lksb', 'vmsobj_nam', 'vmsobj_rab', 'vmsobj_xaball', 'vmsobj_xabdat', 'vmsobj_xabfhc', 'vmsobj_xabitm', 'vmsobj_xabkey', 'vmsobj_xabpro', 'vmsobj_xabrdt', Python for OpenVMS -Reference Manual PAGE 2-3 pyvms module 'vmsobj_xabsum', 'vmsobj_xabtrm'] >>> >>> type (pyvms.definitions) >>> print pyvms.definitions ['$BRKDEF', '$CIADEF', '$DCDEF', '$DMTDEF', '$DVIDEF', '$DVSDEF', '$FABDEF', '$FSCNDEF', '$IMPDEF', '$INITDEF', '$JPIDEF', '$KGBDEF', '$LBRDEF', '$LCKDEF', '$LIBDTDEF', '$LNMDEF', '$MAILDEF', '$MNTDEF', '$NAMDEF', '$OSSDEF', '$PQLDEF', '$PRCDEF', '$PRVDEF', '$PSCANDEF', '$QUIDEF', '$RABDEF', '$RSDMDEF', '$SJCDEF', '$STATEDEF', '$SYIDEF', '$TRMDEF', '$UAIDEF', '$XABALLDEF', '$XABFHCDEF', '$XABITMDEF', '$XABKEYDEF', '$XABPRODEF'] >>> >>> type (pyvms.vms_version_number) >>> 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] $CIADEF >>> print len(pyvms.definitions) 35 >>> 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', [...] '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 Python for OpenVMS -Reference Manual PAGE 2-4 pyvms module >>> 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 >>> >>> 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 Python for OpenVMS -Reference Manual PAGE 2-5 pyvms module {'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() 1 pyvms.history_show() >>> ------------------------------------------------------------------------ Alphabetical list of Python library support routines: - PYLIB_GETPASS - Get password from terminal ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-6 pyvms.pylib_getpass() routine 2.1.1 PYLIB_GETPASS - get password from terminal This is a helper routine for [.LIB]GETPASS.PY. Format: password = pyvms.pylib_getpass (fileno, prompt) Returns: password The password that was entered - it is not echoed. Arguments: fileno 'file number' from the C RTL. Internally this is translated into an OpenVMS file specification and an I/O channel is SYS$ASSIGNed to it. If the I/O channel is not assigned to a terminal device an exception is raised - see the examples section. password The password string that is entered. Examples: >>> import pyvms >>> import sys >>> l_fileno = sys.stdin.fileno() >>> print l_fileno 0 >>> t_password = pyvms.pylib_getpass (l_fileno, 'PwDStr:') PwDStr: <-- cursor is directly after ':' >>> print repr (t_password) 'InPUt' >>> >>> # try a file >>> filobj = open ('python_vms:setup.com', 'r') >>> l_fileno = filobj.fileno() >>> print l_fileno 3 >>> t_password = pyvms.pylib_getpass (l_fileno, 'PwDStr:') Traceback (innermost last): File "", line 1, in ? pyvms.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name') >>> filobj.close() # cleanup >>> Note: SS$_IVDEVNAM has been deliberately choosen. Python for OpenVMS -Reference Manual PAGE 2-7 pyvms.pylib_getpass() routine >>> l_fileno = 9 >>> t_password = pyvms.pylib_getpass (l_fileno, 'PwDStr:') Traceback (innermost last): File "", line 1, in ? pyvms.error: (9, 'bad file number') >>> >>> # test with [.LIB]GETPASS.PY >>> >>> import getpass >>> t_password = getpass.getpass ('PRoMpT:') PRoMpT: >>> print repr(t_password) 'DAtA' >>> 22-JAN-2000 ZE. ------------------------------------------------------------------------ Alphabetical list of RMS file I/O-related routines: - CRTL_FROM_VMS - call decc$from_vms() routine - CRTL_OPEN - call C RTL open() routine - CRTL_TO_VMS - call decc$to_vms() routine - FILE_OPEN - call C RTL fopen() routine returning a Python file object ------------------------------------------------------------------------ 2.1.2 CRTL_FROM_VMS - call decc$from_vms() routine Calls the C RTL decc$from_vms() function to translate a file specification from OpenVMS format into Unix style. Format: file_list = pyvms.crtl_from_vms (vms_filespec, action_routine, \ wild_flag) Returns: file_list List of files translated to Unix style. If this is a non-wildcard operation, then the list contains only one filename. Arguments: vms_filespec File specification in OpenVMS format. action_routine Python for OpenVMS -Reference Manual PAGE 2-8 pyvms.crtl_from_vms() routine A Python function that is called for each file processed. See the examples section below. Return 1 to indicate continuation of wildcard processing; 0 to abort. If the action routine is omitted, then an internal routine is used that appends the filename that is passed to 'file_list'. wild_flag If 0 (the default), then wildcards found in 'vms_filespec' are not expanded. Examples: >>> import pyvms >>> file_list = pyvms.crtl_from_vms ('SYS$SYSTEM:DIRECTORY.EXE') >>> file_list ['/SYS$SYSTEM/DIRECTORY.EXE'] >>> >>> # wild_flag is 0 by default >>> file_list = pyvms.crtl_from_vms ('SYS$SYSTEM:NET*.DAT') >>> file_list [] >>> >>> # the internal action_routine is used >>> file_list = pyvms.crtl_from_vms ('SYS$SYSTEM:NET*.DAT', None, 1) >>> for filespec in file_list: ... print filespec ... /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1 /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1 /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1 /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1 /SYS$SYSROOT/SYSEXE/NETNODE_LOCAL.DAT.1 /SYS$SYSROOT/SYSEXE/NETNODE_REMOTE.DAT.1 /SYS$SYSROOT/SYSEXE/NETOBJECT.DAT.1 >>> >>> def action_routine (unix_filespec): ... print unix_filespec ... r = unix_filespec+'***' ... return (1, r) ... >>> # Note: the output is from the action_routine >>> file_list = pyvms.crtl_from_vms \ ... ('SYS$SYSTEM:NET*.DAT', action_routine, 1) /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1 /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1 /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1 /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1 /SYS$SYSROOT/SYSEXE/NETNODE_LOCAL.DAT.1 /SYS$SYSROOT/SYSEXE/NETNODE_REMOTE.DAT.1 /SYS$SYSROOT/SYSEXE/NETOBJECT.DAT.1 Python for OpenVMS -Reference Manual PAGE 2-9 pyvms.crtl_from_vms() routine >>> >>> # show contents of 'file_list' >>> for filespec in file_list: ... print filespec ... /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1*** /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1*** /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1*** /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1*** /SYS$SYSROOT/SYSEXE/NETNODE_LOCAL.DAT.1*** /SYS$SYSROOT/SYSEXE/NETNODE_REMOTE.DAT.1*** /SYS$SYSROOT/SYSEXE/NETOBJECT.DAT.1*** >>> >>> def action_routine (unix_filespec): ... import string ... print unix_filespec ... r = unix_filespec+'***' ... try: ... pos = string.index (unix_filespec, 'LOCAL') ... return_value = 0 # end loop ... except ValueError: ... return_value = 1 # continue ... return (return_value, r) ... >>> file_list = pyvms.crtl_from_vms \ ... ('SYS$SYSTEM:NET*.DAT', action_routine, 1) /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1 /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1 /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1 /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1 /SYS$SYSROOT/SYSEXE/NETNODE_LOCAL.DAT.1 >>> for filespec in file_list: ... print filespec ... /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1*** /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1*** /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1*** /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1*** /SYS$SYSROOT/SYSEXE/NETNODE_LOCAL.DAT.1*** >>> >>> def action_routine (unix_filespec): ... import string ... print unix_filespec ... r = unix_filespec+'***' ... try: ... pos = string.index (unix_filespec, 'LOCAL') ... r = None ... return_value = 0 # end loop ... except ValueError: ... return_value = 1 # continue Python for OpenVMS -Reference Manual PAGE 2-10 pyvms.crtl_from_vms() routine ... return (return_value, r) ... >>> file_list = pyvms.crtl_from_vms \ ... ('SYS$SYSTEM:NET*.DAT', action_routine, 1) /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1 /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1 /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1 /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1 /SYS$SYSROOT/SYSEXE/NETNODE_LOCAL.DAT.1 >>> for filespec in file_list: ... print filespec ... /SYS$SYSROOT/SYSEXE/NETCIRC.DAT.1*** /SYS$SYSROOT/SYSEXE/NETCONF.DAT.1*** /SYS$SYSROOT/SYSEXE/NETLINE.DAT.1*** /SYS$SYSROOT/SYSEXE/NETLOGING.DAT.1*** None <-- the last item is always returned ! >>> 14-MAR-1999 ZE. ------------------------------------------------------------------------ 2.1.3 CRTL_OPEN - call C RTL open() routine Calls the C RTL open() routine. This is similar to the os.open() (or posix.open() ) routine, but it allows to specify a fourth argument. Note: the creat() and open() routine in the C RTL accept an optional argument list. The Python interface requires that you specify all the arguments as a single tuple that is passed as argument 4 - see the examples section below. Format: fd = pyvms.crtl_open (filename, flag [,mode] [,RMS-arguments]) Returns: fd file descriptor number Use the routines in the 'os', 'posix' module to work with it. Arguments: filename name of the file to open flag flags like O_CREAT or O_WRONLY. These constants can be retrieved from the 'os' module. mode file-protection mode. Use None or 0777 (that's octal!) to use the default mechanism of OpenVMS. Python for OpenVMS -Reference Manual PAGE 2-11 pyvms.crtl_open() routine RMS-arguments This is a tuple of strings to control the file attributes. See the examples section below. Do not use the "acc" or "err" keywords! The interface does neither support these callback routines nor prevent use of them! Examples: >>> import os, pyvms >>> # O_TRUNC requests a NEW version of the file to be created ! >>> flags = os.O_CREAT + os.O_TRUNC + os.O_WRONLY >>> fd = pyvms.crtl_open \ ... ('CRTL_OPEN.TMP' # filename ... ,flags # flags ... ,None # mode ... ,("alq=200","rat=ftn","rfm=stm") # RMS-arguments ... ) >>> >>> os.write (fd, ' Hello!') 7 # number of bytes written >>> os.close (fd) >>> $ directory/full CRTL_OPEN.TMP Directory DKA100:[PYTHON.PYTHON-1_5_1.VMS] CRTL_OPEN.TMP;1 File ID: (12140,33,0) Size: 1/200 Owner: [G1,SYSTEM] Created: 31-DEC-1998 18:30:45.28 Revised: 31-DEC-1998 18:31:30.14 (1) Expires: Backup: Effective: Recording: File organization: Sequential Shelved state: Online File attributes: Allocation: 200, Extend: 0, Global buffer count: 0 No version limit Record format: Stream, maximum 8 bytes Record attributes: Fortran carriage control RMS attributes: None Journaling enabled: None File protection: System:RWED, Owner:RWED, Group:RE, World: Access Cntrl List: None Total of 1 file, 1/200 blocks. $ Python for OpenVMS -Reference Manual PAGE 2-12 pyvms.crtl_open() routine ---------- >>> flags = 0 >>> fd = pyvms.crtl_open \ ... ('%CRTL_OPEN.TMP' # *BAD* filename ... ,flags # flags ... ,None # mode ... ,("alq=200","rat=ftn","rfm=stm") # RMS-arguments ... ) Traceback (innermost last): File "", line 1, in ? pyvms.error: (100164, '%RMS-F-WLD, invalid wildcard operation') >>> ---------- $!+ $! Create a simple test queue to demonstrate spool-on-close. $! Need to point SYS$PRINT to this queue. $!- $ initialize /queue /device /noSTART PY_SPL_TEST $ define SYS$PRINT PY_SPL_TEST $ python [...] >>> import os, pyvms >>> # O_TRUNC requests a NEW version of the file to be created ! >>> flags = os.O_CREAT + os.O_TRUNC + os.O_WRONLY >>> fd = pyvms.crtl_open \ ... ('SPOOL.TMP' # filename ... ,flags # flags ... ,None # mode ... ,("fop=spl",) # RMS-arguments ... ) # ^- need a tuple, here ! >>> >>> os.write (fd, ' Hello!') 7 # number of bytes written >>> os.close (fd) >>> $ show queue /full /all PY_SPL_TEST Printer queue PY_SPL_TEST, stopped, mounted form DEFAULT /BASE_PRIORITY=4 /DEFAULT=(FEED,FORM=DEFAULT) /OWNER=[G1,SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:S) Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 23 SPOOL ZESSIN 1 Pending (queue stopped) Submitted 12-MAR-1999 14:09 /FORM=DEFAULT /PRIORITY=100 File: _$99$DKA100:[PYTHON.PYTHON-1_5_1.VMS]SPOOL.TMP;1 $ $! -- cleanup Python for OpenVMS -Reference Manual PAGE 2-13 pyvms.crtl_open() routine $ deassign SYS$PRINT $ delete /queue PY_SPL_TEST $ delete SPOOL.TMP;1 $ 08-OCT-2000 ZE. ------------------------------------------------------------------------ 2.1.4 CRTL_TO_VMS - call decc$to_vms() routine Calls the C RTL decc$to_vms() function to translate a file specification from Unix style into OpenVMS format. Format: file_list = pyvms.crtl_to_vms (unix_filespec, action_routine, \ allow_wild, no_directory) Returns: file_list List of files translated to OpenVMS format. If this is a non-wildcard operation, then the list contains only one filename. Arguments: unix_filespec File specification in Unix style. action_routine A Python function that is called for each file processed. See the examples section below. Return 1 to indicate continuation of wildcard processing; 0 to abort. If the action routine is omitted, then an internal routine is used that appends the filename that is passed to 'file_list'. allow_wild If 0 (the default), then wildcards found in 'vms_filespec' are not expanded. no_directory valid values: 0 directory is not allowed 1 prevent expansion of string as directory name 2 forced to be directory name Examples: $ copy _nla0: SYS$SPECIFIC:[000000]pydemo.tmp >>> import pyvms Python for OpenVMS -Reference Manual PAGE 2-14 pyvms.crtl_to_vms() routine >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/', None, 0, 0) >>> file_list [('SYS$SYSTEM:', 1)] >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/', None, 0, 1) >>> file_list [('SYS$SYSTEM:', 1)] >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/', None, 0, 2) >>> file_list [('SYS$SYSTEM:', 1)] >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/DIRECTORY.ERR') >>> file_list [('SYS$SYSTEM:DIRECTORY.ERR', 1)] >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/DIRECTORY.EXE') >>> file_list [('SYS$SYSTEM:DIRECTORY.EXE', 1)] >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/NET*.DAT') >>> file_list [] >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/NET*.DAT', None, 1, 0) >>> for filespec in file_list: ... print filespec ... ('SYS$SYSROOT:[SYSEXE]NETCIRC.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETCONF.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETLINE.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETLOGING.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETNODE_LOCAL.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETNODE_REMOTE.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETOBJECT.DAT.1', 1) >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/NET*.DAT', None, 1, 1) >>> for filespec in file_list: ... print filespec ... ('SYS$SYSROOT:[SYSEXE]NETCIRC.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETCONF.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETLINE.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETLOGING.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETNODE_LOCAL.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETNODE_REMOTE.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETOBJECT.DAT.1', 1) >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SYSTEM/NET*.DAT', None, 1, 2) >>> for filespec in file_list: ... print filespec ... ('SYS$SYSROOT:[SYSEXE]NETCIRC.DAT.1', 1) Python for OpenVMS -Reference Manual PAGE 2-15 pyvms.crtl_to_vms() routine ('SYS$SYSROOT:[SYSEXE]NETCONF.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETLINE.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETLOGING.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETNODE_LOCAL.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETNODE_REMOTE.DAT.1', 1) ('SYS$SYSROOT:[SYSEXE]NETOBJECT.DAT.1', 1) >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SPECIFIC/000000/*', None, 1, 0) >>> for filespec in file_list: ... print filespec ... ('SYS$SPECIFIC:[000000]FAL$SERVER.DIR.1', 1) ('SYS$SPECIFIC:[000000.MOM$SYSTEM]', 2) <--- [1] ('SYS$SPECIFIC:[000000]PYDEMO.TMP.1', 1) ('SYS$SPECIFIC:[000000.SYS$I18N]', 2) ('SYS$SPECIFIC:[000000.SYS$LDR]', 2) ('SYS$SPECIFIC:[000000.SYS$STARTUP]', 2) ('SYS$SPECIFIC:[000000.SYSCBI]', 2) ('SYS$SPECIFIC:[000000.SYSCOMMON]', 2) ('SYS$SPECIFIC:[000000.SYSERR]', 2) ('SYS$SPECIFIC:[000000.SYSEXE]', 2) ('SYS$SPECIFIC:[000000.SYSHLP]', 2) ('SYS$SPECIFIC:[000000.SYSLIB]', 2) ('SYS$SPECIFIC:[000000.SYSMAINT]', 2) ('SYS$SPECIFIC:[000000.SYSMGR]', 2) ('SYS$SPECIFIC:[000000.SYSMSG]', 2) ('SYS$SPECIFIC:[000000.SYSTEST]', 2) ('SYS$SPECIFIC:[000000.SYSUPD]', 2) ('SYS$SPECIFIC:[000000.UCX$BIND]', 2) >>> [1] this is wrong. It has been (unofficially) reported to Compaq. >>> file_list = pyvms.crtl_to_vms ('/SYS$SPECIFIC/000000/*', None, 1, 0) >>> for filespec in file_list: ... print filespec ... ('SYS$SPECIFIC:[000000.FAL$SERVER]', 2) ('SYS$SPECIFIC:[000000.MOM$SYSTEM]', 2) ('SYS$SPECIFIC:[000000]PYDEMO.TMP.1', 1) ('SYS$SPECIFIC:[000000.SYS$I18N]', 2) ('SYS$SPECIFIC:[000000.SYS$LDR]', 2) ('SYS$SPECIFIC:[000000.SYS$STARTUP]', 2) ('SYS$SPECIFIC:[000000.SYSCBI]', 2) ('SYS$SPECIFIC:[000000.SYSCOMMON]', 2) ('SYS$SPECIFIC:[000000.SYSERR]', 2) ('SYS$SPECIFIC:[000000.SYSEXE]', 2) ('SYS$SPECIFIC:[000000.SYSHLP]', 2) ('SYS$SPECIFIC:[000000.SYSLIB]', 2) ('SYS$SPECIFIC:[000000.SYSMAINT]', 2) ('SYS$SPECIFIC:[000000.SYSMGR]', 2) ('SYS$SPECIFIC:[000000.SYSMSG]', 2) ('SYS$SPECIFIC:[000000.SYSTEST]', 2) ('SYS$SPECIFIC:[000000.SYSUPD]', 2) Python for OpenVMS -Reference Manual PAGE 2-16 pyvms.crtl_to_vms() routine ('SYS$SPECIFIC:[000000.UCX$BIND]', 2) >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SPECIFIC/000000/*', None, 1, 1) >>> for filespec in file_list: ... print filespec ... ('SYS$SPECIFIC:[000000]FAL$SERVER.DIR.1', 1) ('SYS$SPECIFIC:[000000.MOM$SYSTEM]', 2) ('SYS$SPECIFIC:[000000]PYDEMO.TMP.1', 1) ('SYS$SPECIFIC:[000000.SYS$I18N]', 2) ('SYS$SPECIFIC:[000000.SYS$LDR]', 2) ('SYS$SPECIFIC:[000000.SYS$STARTUP]', 2) ('SYS$SPECIFIC:[000000.SYSCBI]', 2) ('SYS$SPECIFIC:[000000.SYSCOMMON]', 2) ('SYS$SPECIFIC:[000000.SYSERR]', 2) ('SYS$SPECIFIC:[000000.SYSEXE]', 2) ('SYS$SPECIFIC:[000000.SYSHLP]', 2) ('SYS$SPECIFIC:[000000.SYSLIB]', 2) ('SYS$SPECIFIC:[000000.SYSMAINT]', 2) ('SYS$SPECIFIC:[000000.SYSMGR]', 2) ('SYS$SPECIFIC:[000000.SYSMSG]', 2) ('SYS$SPECIFIC:[000000.SYSTEST]', 2) ('SYS$SPECIFIC:[000000.SYSUPD]', 2) ('SYS$SPECIFIC:[000000.UCX$BIND]', 2) >>> >>> file_list = pyvms.crtl_to_vms ('/SYS$SPECIFIC/000000/*', None, 1, 2) >>> for filespec in file_list: ... print filespec ... ('SYS$SPECIFIC:[000000]FAL$SERVER.DIR.1', 1) ('SYS$SPECIFIC:[000000.MOM$SYSTEM]', 2) ('SYS$SPECIFIC:[000000]PYDEMO.TMP.1', 1) ('SYS$SPECIFIC:[000000.SYS$I18N]', 2) ('SYS$SPECIFIC:[000000.SYS$LDR]', 2) ('SYS$SPECIFIC:[000000.SYS$STARTUP]', 2) ('SYS$SPECIFIC:[000000.SYSCBI]', 2) ('SYS$SPECIFIC:[000000.SYSCOMMON]', 2) ('SYS$SPECIFIC:[000000.SYSERR]', 2) ('SYS$SPECIFIC:[000000.SYSEXE]', 2) ('SYS$SPECIFIC:[000000.SYSHLP]', 2) ('SYS$SPECIFIC:[000000.SYSLIB]', 2) ('SYS$SPECIFIC:[000000.SYSMAINT]', 2) ('SYS$SPECIFIC:[000000.SYSMGR]', 2) ('SYS$SPECIFIC:[000000.SYSMSG]', 2) ('SYS$SPECIFIC:[000000.SYSTEST]', 2) ('SYS$SPECIFIC:[000000.SYSUPD]', 2) ('SYS$SPECIFIC:[000000.UCX$BIND]', 2) >>> 15-MAR-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-17 pyvms.file_open() routine 2.1.5 FILE_OPEN - call C RTL fopen() routine Calls the C RTL fopen() routine, but returns a Python file object. This is similar to the 'open()' builtin, but it allows to specify a fourth argument. Note: the creat() and open() routine in the C RTL accept an optional argument list. The Python interface requires that you specify all the arguments as a single tuple that is passed as argument 4 - see the examples section below. Format: fo = pyvms.file_open (filename, [,mode] [,buffer] [,RMS-arguments]) Returns: fo Python file object Arguments: filename name of the file to open mode 'r', 'w', 'a' - see the online documentation for details: print pyvms.file_open.__doc__ buffering 0 = unbuffered, 1 = line-buffered, others = actual buffer size RMS-arguments This is a tuple of strings to control the file attributes. See the examples section below. Do not use the "acc" or "err" keywords! The interface does neither support these callback routines nor prevent use of them! Examples: >>> import pyvms >>> fo = pyvms.file_open \ ... ('FILE_OPEN.TMP' # filename ... ,'w' # mode ... ,-1 # buffering ... ,("alq=200","rat=ftn","rfm=var") # RMS-arguments ... ) >>> print type(fo) >>> fo.write (' Hello!\n') >>> fo.close () >>> Python for OpenVMS -Reference Manual PAGE 2-18 pyvms.file_open() routine $ directory/full FILE_OPEN.TMP Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] FILE_OPEN.TMP;1 File ID: (8949,43,0) Size: 1/200 Owner: [G1,SYSTEM] Created: 26-DEC-1999 17:55:09.20 Revised: 26-DEC-1999 17:55:15.38 (1) Expires: Backup: Effective: Recording: File organization: Sequential Shelved state: Online File attributes: Allocation: 200, Extend: 0, Global buffer count: 0 No version limit Record format: Variable length, maximum 2 bytes Record attributes: Fortran carriage control RMS attributes: None Journaling enabled: None File protection: System:RWED, Owner:RWED, Group:RE, World: Access Cntrl List: None Total of 1 file, 1/200 blocks. $ ---------- >>> fo = pyvms.file_open \ ... ('%FILE_OPEN.TMP' # filename ... ,'w' # mode ... ,-1 # buffering ... ,("alq=200","rat=ftn","rfm=var") # RMS-arguments ... ) Traceback (innermost last): File "", line 5, in ? IOError: [Errno 65535] invalid wildcard operation: '%FILE_OPEN.TMP' >>> @@ output from pyvms.crtl_open() is: @@Traceback (innermost last): @@ File "", line 1, in ? @@pyvms.error: (100164, '%RMS-F-WLD, invalid wildcard operation') ---------- $!+ $! Create a simple test queue to demonstrate spool-on-close. $! Need to point SYS$PRINT to this queue. $!- $ initialize /queue /device /noSTART PY_SPL_TEST $ define SYS$PRINT PY_SPL_TEST $ python Python for OpenVMS -Reference Manual PAGE 2-19 pyvms.file_open() routine [...] >>> import pyvms >>> fo = pyvms.file_open \ ... ('SPOOL.TMP' # filename ... ,'w' # mode ... ,-1 # buffering ... ,("fop=spl",) # RMS-arguments ... ) # ^- need a tuple, here ! >>> fo.write (' Hello!') >>> fo.close () >>> $ show queue /full /all PY_SPL_TEST Printer queue PY_SPL_TEST, stopped, mounted form DEFAULT /BASE_PRIORITY=4 /DEFAULT=(FEED,FORM=DEFAULT) /OWNER=[G1,SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:S) Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 30 SPOOL ZESSIN 1 Pending (queue stopped) Submitted 26-DEC-1999 17:59 /FORM=DEFAULT /PRIORITY=100 File: _$99$DKA100:[PYTHON.PYTHON-1_5_2.VMS]SPOOL.TMP;1 $ $! -- cleanup $ deassign SYS$PRINT $ delete /queue PY_SPL_TEST $ delete SPOOL.TMP;1 $ 26-DEC-1999 ZE. ------------------------------------------------------------------------ Alphabetical list of UAF-related routines: - UAF_GET_USERNAMES - Get list of usernames from authorization file ------------------------------------------------------------------------ 2.1.6 UAF_GET_USERNAMES - Get list of usernames from authorization file Returns a list of all usernames that exist in SYSUAF.DAT pyvms.uaf_get_usernames() does _not_ raise an exception when one of the system services (SYS$OPEN, SYS$CONNECT, SYS$GET, SYS$CLOSE) returns an error. The routine stores two additional keys in the dictionary that is returned to the user. Warning! This routine requires file access to SYSUAF.DAT. The Python executable should NOT be installed with privileges to provide this access. The interpreter and its VMS extensions have NO safeguards Python for OpenVMS -Reference Manual PAGE 2-20 pyvms.uaf_get_usernames() routine build in to limit privilege usage to this routine! Note: the interface routines vms_sys.getuai() and vms_sys.setuai() provide a 'context' argument, but it can only be used for repeated access to the SAME username. Format: dict = pyvms.uaf_get_usernames () Returns: dict A dictionary that has the following keys: 'sts' The condition value returned in FAB$L_STS or RAB$L_STS. 'stv' the condition value returned in FAB$L_STS or RAB$L_STS. 'usernames' A list of all usernames that are stored in SYSUAF.DAT. If no access to the file can be established, then this key is missing. Arguments: None Examples: >>> import pyvms >>> dict = pyvms.uaf_get_usernames () >>> type (dict) >>> dict {'sts': 98938, 'stv': 0, 'usernames': ['DECNET', 'DEFAULT', 'FAL$SERVER', 'FIELD', 'GETUAI_TST', 'HTTP_SERVER', 'MAIL$SERVER', 'MIRRO$SERVER', 'NML$SERVER', 'NOPRIV', 'PHONE$SERVER', 'RAYTRACE', 'SETUAI_TST', 'SYSTEM', 'SYSTEST', 'SYSTEST_CLIG', 'SYS_ARCHIVE', 'SYS_BACKUP', 'SYS_CRON', 'SYS_MONITOR', 'UCX$BIND', 'UCX$FTP', 'UCX$PORTM', 'UUCP_DAEMON', 'UUCP_LOGIN', 'UUCP_TEST', 'VPM$SERVER', 'ZESSIN']} >>> sts = dict.get ('sts') >>> import vms_sys >>> print vms_sys.getmsg (sts) [0] %RMS-E-EOF, end of file detected >>> Python for OpenVMS -Reference Manual PAGE 2-21 pyvms.uaf_get_usernames() routine >>> # loop over list and show each username with owner information >>> usernames = dict.get ('usernames') >>> for username in usernames: ... dict = vms_sys.getuai (None,None,username, \ ... ('UAI$_OWNER', 'UAI$_EXPIRATION')) ... owner = dict.get ('UAI$_OWNER') ... print "%12s, %s" % (username, owner) ... DECNET, DECNET DEFAULT DEFAULT, DEFAULT FAL$SERVER, FAL$SERVER DEFAULT FIELD, FIELD SERVICE HTTP_SERVER, WWW-Server MAIL$SERVER, MAIL$SERVER DEFAULT MIRRO$SERVER, MIRRO$SERVER DEFAULT NML$SERVER, NML$SERVER DEFAULT NOPRIV, Zessin,Uwe PHONE$SERVER, PHONE$SERVER DEFAULT RAYTRACE, Zessin,Uwe SYSTEM, SYSTEM MANAGER SYSTEST, SYSTEST-UETP SYSTEST_CLIG, SYSTEST-UETP SYS_ARCHIVE, SYSTEM ARCHIVE SYS_BACKUP, SYSTEM BACKUP SYS_CRON, CRON scheduler SYS_MONITOR, SYSTEM MONITOR UCX$BIND, UCX$BIND UCX$FTP, UCX$FTP UCX$PORTM, UCX$PORTM UUCP_DAEMON, UUCP daemon account UUCP_LOGIN, Template UUCP Account UUCP_TEST, UUCP Test Account VPM$SERVER, VPM$SERVER DEFAULT ZESSIN, Zessin,Uwe >>> ------------------------------ >>> dict = pyvms.uaf_get_usernames ('BAD-ARG') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> >>> # no privilege to access SYSUAF.DAT >>> dict = pyvms.uaf_get_usernames () >>> dict {'sts': 98970, 'stv': 36} >>> sts = dict.get ('sts') >>> print vms_sys.getmsg (sts) [0] %RMS-E-PRV, insufficient privilege or file protection violation >>> stv = dict.get ('stv') Python for OpenVMS -Reference Manual PAGE 2-22 pyvms.uaf_get_usernames() routine >>> print vms_sys.getmsg (stv) [0] %SYSTEM-F-NOPRIV, insufficient privilege or object protection\ violation >>> $! point to non-existent file via logical name $ define SYSUAF XX >>> import vms_sys >>> dict = pyvms.uaf_get_usernames () >>> print dict {'sts': 98962, 'stv': 2320} >>> sts = dict.get ('sts') >>> print vms_sys.getmsg (sts) [0] %RMS-E-FNF, file not found >>> stv = dict.get ('stv') >>> print vms_sys.getmsg (stv) [0] %SYSTEM-W-NOSUCHFILE, no such file >>> $! point to non-existent file (including bad device) $! via logical name $ define sysuaf no_disk:[000000]SYSUAF.DAT >>> dict = pyvms.uaf_get_usernames () >>> print dict {'sts': 99524, 'stv': 324} >>> sts = dict.get('sts') >>> print vms_sys.getmsg (sts) [0] %RMS-F-DEV, error in device name or inappropriate device type\ for operation >>> stv = dict.get('stv') >>> print vms_sys.getmsg (stv) [0] %SYSTEM-F-IVDEVNAM, invalid device name >>> 10-NOV-1999 ZE. ------------------------------------------------------------------------ 01-JUL-2001 ZE. 2.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. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-23 vms_lbr module Alphabetical list of routines: - OUTPUT_HELP - Output Help Messages ------------------------------------------------------------------------ ------------------------------------------------------------------------ 2.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. 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 omit this argument, then the RTL routine LIB$GET_INPUT will be used internally. Examples: >>> import vms_lbr Python for OpenVMS -Reference Manual PAGE 2-24 vms_lbr module >>> # 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 ... 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? Python for OpenVMS -Reference Manual PAGE 2-25 vms_lbr module 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. 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() Python for OpenVMS -Reference Manual PAGE 2-26 vms_lbr module >>> >>> # specify a different verb in 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 >>> # @@ a future version should have a condition handler to >>> # suppress this traceback >>> status = 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 >>> >>> print status 276172954 >>> import vms_sys >>> vms_sys.getmsg (status)[0] '%HELP-E-OPENIN, error opening !AS as input' >>> >>> # 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() >>> Python for OpenVMS -Reference Manual PAGE 2-27 vms_lbr module @@ old output, not updated after (minmal code changes) on 28-OCT-1998 >>> # 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 ... ------------------------------------------------------------------------ 28-OCT-1998 ZE. Python for OpenVMS -Reference Manual PAGE 2-28 vms_lib module 2.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 - CONVERT_DATE_STRING - Convert Date String to Quadword - CREATE_DIR - Create a Directory - CURRENCY - Get System Currency Symbol - CVTF_FROM_INTERNAL_TIME - Convert Internal Time to External Time (F-Floating-Point Value) - CVTF_TO_INTERNAL_TIME - Convert External Time to Internal Time (F-Floating-Point Value) - CVT_FROM_INTERNAL_TIME - Convert Internal Time to External Time - CVT_TO_INTERNAL_TIME - Convert External Time to Internal Time - 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_FILE - Delete One or More Files - 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_FILE - Find File - FIND_FILE_END - End of Find File - FIND_IMAGE_SYMBOL - Find Universal Symbol in Shareable Image File - FORMAT_DATE_TIME - Format Date and/or Time - FORMAT_SOGW_PROT - Translate a protection mask into a formatted string. - FREE_DATE_TIME_CONTEXT - Free the Context Area Used When Formatting Dates and Times for Input or Output - FREE_EF - Free Event Flag - GETDVI - Get Device/Volume Information - GETJPI - Get Job/Process Information - GETQUI - Get Queue Information - GETSYI - Get Systemwide Information - GET_ACCNAM - Get Access Name Table for Protected Object Class (by Name) Python for OpenVMS -Reference Manual PAGE 2-29 vms_lib module - GET_ACCNAM_BY_CONTEXT - Get Access Name Table for Protected Object Class (by Context) - GET_COMMAND - Get Line from SYS$COMMAND - GET_COMMON - Get String from Common - GET_DATE_FORMAT - Get the User's Date Input Format - GET_EF - Get Event Flag - GET_FOREIGN - Get Foreign Command Line - GET_MAXIMUM_DATE_LENGTH - Retrieve the Maximum Length of a Date/Time String - GET_SYMBOL - Get Value of CLI Symbol - GET_USERS_LANGUAGE - Return the User's Language - INIT_DATE_TIME_CONTEXT - Initialize the Context Area Used in Formatting Dates and Times for Input or Output - LP_LINES - Lines on Each Printer Page - PARSE_ACCESS_CODE - Parse Access Encoded Name String - PARSE_SOGW_PROT - Parse Protection String - PUT_COMMON - Put String to Common - PUT_OUTPUT - Put Line to SYS$OUTPUT - RADIX_POINT - Radix Point Symbol - RENAME_FILE - Rename One or More Files - 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 - TRIM_FILESPEC - Fit Long File Specification into Fixed Field - WAIT - Wait a Specified Period of Time ------------------------------------------------------------------------ 2.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 GENMAN 'Programming', 'special OpenVMS datatypes' for details. Arguments: time1 + time2 64-bit system time - a Python 'long integer'. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Python for OpenVMS -Reference Manual PAGE 2-30 vms_lib.add_times() routine 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' >>> resultant_time = vms_lib.add_times ('X', time2) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: must be long integer >>> resultant_time = vms_lib.add_times (time1, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: must be long integer >>> 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 ? TypeError: argument 2: must be long integer Python for OpenVMS -Reference Manual PAGE 2-31 vms_lib.add_times() routine >>> 12-MAY-1999 ZE. ------------------------------------------------------------------------ 2.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. A 16-bit Python integer. mailbox_channel Channel to mailbox, received from SYS$CREMBX. A 16-bit Python integer. Both I/O channels can be closed by the vms_sys.dassgn() system service. 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 >>> 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 omitted in vms_lib.getdvi()) $ show device/full _MBA233: Device MBA233: is online, record-oriented device, shareable, Python for OpenVMS -Reference Manual PAGE 2-32 vms_lib.asn_wth_mbx() routine 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: ! from a different process 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 $! -----> ** >>> # close these channels >>> import vms_sys >>> vms_sys.dassgn (devchn) >>> vms_sys.dassgn (mbxchn) $ show device/full _MBA241: ! from a different process %SYSTEM-W-NOSUCHDEV, no such device available $ ! -> channel closed, mailbox deleted >>> # 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') >>> 29-NOV-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-33 vms_lib.attach() routine 2.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 >>> Python for OpenVMS -Reference Manual PAGE 2-34 vms_lib.attach() routine 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.4 CONVERT_DATE_STRING - Convert Date String to Quadword Format: status, context, date_time, defaulted_fields = \ vms_lib.convert_date_string (date-string, [user-context], \ [flags], [defaults]) Returns: status condition code from LIB$CONVERT_DATE_STRING context Updated context value from the 'user-context' argument. If omitted this will be 'None'. date_time The converted time - 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. defaulted-fields Indicates which date or time fields have been defaulted. Bits are the same as those of the 'flags' argument. Arguments: date-string The absolute date + time that is to be converted to the internal 64-bit format. user-context Translation context - usually set up by vms_lib.init_date_time_contexte. flags Specifies for which components might be omitted and defaults instead applied. See the 'OpenVMS RTL Library (LIB$) manual' for details. defaults Default values for omitted fields. This is a 7-item tuple of 16-bit values. (year, month, day, hour, minute, second, hundredth) Examples: >>> import vms_lib >>> import vms_sys >>> status, context, date_time, defaulted_fields = \ ... vms_lib.convert_date_string('1-JUN-1999') >>> print (status, context, date_time, defaulted_fields) Python for OpenVMS -Reference Manual PAGE 2-35 vms_lib.convert_date_string() routine (1, None, 44349120000000000L, 120) >>> (the RTL manual explains why 120 is returned for defaulted_fields) >>> print vms_sys.asctim (date_time) 1-JUN-1999 00:00:00.00 >>> >>> print vms_sys.asctim () 4-AUG-1999 20:23:11.62 >>> status, context, date_time, defaulted_fields = \ ... vms_lib.convert_date_string('YESTERDAY') >>> print (status, context, date_time, defaulted_fields) (1, None, 44403552000000000L, 0) >>> print vms_sys.asctim (date_time) 3-AUG-1999 00:00:00.00 >>> >>> # German version >>> context = 0 >>> import vms_libdtdef >>> relative_day_name = "|gestern|heute|morgen|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_RELATIVE_DAY_NAME, relative_day_name) >>> status, context, date_time, defaulted_fields = \ ... vms_lib.convert_date_string ('morgen', context) >>> print (status, context, date_time, defaulted_fields) (1, 2755936, 44405280000000000L, 0) >>> print vms_sys.asctim (date_time) 5-AUG-1999 00:00:00.00 >>> >>> vms_lib.convert_date_string('1-JUN') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410124, '%LIB-F-INCDATTIM, incomplete date-time,\ missing fields with no defaults') >>> >>> status, context, date_time, defaulted_fields = \ ... vms_lib.convert_date_string('1-JUN', None, 0x7f, \ ... (1, 2, 3, 4, 5, 6, 7) ) Traceback (innermost last): File "", line 3, in ? vms_lib.error: (1410012, '%LIB-F-IVTIME, invalid time passed in,\ or computed') >>> >>> status, context, date_time, defaulted_fields = \ ... vms_lib.convert_date_string('1-JUN', None, 0x7f, \ Python for OpenVMS -Reference Manual PAGE 2-36 vms_lib.convert_date_string() routine ... (1997, 2, 3, 4, 5, 6, 7) ) >>> print (status, context, date_time, defaulted_fields) (1, None, 43718547060700000L, 121) >>> >>> print vms_sys.asctim (date_time) 1-JUN-1997 04:05:06.07 >>> 04-AUG-1999 ZE. ------------------------------------------------------------------------ 2.3.5 CREATE_DIR - Create a Directory The Create a Directory routine creates a directory or subdirectory. This interface does NOT raise an exception when an error occurs! Format: status = vms_lib.create_dir (device-directory-spec, \ [,owner-UIC] [,protection-enable] \ [,protection-value] [,maximum-versions] \ [,relative-volume-number] ) Returns: status Condition code that is returned by LIB$CREATE_DIR. SS$_CREATED and SS$_NORMAL are returned for success, so you must check status! Arguments: devdir-spec owner-uic protection-enable protection-value maximum-versions relative-volume-number Examples: >>> import vms_lib @@ examples for CREATE_DIR missing 29-NOV-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-37 vms_lib.currency() routine 2.3.6 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. This interface uses a dynamic string descriptor in the call to LIB$CURRENCY(), so it may raise other exceptions than those which are documented for LIB$CURRENCY(). 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 >>> 30-NOV-1998 ZE. ------------------------------------------------------------------------ 2.3.7 CVTF_FROM_INTERNAL_TIME - Convert Internal Time to External Time (F-Floating-Point Value) Format: resultant_time = vms_lib.cvtf_from_internal_time \ (operation, input_time) Python for OpenVMS -Reference Manual PAGE 2-38 vms_lib.cvtf_from_internal_time() routine Returns: resultant_time F-Floating-Point Value that results from the conversion. Beginning with Python for OpenVMS V2.1-V001 there is (limited) support for different floating point formats available. This routine will now return a vmsobj__floating_f object to be able to retain the exact bit pattern. The examples section shows how to convert to a Python float. Arguments: operation Conversion type to be performed. Codes (LIB$K_DELTA_xxx_F) are in module 'vms_libdtdef'. input_time Delta time to be converted. 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_lib >>> import vms_libdtdef >>> op = vms_libdtdef.LIB_K_DELTA_SECONDS_F >>> import vms_sys >>> q_deltim = vms_sys.bintim ('0 00:00:00.50') >>> q_deltim -5000000L >>> resultant_time = vms_lib.cvtf_from_internal_time (op, q_deltim) >>> resultant_time >>> >>> resultant_time_f = resultant_time.as_python_float() >>> resultant_time_f 0.5 >>> >>> op = vms_libdtdef.LIB_K_DELTA_DAYS_F >>> q_deltim = vms_sys.bintim ('0 18:00:00.00') >>> q_deltim -648000000000L >>> resultant_time = vms_lib.cvtf_from_internal_time (op, q_deltim) >>> resultant_time >>> >>> resultant_time_f = resultant_time.as_python_float() >>> resultant_time_f 0.74999994039535522 <-- OpenVMS VAX V6.1 (D_float) >>> print 18.0/24.0 Python for OpenVMS -Reference Manual PAGE 2-39 vms_lib.cvtf_from_internal_time() routine 0.75 >>> >>> op = vms_libdtdef.LIB_K_DELTA_DAYS_F >>> q_deltim = vms_sys.bintim ('0 06:00:00.00') >>> q_deltim -216000000000L >>> resultant_time = vms_lib.cvtf_from_internal_time (op, q_deltim) >>> resultant_time >>> >>> resultant_time_f = resultant_time.as_python_float() >>> resultant_time_f 0.25 >>> print 6.0/24.0 0.25 >>> >>> vms_lib.cvtf_from_internal_time ('X', q_deltim) Traceback (innermost last): File "", line 1, in ? TypeError: an integer is required >>> >>> # -------------------------------v >>> vms_lib.cvtf_from_internal_time (1, q_deltim) Traceback (innermost last): File "", line 1, in ? vms_lib.error: [Errno 1410060] %LIB-F-INVOPER, invalid operation specified >>> >>> import vms_sys >>> vms_sys.getmsg (1410060) ('%LIB-F-INVOPER, invalid operation specified', (0, 0, 0, 0)) >>> >>> vms_lib.cvtf_from_internal_time (op, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: input-time - must be long integer >>> >>> q_abstim = vms_sys.bintim ('29-FEB-2000 12:34:56.78') >>> q_abstim 44585444967800000L >>> vms_lib.cvtf_from_internal_time (op, q_abstim) Traceback (innermost last): File "", line 1, in ? vms_lib.error: [Errno 1410052] %LIB-F-DELTIMREQ, delta time required,\ absolute time supplied >>> 16-APR-2001 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-40 vms_lib.cvtf_to_internal_time() routine 2.3.8 CVTF_TO_INTERNAL_TIME - Convert External Time to Internal Time (F-Floating-Point Value) Format: resultant_time = vms_lib.cvtf_to_internal_time \ (operation, input_time) Returns: resultant_time OpenVMS internal format delta time that results from the conversion. 64-bit system time - a Python 'long integer'. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Arguments: operation Conversion type to be performed. Codes (LIB$K_DELTA_xxx_F) are in module 'vms_libdtdef'. input_time Delta time to be converted (F-Floating-Point value). Beginning with Python for OpenVMS V2.1-V001 there is (limited) support for different floating point formats available. This routine now accepts a Python float or a vmsobj__floating_f object to be able to retain the exact bit pattern. The examples section shows how to convert to a Python float. Examples: >>> import vms_lib >>> import vms_libdtdef >>> op = vms_libdtdef.LIB_K_DELTA_SECONDS_F >>> import vms_sys >>> resultant_time = vms_lib.cvtf_to_internal_time (op, 0.5) >>> resultant_time -5000000L >>> vms_sys.asctim (resultant_time) ' 0 00:00:00.50' >>> >>> op = vms_libdtdef.LIB_K_DELTA_DAYS_F >>> print 8.0/24.0 0.333333333333 >>> resultant_time = vms_lib.cvtf_to_internal_time (op, 8.0/24.0) -287999971200L >>> vms_sys.asctim (resultant_time) ' 0 07:59:59.99' >>> Python for OpenVMS -Reference Manual PAGE 2-41 vms_lib.cvtf_to_internal_time() routine >>> op = vms_libdtdef.LIB_K_DELTA_DAYS_F >>> print 6.0/24.0 0.25 >>> resultant_time = vms_lib.cvtf_to_internal_time (op, 6.0/24.0) >>> resultant_time -216000000000L >>> vms_sys.asctim (resultant_time) ' 0 06:00:00.00' >>> >>> # a week has 7 days. 0.5 week = 3.5 days = 3 days, 12 hours >>> op = vms_libdtdef.LIB_K_DELTA_WEEKS_F >>> resultant_time = vms_lib.cvtf_to_internal_time (op, 0.5) >>> resultant_time -3024000000000L >>> vms_sys.asctim (resultant_time) ' 3 12:00:00.00' >>> >>> # a week has 7 days. 1.5 week = 10.5 days = 10 days, 12 hours >>> import pyvms >>> f = pyvms.vmsobj__floating_f () >>> f >>> >>> f.from_python_float (1.5) >>> >>> op = vms_libdtdef.LIB_K_DELTA_WEEKS_F >>> resultant_time = vms_lib.cvtf_to_internal_time (op, f) @@@ Traceback (most recent call last): File "", line 1, in ? TypeError: bad argument type for built-in operation >>> resultant_time -3024000000000L >>> vms_sys.asctim (resultant_time) ' 3 12:00:00.00' >>> ---------------------------------------------------------------------------- >>> # a week has 7 days. 1.5 week = 10.5 days = 10 days, 12 hours >>>import pyvms, vms_libdtdef, vms_lib >>>f = pyvms.vmsobj__floating_f() >>>f >>> >>> f.from_python_float(1.5) >>> >>> op = vms_libdtdef.LIB_K_DELTA_WEEKS_F >>> resultant_time = vms_lib.cvtf_to_internal_time (op, f) @@@ Python for OpenVMS -Reference Manual PAGE 2-42 vms_lib.cvtf_to_internal_time() routine Traceback (most recent call last): File "", line 1, in ? TypeError: bad argument type for built-in operation >>> resultant_time -3024000000000L >>> vms_sys.asctim (resultant_time) ' 3 12:00:00.00' ---------------------------------------------------------------------------- >>> vms_lib.cvtf_to_internal_time ('X', 0.5) Traceback (innermost last): File "", line 1, in ? TypeError: an integer is required >>> >>> # -----------------------------v >>> vms_lib.cvtf_to_internal_time (1, 0.5) Traceback (innermost last): File "", line 1, in ? vms_lib.error: [Errno 1410060] %LIB-F-INVOPER, invalid operation specified >>> >>> import vms_sys >>> print vms_sys.getmsg (1410060) ('%LIB-F-INVOPER, invalid operation specified', (0, 0, 0, 0)) >>> >>> vms_lib.cvtf_to_internal_time (op, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: bad argument type for built-in operation >>> 24-OCT-1998 ZE. ------------------------------------------------------------------------ 2.3.9 CVT_FROM_INTERNAL_TIME - Convert Internal Time to External Time Format: resultant_time = vms_lib.cvt_from_internal_time \ (operation [,input_time]) Returns: resultant_time integer value Arguments: operation Conversion type to be performed. Codes (LIB_K_DELTA_xxx) are currently (25-OCT-1998) not available. Python for OpenVMS -Reference Manual PAGE 2-43 vms_lib.cvt_from_internal_time() routine input_time Delta time to be converted. 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_lib >>> # set up some constants >>> LIB_K_MONTH_OF_YEAR = 1 >>> LIB_K_DAY_OF_YEAR = 2 >>> LIB_K_HOUR_OF_YEAR = 3 >>> LIB_K_MINUTE_OF_YEAR = 4 >>> LIB_K_SECOND_OF_YEAR = 5 >>> LIB_K_DAY_OF_MONTH = 6 >>> LIB_K_HOUR_OF_MONTH = 7 >>> LIB_K_MINUTE_OF_MONTH = 8 >>> LIB_K_SECOND_OF_MONTH = 9 >>> LIB_K_DAY_OF_WEEK = 10 >>> LIB_K_HOUR_OF_WEEK = 11 >>> LIB_K_MINUTE_OF_WEEK = 12 >>> LIB_K_SECOND_OF_WEEK = 13 >>> LIB_K_HOUR_OF_DAY = 14 >>> LIB_K_MINUTE_OF_DAY = 15 >>> LIB_K_SECOND_OF_DAY = 16 >>> LIB_K_MINUTE_OF_HOUR = 17 >>> LIB_K_SECOND_OF_HOUR = 18 >>> LIB_K_SECOND_OF_MINUTE = 19 >>> LIB_K_JULIAN_DATE = 20 >>> LIB_K_DELTA_WEEKS = 21 >>> LIB_K_DELTA_DAYS = 22 >>> LIB_K_DELTA_HOURS = 23 >>> LIB_K_DELTA_MINUTES = 24 >>> LIB_K_DELTA_SECONDS = 25 >>> import vms_sys >>> q_abstim = vms_sys.bintim ('29-FEB-2000 12:34:56.78') >>> q_abstim 44585444967800000L >>> q_deltim = vms_sys.bintim ('9 12:34:56.78') >>> q_deltim -8228967800000L >>> >>> vms_lib.cvt_from_internal_time (LIB_K_MONTH_OF_YEAR, q_abstim) 2 >>> vms_lib.cvt_from_internal_time (LIB_K_DAY_OF_YEAR, q_abstim) 60 >>> vms_lib.cvt_from_internal_time (LIB_K_HOUR_OF_YEAR, q_abstim) 1428 >>> vms_lib.cvt_from_internal_time (LIB_K_MINUTE_OF_YEAR, q_abstim) Python for OpenVMS -Reference Manual PAGE 2-44 vms_lib.cvt_from_internal_time() routine 85714 >>> vms_lib.cvt_from_internal_time (LIB_K_SECOND_OF_YEAR, q_abstim) 5142896 >>> vms_lib.cvt_from_internal_time (LIB_K_DAY_OF_MONTH, q_abstim) 29 >>> vms_lib.cvt_from_internal_time (LIB_K_HOUR_OF_MONTH, q_abstim) 684 >>> vms_lib.cvt_from_internal_time (LIB_K_MINUTE_OF_MONTH, q_abstim) 41074 >>> vms_lib.cvt_from_internal_time (LIB_K_SECOND_OF_MONTH, q_abstim) 2464496 >>> >>> vms_lib.cvt_from_internal_time (LIB_K_MONTH_OF_YEAR, q_deltim) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410044, '%LIB-F-ABSTIMREQ, absolute time required,\ delta time supplied') >>> >>> vms_lib.cvt_from_internal_time (LIB_K_DELTA_WEEKS, q_deltim) 1 >>> vms_lib.cvt_from_internal_time (LIB_K_DELTA_DAYS, q_deltim) 9 >>> vms_lib.cvt_from_internal_time (LIB_K_DELTA_HOURS, q_deltim) 228 >>> vms_lib.cvt_from_internal_time (LIB_K_DELTA_MINUTES, q_deltim) 13714 >>> vms_lib.cvt_from_internal_time (LIB_K_DELTA_SECONDS, q_deltim) 822896 >>> >>> vms_lib.cvt_from_internal_time (LIB_K_DELTA_WEEKS, q_abstim) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410052, '%LIB-F-DELTIMREQ, delta time required,\ absolute time supplied') >>> >>> vms_lib.cvt_from_internal_time ('X', q_deltim) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> >>> # ------------------------------v >>> vms_lib.cvt_from_internal_time (999, q_deltim) Warning! This test caused a SS$_ROPRAND exception in LIBRTL on OpenVMS VAX V6.1! >>> vms_lib.cvt_from_internal_time (op, 'X') Python for OpenVMS -Reference Manual PAGE 2-45 vms_lib.cvt_from_internal_time() routine Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: input-time - must be long integer >>> 25-OCT-1998 ZE. ------------------------------------------------------------------------ 2.3.10 CVT_TO_INTERNAL_TIME - Convert External Time to Internal Time Format: resultant_time = vms_lib.cvt_to_internal_time \ (operation, input_time) Returns: resultant_time OpenVMS internal format delta time that results from the conversion. 64-bit system time - a Python 'long integer'. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Arguments: operation Conversion type to be performed. Codes (LIB_K_DELTA_xxx_F) are currently (25-OCT-1998) not available. input_time Delta time to be converted. Python integer. Examples: >>> import vms_lib >>> # set up some constants >>> LIB_K_DELTA_WEEKS = 21 >>> LIB_K_DELTA_DAYS = 22 >>> LIB_K_DELTA_HOURS = 23 >>> LIB_K_DELTA_MINUTES = 24 >>> LIB_K_DELTA_SECONDS = 25 >>> import vms_sys >>> op = LIB_K_DELTA_SECONDS >>> q_restim = vms_lib.cvt_to_internal_time (op, 5) >>> q_restim -50000000L >>> vms_sys.asctim (q_restim) ' 0 00:00:05.00' >>> Python for OpenVMS -Reference Manual PAGE 2-46 vms_lib.cvt_to_internal_time() routine >>> op = LIB_K_DELTA_MINUTES >>> q_restim = vms_lib.cvt_to_internal_time (op, 127) >>> q_restim -76200000000L >>> vms_sys.asctim (q_restim) ' 0 02:07:00.00' >>> >>> op = LIB_K_DELTA_HOURS >>> q_restim = vms_lib.cvt_to_internal_time (op, 25) >>> q_restim -900000000000L >>> vms_sys.asctim (q_restim) ' 1 01:00:00.00' >>> >>> op = LIB_K_DELTA_DAYS >>> q_restim = vms_lib.cvt_to_internal_time (op, 123) >>> q_restim -106272000000000L >>> vms_sys.asctim (q_restim) ' 123 00:00:00.00' >>> >>> # more than 9999 days of delta-time are prevented >>> q_restim = vms_lib.cvt_to_internal_time (op, 10000) >>> q_restim -8640000000000000L >>> vms_sys.asctim (q_restim) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time') >>> >>> q_restim = vms_lib.cvt_to_internal_time (1,1) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1410060, '%LIB-F-INVOPER, invalid operation specified') >>> >>> vms_lib.cvt_to_internal_time ('X', 1) Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> >>> vms_lib.cvt_to_internal_time (op, 'X') Traceback (innermost last): File "", line 1, in ? Python for OpenVMS -Reference Manual PAGE 2-47 vms_lib.cvt_to_internal_time() routine TypeError: illegal argument type for built-in operation >>> 25-OCT-1998 ZE. ------------------------------------------------------------------------ 2.3.11 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 GENMAN '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): Python for OpenVMS -Reference Manual PAGE 2-48 vms_lib.cvt_vectim() routine File "", line 1, in ? vms_lib.error: (1410012, '%LIB-F-IVTIME, invalid time passed in,\ or computed') >>> >>> # 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 >>> >>> # The first tuple element is numbered 0. >>> # tuple element 2 out of range --------------vvvvv >>> resultant_time = vms_lib.cvt_vectim ((2000,2,65536,12,34,56,78)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: tuple-element:2 is not a 16-bit integer >>> >>> # The first tuple element is numbered 0. >>> # tuple element 1 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:1 is not an integer >>> 31-MAR-1999 ZE. ------------------------------------------------------------------------ 2.3.12 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 () Python for OpenVMS -Reference Manual PAGE 2-49 vms_lib.date_time() routine >>> 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' >>> vms_lib.date_time ('S') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 0 arguments; 1 given >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.13 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 GENMAN 'Programming', 'special OpenVMS datatypes' for details. If the argument is not present or None, 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 Python for OpenVMS -Reference Manual PAGE 2-50 vms_lib.day() routine 51603 >>> day_time 372304 >>> vms_lib.day (binary_time) (51603, 372304) >>> vms_lib.day (vms_sys.gettim ()) (51037, 5151320) >>> vms_lib.day () (51037, 5152244) >>> vms_lib.day (None) (51037, 5153719) >>> vms_lib.day ('A') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: must be long integer or None >>> vms_lib.day ('A','B') Traceback (innermost last): File "", line 1, in ? TypeError: function requires at most 1 argument; 2 given >>> 01-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.14 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 GENMAN 'Programming', 'special OpenVMS datatypes' for details. If the argument is not present or None, then the current day is used. Examples: Python for OpenVMS -Reference Manual PAGE 2-51 vms_lib.day_of_week() routine >>> import vms_lib >>> import vms_sys >>> weekday_list = [0,'Monday','Tuesday','Wednesday','Thursday', ... 'Friday','Saturday','Sunday'] >>> q_bintim = vms_sys.bintim ('29-FEB-2000 01:02:03.04') >>> q_bintim 44585029230400000L >>> vms_lib.day_of_week (q_bintim) 2 >>> day_number = vms_lib.day_of_week (q_bintim) >>> 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 ? TypeError: argument 1: must be long integer or None >>> vms_lib.day_of_week ('A', 'B') Traceback (innermost last): File "", line 1, in ? TypeError: function requires at most 1 argument; 2 given >>> 01-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.15 DELETE_FILE - Delete One or More Files Format: status, context, resultant_name = vms_lib.delete_file ( \ Python for OpenVMS -Reference Manual PAGE 2-52 vms_lib.delete_file() routine filespec [,default-filespec] [,related-filespec] \ [,user-success-procedure] [,user-error-procedure] \ [,user-confirm-procedure] [,user-specified-argument] \ [,file-scan-context]) Returns: status Return code from LIB$DELETE_FILE. context Updated 'file-scan-context'. If this argument is omitted (or None), then 0 is returned. resultant_name The RMS resultant file specification of the last file processed. Arguments: filespec File specification of the files to be deleted. Can include wildcards. default-filespec Default file specification of the files to be deleted. See the OpenVMS Record Management Services Reference Manual for information about default file specifications. related-filespec Related file specification of the files to be deleted. See the OpenVMS Record Management Services Reference Manual for information about related file specifications. user-success-procedure User-supplied success routine that LIB$DELETE_FILE calls after it successfully deleted a file. See the examples section for the arguments to this routine. user-error-procedure User-supplied error routine that LIB$DELETE_FILE calls when it detects an error. Return with the value 1 to tell LIB$DELETE_FILE to contine. Return with the value 0 to tell LIB$DELETE_FILE to stop processing immediately. See the examples section for the arguments to this routine. user-confirm-procedure The confirm-procedure can make more checks to determine if the current file should be deleted. If confirm routine returns a success status (bit 0 set), the file is then deleted; otherwise, the file is not deleted. See the examples section for the arguments to this routine. WARNING!Changes to the FAB can lead to crashes after returning from the user-confirm-procedure back to LIB$DELETE_FILE !! user-specified-argument This can be any Python object (including None) that is passed unchanged to the user-procedures. file-scan-context Context for deleting a list of file specifications. Supply a value of 0 for the first call. The context can be deallocated Python for OpenVMS -Reference Manual PAGE 2-53 vms_lib.delete_file() routine by calling the vms_lib.file_scan_end() routine with the context as its argument. Examples: >>> import vms_lib >>> import vms_sys >>> # define user-procedures >>> # user-success >>> def u_success (filespec, user_arg): ... print '*user-success-procedure' ... print type(filespec), filespec ... print type(user_arg), user_arg ... return 1 ... #-u_success >>> >>> # user-error >>> def u_error (filespec, l_rms_sts, l_rms_stv, \ ... l_error_source, user_arg): ... print '*user-error-procedure' ... print type(filespec), filespec ... print type(l_rms_sts), l_rms_sts ... print type(l_rms_stv), l_rms_stv ... print type(l_error_source), l_error_source ... print type(user_arg), user_arg ... return 1 ... #-u_error >>> >>> # user-confirm >>> def u_confirm (filespec, fab, user_arg): ... print '*user-confirm-procedure' ... print type(filespec), filespec ... print type(fab), fab ... print fab.FNA ... print type(user_arg), user_arg ... return 1 ... #-u_confirm >>> >>> # simple delete-test >>> file = open ('DELETE.TMP','w') >>> file.close() >>> vms_lib.delete_file ('delete.tmp;', None, None, \ ... u_success, u_error, u_confirm, 'uspec-arg') *user-confirm-procedure USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1 Python for OpenVMS -Reference Manual PAGE 2-54 vms_lib.delete_file() routine delete.tmp; <-- fab.FNA uspec-arg *user-success-procedure USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1 uspec-arg (1, 0, 'USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1') >>> # Note: 1 = status, 0 = context >>> # see if file has been deleted ... >>> import os; os.system ('DIRECTORY DELETE.TMP') %DIRECT-W-NOFILES, no files found 98960 <-- return status from subprocess >>> >>> # try to delete an open file (triggers error-procedure) >>> file = open ('DELETE.TMP','w') >>> vms_lib.delete_file ('delete.tmp;', None, None, \ ... u_success, u_error, u_confirm, 'uspec-arg') *user-confirm-procedure USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1 delete.tmp; <-- fab.FNA uspec-arg *user-error-procedure USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1 98954 <-- rms_sts 2048 <-- rms_stv 1 <-- error-source, 1= error deleting file uspec-arg (1409065, 0, 'USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1') >>> file.close() >>> >>> vms_sys.getmsg (98954) # rms_sts ('%RMS-E-FLK, file currently locked by another user', (0, 0, 0, 0)) >>> vms_sys.getmsg (2048) # rms_stv ('%SYSTEM-W-ACCONFLICT, file access conflict', (0, 0, 0, 0)) >>> >>> vms_sys.getmsg (1409065) ('%LIB-S-ERRROUCAL, error routine called', (0, 0, 0, 0)) >>> >>> # see if file has been deleted ... >>> import os; os.system ('DIRECTORY DELETE.TMP') Directory USER_HERE:[ZESSIN.DELETE] DELETE.TMP;1 Total of 1 file. 1 <-- return status from subprocess >>> Python for OpenVMS -Reference Manual PAGE 2-55 vms_lib.delete_file() routine >>> # example of wildcard delete with context >>> file = open ('DELETE1.TMP','w'); file.close() >>> file = open ('DELETE2.TMP','w'); file.close() >>> file = open ('DELETE3.TMP','w'); file.close() >>> context = 0 ... status, context, resultant_name = \ ... vms_lib.delete_file ('delete*.tmp;', None, None, \ ... u_success, u_error, u_confirm, 'uspec-arg', context) ... print status, context, resultant_name *user-confirm-procedure USER_HERE:[ZESSIN.DELETE]DELETE1.TMP;1 delete*.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.DELETE]DELETE1.TMP;1 uspec-arg *user-confirm-procedure USER_HERE:[ZESSIN.DELETE]DELETE2.TMP;1 delete*.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.DELETE]DELETE2.TMP;1 uspec-arg *user-confirm-procedure USER_HERE:[ZESSIN.DELETE]DELETE3.TMP;1 delete*.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.DELETE]DELETE3.TMP;1 uspec-arg >>> print status, context, resultant_name 1 2281736 USER_HERE:[ZESSIN.DELETE]DELETE3.TMP;1 >>> @@ more DELETE_FILE examples >>> 02-APR-1999 ZE. ------------------------------------------------------------------------ 2.3.16 DELETE_LOGICAL - Delete Logical Name Format: vms_lib.delete_logical (logical-name [,table-name]) Python for OpenVMS -Reference Manual PAGE 2-56 vms_lib.delete_logical() routine Returns: None Arguments: logical-name The logical name to be deleted. 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) Python for OpenVMS -Reference Manual PAGE 2-57 vms_lib.delete_logical() routine (DECW$LOGICAL_NAMES) %SHOW-S-NOTRAN, no translation for logical name LNM_* $ >>> 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 read-only buffer, int found >>> >>> s= 65536*'*' >>> vms_lib.delete_logical (s) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: logical-name - string size limited to\ 65535 characters >>> >>> vms_lib.delete_logical ('X',s) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: table-name - string size limited to\ 65535 characters >>> 01-DEC-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-58 vms_lib.delete_symbol() routine 2.3.17 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 1 = LIB$K_CLI_LOCAL_SYM - Local symbol table 2 = LIB$K_CLI_GLOBAL_SYM - Global symbol table If omitted or None, the local symbol table is used. Examples: $ VMS_LIB_SYM_DEFAULT = "VALUE_DEFAULT" $ VMS_LIB_SYM_NONE = "VALUE_NONE" $ VMS_LIB_SYM_GLOBAL == "VALUE_GLOBAL" $ VMS_LIB_SYM_LOCAL = "VALUE_LOCAL" >>> import vms_lib >>> LIB_K_CLI_LOCAL_SYM = 1 >>> LIB_K_CLI_GLOBAL_SYM = 2 >>> vms_lib.delete_symbol ('VMS_LIB_SYM_GLOBAL', \ ... LIB_K_CLI_GLOBAL_SYM) >>> vms_lib.delete_symbol ('VMS_LIB_SYM_LOCAL', \ ... LIB_K_CLI_LOCAL_SYM) >>> 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) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name') >>> >>> symbol_name = 'S' * 65536 >>> vms_lib.delete_symbol (symbol_name) Traceback (innermost last): Python for OpenVMS -Reference Manual PAGE 2-59 vms_lib.delete_symbol() routine File "", line 1, in ? ValueError: argument 1: symbol - string size limited to 65535 characters >>> >>> vms_lib.delete_symbol ('SYMBOL', 3) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> >>> vms_lib.delete_symbol ('NON_EXIST_SYMBOL') 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 read-only buffer, int found >>> # that means 'string' ------^^^^^^^^^^^^^^^^ >>> vms_lib.delete_symbol () Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 1 argument; 0 given >>> 02-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.18 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. The logical name SYS$DIGIT_SEP can be used to define a non-default digit separator symbol. Arguments: vms_lib.digit_sep() does not take any arguments. Examples: >>> import vms_lib Python for OpenVMS -Reference Manual PAGE 2-60 vms_lib.digit_sep() routine >>> 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.19 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) 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 Python for OpenVMS -Reference Manual PAGE 2-61 vms_lib.do_command() routine >>> 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 >>> command_string = 'C' * 65536 >>> vms_lib.do_command (command_string) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: command - string size limited to 65535 characters >>> # 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! 02-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.20 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. The Python interface uses dynamic string descriptors so it can also return a status from LIB$SFREE1_DD. acp_status The status resulting from traversing the backward links. filespec The resulting file specification string. Arguments: device_name Name of the device on which the file resides. (64 characters or less!) Python for OpenVMS -Reference Manual PAGE 2-62 vms_lib.fid_to_name() routine 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 omitted) ... >>> 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 vms_sys >>> vms_sys.getmsg (status)[0] '%SYSTEM-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: >>> >>> import vms_sys >>> vms_sys.getmsg (status)[0] '%SYSTEM-W-NOTVOLSET, volume is not part of a volume set' >>> >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,999,0)) >>> print status, acp_status, filespec 2320 2320 DISK$D1: >>> >>> import vms_sys >>> vms_sys.getmsg (status)[0] '%SYSTEM-W-NOSUCHFILE, no such file' >>> Python for OpenVMS -Reference Manual PAGE 2-63 vms_lib.fid_to_name() routine >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,99999,0)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: file-id - tuple-element:1 is not a 16-bit integer >>> # The first tuple element is numbered 0. >>> status, acp_status, filespec = vms_lib.fid_to_name ( ... 'DKA100:', (12621,17,'X')) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: file-id - tuple-element:2 is not a 16-bit integer >>> # The first tuple element is numbered 0. >>> status, acp_status, filespec = vms_lib.fid_to_name ('DKA100:', 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: file-id - must be a tuple of 3 16-bit integers >>> 23-MAR-1999 ZE. ------------------------------------------------------------------------ 2.3.21 FIND_FILE - Find File Search for files. Please note that You MUST check status (and status_value) because FIND_FILE() does NOT raise an exception when something goes wrong! Format: status, status_value, context, resultant_filespec = \ vms_lib.find_file (filespec, context, \ [default_filespec], [related_filespec], [flags]) Returns: status The return-status from LIB$FIND_FILE. status_value RMS status (FAB$L_STV) if the operation failed. context A context value for future calls to FIND_FILE. resultant_filespec Resultant file specification that LIB$FIND_FILE returns when it finds a file that matches the specification in the filespec argument. Arguments: filespec Python for OpenVMS -Reference Manual PAGE 2-64 vms_lib.find_file() routine File specification, which may contain wildcards, that LIB$FIND_FILE uses to search for the desired file. context A context value from a previous call to FIND_FILE. Use 0 for the first call. Warning! The implementation of the 'readdir()' function that is called from the 'posix' module uses LIB$FIND_FILE() with a context argument. It is strongly recommended that you always use the context argument, too. default_filespec Default file specification. See the OpenVMS Record Management Services Reference Manual for information about default file specifications. related_filespec Related file specification containing the context of the last file processed. flags See the description of LIB$FIND_FILE for details. According to the documentation (OpenVMS VAX V6.1) there are no symbolic names available to define these bits. Examples: $! create test area $ create/directory [.TMP_FF] $ copy _NLA0: [.TMP_FF]FF_1.TMP $ copy _NLA0: [.TMP_FF]FF_2.TMP $ copy _NLA0: [.TMP_FF]FF_3.TMP $ copy _NLA0: [.TMP_FF]FZ_1.TMP $ copy _NLA0: [.TMP_FF]FZ_2.TMP $ copy _NLA0: [.TMP_FF]FZ_2.ZZZ $ python [ banner page omitted ] >>> import vms_lib >>> import vms_sys >>> import string >>> context = 0 >>> status, status_value, context, resultant_filespec = \ ... vms_lib.find_file ('[.TMP_FF]FF_*.TMP', context, \ ... None, None, 1) # 1=NOWILD >>> >>> status, status_value, context, resultant_filespec (1380650, 0, 2103296, None) >>> vms_sys.getmsg (status) ('%LIB-E-NOWILD, no wildcard permitted', (0, 0, 0, 0)) >>> print vms_lib.find_file_end (context) None >>> >>> # retry to deallocate an already deallocated context >>> vms_lib.find_file_end (context) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (99596, '%RMS-F-FAB, invalid FAB or FAB not accessible') Python for OpenVMS -Reference Manual PAGE 2-65 vms_lib.find_file() routine >>> >>> context = 0 >>> status = 1 >>> while (status & 1): ... status, status_value, context, resultant_filespec = \ ... vms_lib.find_file ('[.TMP_FF]FF_*.TMP', context, \ ... None, None, 0) # 0 = allow wildcards ... status, status_value, context ... if (resultant_filespec != None): ... string.strip (resultant_filespec) ... else: ... vms_sys.getmsg (status) ... vms_sys.getmsg (status_value) ... break # reached end ... (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FF_1.TMP;1' (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FF_2.TMP;1' (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FF_3.TMP;1' (99018, 2352, 0) ('%RMS-E-NMF, no more files found', (0, 0, 0, 0)) ('%SYSTEM-W-NOMOREFILES, no more files', (0, 0, 0, 0)) >>> >>> # loop completed, context is deallocated >>> print context 0 >>> >>> # show a 'success' status value: >>> vms_sys.getmsg (65537) ('%RMS-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> # a status_value of 0 also means no error has accured >>> context = 0 >>> status, status_value, context, resultant_filespec = \ ... vms_lib.find_file ('[.TMP_FF]FF_*.TMP,FZ_*.*', context, \ ... None, None, 0) # 0 = no multiple, but wildcards allowed >>> status, status_value, context (100052, 0, 2104624) >>> vms_sys.getmsg (status) ('%RMS-F-SYN, file specification syntax error', (0, 0, 0, 0)) >>> >>> # WARNING! There is a context left! >>> print context 2104624 >>> # deallocate it >>> vms_lib.find_file_end (context) None >>> Python for OpenVMS -Reference Manual PAGE 2-66 vms_lib.find_file() routine -- use multiple and provide a default-filespec $ define FF_LNM FF_*,FZ_* ! logical name search list >>> context = 0 >>> status = 1 >>> while (status & 1): ... status, status_value, context, resultant_filespec = \ ... vms_lib.find_file ('FF_LNM', context, '[.TMP_FF].TMP', \ ... None, 2) # 2 = multiple and wildcards allowed ... status, status_value, context ... if (resultant_filespec != None): ... string.strip (resultant_filespec) ... else: ... vms_sys.getmsg (status) ... vms_sys.getmsg (status_value) ... break # reached end ... (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FF_1.TMP;1' (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FF_2.TMP;1' (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FF_3.TMP;1' (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FZ_1.TMP;1' (65537, 0, 2104624) 'DKA100:[PYTHON.PYTHON-1_5_1.VMS.TMP_FF]FZ_2.TMP;1' (99018, 2352, 2104624) ('%RMS-E-NMF, no more files found', (0, 0, 0, 0)) ('%SYSTEM-W-NOMOREFILES, no more files', (0, 0, 0, 0)) >>> >>> # a context is still active, because - according to the >>> # documentation - the data from the previous call is saved >>> # to be used as the related filespecification on the next >>> # call >>> print context 2104624 >>> # deallocate it >>> vms_lib.find_file_end (context) >>> import vms_sys >>> vms_sys.getmsg (status)[0] '%SYSTEM-S-NORMAL, normal successful completion' >>> $! delete test area $ set PROTECTION=O:RWED [.TMP_FF]*.*;*, []TMP_FF.DIR;* $ delete [.TMP_FF]*.*;*, []TMP_FF.DIR;* 11-NOV-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-67 vms_lib.find_file_end() routine 2.3.22 FIND_FILE_END - End of Find File Deallocate any memory that is used by vms_lib.find_file(). Format: vms_lib.find_file_end (context) Returns: None Arguments: context The context value from a previous call to the vms_lib.find_file() routine. WARNING! An invalid context value can result in an unhandled OpenVMS exception (SS$_ACCVIO) that aborts the Python interpreter. Examples: See the examples section of the vms_lib.find_file() routine. 02-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.23 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: 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 Python for OpenVMS -Reference Manual PAGE 2-68 vms_lib.find_image_symbol() routine 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) @@ >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.24 FORMAT_DATE_TIME - Format Date and/or Time Format: status, context, date_string = vms_lib.format_date_time \ ([date], [user-context], flags) Returns: status Condition value as returned by LIB$FORMAT_DATE_TIME. context Updated context value from the 'user-context' argument. If omitted this will be 'None'. date_string Formatted output. Python for OpenVMS -Reference Manual PAGE 2-69 vms_lib.format_date_time() routine Arguments: date Date and time to be formatted for output. 64-bit system time - a Python 'long integer'. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. user-context A context value that has previously been set by vms_lib.init_date_time_context(). flags Bitmasks like LIB_M_DATE_FIELDS are available from module vms_libdtdef. Examples: >>> import vms_lib >>> import vms_libdtdef >>> print vms_lib.format_date_time () (1, None, ' 8-AUG-1999 17:45:00.42') >>> >>> import vms_sys >>> q_bintim = vms_sys.bintim ('29-FEB-2000 12:34:56.78') >>> print vms_lib.format_date_time (q_bintim, None) (1, None, '29-FEB-2000 12:34:56.78') >>> print vms_lib.format_date_time (q_bintim, None, \ ... vms_libdtdef.LIB_M_DATE_FIELDS) (1, None, '29-FEB-2000') >>> >>> context = 0 >>> month_name = "|Jan|**Feb**|Mrz|Apr|Mai|Jun|" + \ ... "Jul|Aug|Sep|Okt|Nov|Dez|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_MONTH_NAME_ABB, month_name) >>> >>> print vms_lib.format_date_time (q_bintim, context, \ ... vms_libdtdef.LIB_M_DATE_FIELDS) (1, 2755304, '29-**Feb**-2000') >>> 08-AUG-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-70 vms_lib.format_sogw_prot() routine 2.3.25 FORMAT_SOGW_PROT - Translate a protection mask into a formatted string Format: status, protection-string = vms_lib.format_sogw_prot \ (protection-mask, [access-names], [ownership-names], [ownership-separator], [list-separator]) Returns: status Condition value as returned by LIB$FORMAT_SOGW_PROT. protection-string Formatted output. Arguments: protection-mask 16-bit protection value - Python integer. access-names Object of type 'vmsobj__access_names'. ownership-names Object of type 'vmsobj__ownership_names'. ownership-separator The separator string is inserted after the ownership name. The default value is ":". list-separator The separator string is placed between ownership/ access pairs. The default value is ",". Examples: >>> import pyvms >>> import vms_lib >>> print vms_lib.format_sogw_prot (0x1234) (1, 'System: RWD, Owner: ED, Group: RED, World: WED') >>> >>> print vms_lib.format_sogw_prot (0x1234, None, None, '=', '|') (1, 'System=RWD|Owner=ED|Group=RED|World=WED') >>> >>> accnam = vms_lib.get_accnam () >>> print accnam >>> accnam[0] = 'r' >>> accnam[1] = 'w' >>> accnam[2] = 'e' >>> accnam[3] = 'd' >>> print accnam[0:4] ['r', 'w', 'e', 'd'] >>> print vms_lib.format_sogw_prot (0x1234, accnam, None, '=', '|') Python for OpenVMS -Reference Manual PAGE 2-71 vms_lib.format_sogw_prot() routine (1, 'System=rwd|Owner=ed|Group=red|World=wed') >>> >>> ownshp = pyvms.vmsobj__ownership_names () >>> print ownshp >>> print ownshp [0:4] ['SYSTEM', 'OWNER', 'GROUP', 'WORLD'] >>> >>> print vms_lib.format_sogw_prot (0x1234, accnam, ownshp, '=', '|') (1, 'SYSTEM=rwd|OWNER=ed|GROUP=red|WORLD=wed') >>> >>> ownshp [0] = 'sys' >>> ownshp [1] = 'own' >>> ownshp [2] = 'grp' >>> ownshp [3] = 'wld' >>> print ownshp [0:4] ['sys', 'own', 'grp', 'wld'] >>> >>> print vms_lib.format_sogw_prot (0x1234, accnam, ownshp, '=', '|') (1, 'sys=rwd|own=ed|grp=red|wld=wed') >>> >>> print vms_lib.format_sogw_prot (0x1234, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: access_names - must be\ vmsobj__access_names or None >>> >>> print vms_lib.format_sogw_prot (0x1234, None, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: ownership_names - must be\ vmsobj__ownership_names or None >>> 12-AUG-1999 ZE. ------------------------------------------------------------------------ 2.3.26 FREE_DATE_TIME_CONTEXT - Free the Context Area Used When Formatting Dates and Times for Input or Output Format: context = vms_lib.free_date_time_context (user-context) Returns: context Python for OpenVMS -Reference Manual PAGE 2-72 vms_lib.free_date_time_context() routine Updated user-context argument. Arguments: user-context User context to be freed - Python integer. WARNING! An invalid context value can result in an OpenVMS SS$_ROPRAND exception! Examples: See the examples section for vms_lib.init_date_time_contexte(). 26-JUL-1999 ZE. ------------------------------------------------------------------------ 2.3.27 FREE_EF - Free Event Flag Format: vms_lib.free_ef (event_flag_number) Returns: None 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 Python for OpenVMS -Reference Manual PAGE 2-73 vms_lib.free_ef() routine >>> 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') >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.28 GETDVI - Get Device/Volume Information Format: 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: item_name Text-string of item to retrieve (e.g. 'DVI$_OWNUIC'). This is the primary device characteristic. One must specifiy a tuple here (e.g. ('DVI$_DEVTYPE',1)), to request the secondary device characteristic. The first element of the tuple is the item code. The second element of the tuple is the value 1 (=DVI$M_SECONDARY). This value is logically OR-ed with the binary value of the item code. WARNING! One should not use this as a 'trick' to construct new item codes! The interface uses the text string to look up the VMSDEF information and takes this data to decide about the data type to return. 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 Python for OpenVMS -Reference Manual PAGE 2-74 vms_lib.getdvi() routine >>> ownuic = vms_lib.getdvi ("DVI$_OWNUIC",None,"DKA100:") >>> hex (ownuic) '0x10004' <-- [1,4] >>> vms_lib.getdvi ("DVI$_LOGVOLNAM",None,"DKA100:") 'DISK$D1' >>> vms_lib.getdvi ("DVI$_FREEBLOCKS",None,"DKA100:") 528888 >>> >>> # 32 is a channel number that was learned via >>> # SDA> show process/channel >>> vms_lib.getdvi ("DVI$_DEVNAM",32,None) '_DKA100:' >>> vms_lib.getdvi ("DVI$_FREEBLOCKS",32,None) 528888 >>> vms_lib.getdvi ("DVI$_FREEBLOCKS",32) 528888 >>> 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:' >>> # FTA12: is a terminal which is used in an editor session >>> # the editor attaches a mailbox (to catch broadcast messages) >>> # to the terminal >>> vms_lib.getdvi(('DVI$_DEVTYPE',0),None,'FTA12:') 112 <-- Device_Type: VT300_Series >>> vms_lib.getdvi(('DVI$_DEVTYPE',1),None,'FTA12:') 1 <-- DT$_MBX >>> >>> vms_lib.getdvi(('DVI$_MBX',0),None,'FTA12:') 0 <-- primary device is not a mailbox >>> vms_lib.getdvi(('DVI$_MBX',1),None,'FTA12:') 1 <-- secondary device is a mailbox >>> >>> 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') Python for OpenVMS -Reference Manual PAGE 2-75 vms_lib.getdvi() routine >>> 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:") Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: channel - must be 16-bit integer or None >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,None) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name') >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: expected read-only buffer, int found >>> # that means 'string' ------^^^^^^^^^ >>> vms_lib.getdvi ('DVI$_LOGVOLNAM',None,sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: expected read-only buffer, int found >>> # that means 'string' ------^^^^^^^^^ >>> s = 65536*'X' >>> vms_lib.getdvi (s,None,"DEVNAM") Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: item-code - string size limited to\ 65535 characters >>> >>> vms_lib.getdvi ("DVI$_DEVNAM",None,s) Traceback (innermost last): File "", line 1, in ? ValueError: argument 3: device-name - string size limited to\ 65535 characters >>> 03-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.29 GETJPI - Get Job/Process Information This routine allows the programmer to receive a single item of information from the specified process per call. The vms_sys.getjpiw() routine provides support to request multiple items at once at the expense of additional work to extract the data from the returned dictionary. Python for OpenVMS -Reference Manual PAGE 2-76 vms_lib.getjpi() routine Note: the 'vms_jpidef' module contains bitmasks and constants 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'. 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 Name of process to lookup. Note: normally pid_ctx overrides process_name! Use pid_ctx = 'None' to force usage of process_name. special notes about some item codes: JPI$_AUTHPRIV The authorized privilege image mask is returned as an unsigned Python long integer. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. JPI$_CREPRC_FLAGS Bitmask values (PRC_M_xxx) for this field are in module 'vms_prcdef'. JPI$_CURPRIV The current privilege image mask is returned as an unsigned Python long integer. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. JPI$_EXCVEC LIB$GETJPI returns only one longword. JPI$_FINALEXC LIB$GETJPI returns only one longword. JPI$_IMAGPRIV The image privilege image mask is returned as an unsigned Python long integer. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. JPI$_JOBTYPE Constant values (JPI_K_xxx) for this field are in module 'vms_jpidef'. Python for OpenVMS -Reference Manual PAGE 2-77 vms_lib.getjpi() routine JPI$_LOGIN_FLAGS Bitmask values (JPI_M_xxx) for this field are in module 'vms_jpidef'. JPI$_MODE Constant values (JPI_K_xxx) for this field are in module 'vms_jpidef'. JPI$_PHDFLAGS Bitmask values for this field are currently not available JPI$_PROCPRIV The process privilege image mask is returned as an unsigned Python long integer. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. JPI$_STATE Constant values (SCH_C_xxx) for this field are in module 'vms_statedef'. JPI$_STS + JPI$_STS2 Bitmask values ($PCBDEF) for these fields are currently not available JPI$_UAF_FLAGS Bitmask values (UAI_M_xxx) for this field are in module 'vms_uaidef'. Examples: >>> import vms_lib >>> import vms_sys # ASCTIM >>> pid, state = vms_lib.getjpi ('JPI$_STATE',0) >>> pid, state (232, 14) >>> # this is vms_statedef.SCH_C_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') >>> l_pid, q_lgitim = vms_lib.getjpi ('JPI$_LOGINTIM', 0) >>> l_pid, q_lgitim (341, 44135430131500000L) >>> import vms_sys # ASCTIM >>> vms_sys.asctim (q_lgitim) '26-SEP-1998 16:10:13.15' >>> 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) Python for OpenVMS -Reference Manual PAGE 2-78 vms_lib.getjpi() routine 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: expected read-only buffer, module found >>> vms_lib.getjpi ('JPI$_PID',None,1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: expected read-only buffer, module found *** 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,vms_sys.asctim(li) ... #-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') >>> 10-FEB-1999 ZE. ------------------------------------------------------------------------ 2.3.30 GETQUI - Get Queue Information Note: the 'vms_quidef' module contains bitmasks and constants that are defined in '$QUIDEF'. Access to the item codes ("QUI$_name") is possible via the 'pyvms' module. Format: Python for OpenVMS -Reference Manual PAGE 2-79 vms_lib.getqui() routine 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. search_flags Optional bit mask. Constants are containted in the vms_quidef module (e.g. vms_quidef.QUI_M_SEARCH_ALL_JOBS). special notes about some item codes: QUI$_CHARACTERISTICS A Python long integer. Warning! This is a 128-bit mask. QUI$_CHARGE_CODE Is an alias name to QUI$_ACCOUNT_NAME. QUI$_FILE_IDENTIFICATION Contains several information combined in a 28-byte 'string'. @@Should be changed to a 'tuple of bytes', but GETQUI can't do that, yet. Examples: >>> import vms_lib >>> import vms_quidef >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_JOB_NAME",5) 'X2' >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_PRIORITY",5) 100 >>> q_sbmtim = vms_lib.getqui ("QUI$_DISPLAY_ENTRY", \ ... "QUI$_SUBMISSION_TIME",9) >>> import vms_sys >>> vms_sys.asctim (q_sbmtim) ' 2-NOV-1997 19:30:55.49' >>> >>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_NOTE",5) Python for OpenVMS -Reference Manual PAGE 2-80 vms_lib.getqui() routine '' >>> 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 >>> 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 integer or None *** example of wildcard lookup *** Python for OpenVMS -Reference Manual PAGE 2-81 vms_lib.getqui() routine >>> 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 < > 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,'*') Python for OpenVMS -Reference Manual PAGE 2-82 vms_lib.getqui() routine >>> print 'Queue:', queue_name, '<', queue_desc, '>' Queue: BATQ_BATCH < > >>> # (queue does not have a description) >>> vms_lib.getqui ("QUI$_CANCEL_OPERATION") >>> 09-JAN-1999 ZE. ------------------------------------------------------------------------ 2.3.31 GETSYI - Get Systemwide Information Note: the 'vms_syidef' module contains bitmasks and constants 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: 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 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_lib >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',0) >>> csid, item Python for OpenVMS -Reference Manual PAGE 2-83 vms_lib.getsyi() routine (0, 'HERE') >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,'HERE') >>> csid, item (0, 'HERE') >>> vms_lib.getsyi ("SYI$_PAGFILCNT",0) (0, 4) >>> vms_lib.getsyi ('SYI$_NODE_HWVERS',0) (0, (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 12, 32)) >>> 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) >>> l_sid, q_bootim = vms_lib.getsyi('SYI$_BOOTTIME',0) >>> l_sid, q_bootim (0, 44136120482800000L) >>> import vms_sys >>> vms_sys.asctim (q_bootim) '27-SEP-1998 11:20:48.28' >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,'NONONO') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (652, '%SYSTEM-F-NOSUCHNODE, remote node is unknown') >>> >>> vms_lib.getsyi (sys,0) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, module found >>> vms_lib.getsyi ("SYI$_RMS_GBLBUFQUO",sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: cluster-system-id - must be integer or None >>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,sys) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: expected read-only buffer, module found >>> 04-DEC-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-84 vms_lib.get_accnam() routine 2.3.32 GET_ACCNAM - Get Access Name Table for Protected Object Class Format: accnam = vms_lib.get_accnam ([clsnam] [,objnam]) Returns: accnam Object of type 'vmsobj__access_names'. Arguments: clsnam Security object class name (e.g. "FILE"). objnam Name of the protected object (e.g. "ACL.DAT"). Examples: >>> import vms_lib >>> accnam = vms_lib.get_accnam () >>> print accnam >>> >>> accnam = vms_lib.get_accnam ('QUEUE') >>> print accnam >>> >>> accnam = vms_lib.get_accnam ('QUEUE', 'NOQUEUE') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (294970, '%JBC-E-NOSUCHQUE, no such queue') >>> >>> accnam = vms_lib.get_accnam ('BAD_CLASS') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (9436, '%SYSTEM-F-NOCLASS, no matching object\ class was located') >>> >>> c= 65536*'*' >>> vms_lib.get_accnam (c) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: clsnam - string size limited to 65535\ characters >>> 28-JUN-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-85 vms_lib.get_accnam_by_context() routine ------------------------------------------------------------------------ 2.3.33 GET_ACCNAM_BY_CONTEXT - Get Access Name Table for Protected Object Class Format: accnam = vms_lib.get_accnam_by_context (contxt) Returns: accnam Object of type 'vmsobj__access_names'. Arguments: contxt context value that is returned by vms_sys.get_security() or vms_sys.set_security() Examples: ----- establish a context first >>> import vms_sys >>> >>> contxt = 0 >>> flags = 0 >>> itmlst = ( ('OSS$_OWNER',0),) >>> >>> dict = vms_sys.get_security ('FILE', 'CC_PYTHON.COM', None, \ ... flags, itmlst, contxt) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-W-NOENTRY, access control entry not found >>> >>> contxt = dict.get ('contxt') >>> print contxt 2147235920 >>> ----- get access_names for this context >>> import vms_lib >>> >>> accnam = vms_lib.get_accnam_by_context (contxt) >>> print accnam >>> Python for OpenVMS -Reference Manual PAGE 2-86 vms_lib.get_accnam_by_context() routine ----- release the context >>> import vms_ossdef >>> contxt = dict.get ('contxt') >>> flags = vms_ossdef.OSS_M_RELCTX >>> >>> dict = vms_sys.get_security (None, None, None, flags, \ ... None, contxt) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> contxt = dict.get ('contxt') >>> print contxt 0 <-- context has been released >>> ----- some error examples >>> accnam = vms_lib.get_accnam_by_context (0) Traceback (innermost last): File ">", line 1, in ? vms_lib.error: (9436, '%SYSTEM-F-NOCLASS, no matching object class\ was located') >>> >>> accnam = vms_lib.get_accnam_by_context (55) Traceback (innermost last): File ">", line 1, in ? vms_lib.error: (8996, '%SYSTEM-F-BADCONTEXT, invalid or corrupted\ context encountered') >>> >>> accnam = vms_lib.get_accnam_by_context ('X') Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> 19-JUL-1999 ZE. ------------------------------------------------------------------------ 2.3.34 GET_COMMAND - Get Line from SYS$COMMAND Format: data_from_command, resultant_length = \ vms_lib.get_command ([prompt] [,buffer_length]) Python for OpenVMS -Reference Manual PAGE 2-87 vms_lib.get_command() routine 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-88 vms_lib.get_common() routine 2.3.35 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 = vms_lib.get_common () Returns: resultant_string A copy of the data that was stored by vms_lib.put_common() in 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 = vms_lib.get_common () >>> print resultant_string 1234ABC >>> print len (resultant_string) 7 >>> 11-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.36 GET_DATE_FORMAT - Get the User's Date Input Format Format: status, context, format-string = \ vms_lib.get_date_format ([user-context]) Returns: status Condition value as returned by LIB$GET_DATE_FORMAT. context Updated context value from the 'user-context' argument. If Python for OpenVMS -Reference Manual PAGE 2-89 vms_lib.get_date_format() routine omitted this will be 'None'. format-string The translation of LIB$DT_INPUT_FORMAT and LIB$FORMAT_MNEMONICS or a pre-initialized value when the user-context argument is given. Arguments: user-context A context value that has previously been set by vms_lib.init_date_time_context(). Examples: >>> import vms_lib >>> print vms_lib.get_date_format () (1, None, 'DD-MONTH-YYYY4 HH:MM:SS.CC2') >>> >>> import vms_libdtdef >>> context = 0 >>> format = "|JJJJ|MM|TT|ST|MI|SE|HU| |MONAT|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_FORMAT_MNEMONICS, format) >>> >>> print vms_lib.get_date_format (context) (1, 2755576, 'TT-MONAT-JJJJ4 ST:MI:SE.HU2') >>> 08-AUG-1999 ZE. ------------------------------------------------------------------------ 2.3.37 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 () Returns: event_flag_number Number of the local event flag that was allocated. Arguments: Python for OpenVMS -Reference Manual PAGE 2-90 vms_lib.get_ef() routine 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) 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.38 GET_FOREIGN - Get Foreign Command Line Format: resultant_string, flags_out = vms_lib.get_foreign \ ([prompt_string] [,flags]) Returns: 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 Python for OpenVMS -Reference Manual PAGE 2-91 vms_lib.get_foreign() routine 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 (V001P1, 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) $ Python for OpenVMS -Reference Manual PAGE 2-92 vms_lib.get_foreign() routine ----- $ 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) $ ----- 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.39 GET_MAXIMUM_DATE_LENGTH - Retrieve the Maximum Length of a Date/Time String Format: status, context, date_length = \ vms_lib.get_maximum_date_length ([user-context], flags) Returns: status Condition value as returned by LIB$GET_MAXIMUM_DATE_LENGTH. context Updated context value from the 'user-context' argument. If omitted this will be 'None'. date_length Maximum possible string size returned by vms_lib.format_date_string(). Arguments: user-context A context value that has previously been set by vms_lib.init_date_time_context(). flags Bitmasks like LIB_M_DATE_FIELDS are available from module vms_libdtdef. Examples: >>> import vms_lib >>> import vms_libdtdef >>> print vms_lib.get_maximum_date_length () (1, None, 23) >>> >>> print vms_lib.get_maximum_date_length \ Python for OpenVMS -Reference Manual PAGE 2-93 vms_lib.get_maximum_date_length() routine ... (None, vms_libdtdef.LIB_M_DATE_FIELDS) (1, None, 11) >>> >>> context = 0 >>> month_name = "|Jan|**Feb**|Mrz|Apr|Mai|Jun|" + \ ... "Jul|Aug|Sep|Okt|Nov|Dez|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_MONTH_NAME_ABB, month_name) >>> >>> print vms_lib.get_maximum_date_length (context) (1, 2756880, 27) >>> print vms_lib.get_maximum_date_length \ ... (context,vms_libdtdef.LIB_M_DATE_FIELDS) (1, 2756880, 15) >>> 08-AUG-1999 ZE. ------------------------------------------------------------------------ 2.3.40 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 1 = LIB$K_CLI_LOCAL_SYM - Local symbol table 2 = LIB$K_CLI_GLOBAL_SYM - Global symbol table Arguments: symbol name of the symbol Examples: $ SYM_LOCAL = "LOCAL_SYMBOL" $ SYM_GLOBAL == "GLOBAL_SYMBOL" >>> import vms_lib >>> LIB_K_CLI_LOCAL_SYM = 1 >>> LIB_K_CLI_GLOBAL_SYM = 2 >>> print vms_lib.get_symbol ('$STATUS') ('%X00000001', 2) Python for OpenVMS -Reference Manual PAGE 2-94 vms_lib.get_symbol() routine >>> >>> symbol, table = vms_lib.get_symbol ('$STATUS') >>> print symbol, '-', table %X00000001 - 2 >>> >>> t = vms_lib.get_symbol ('$STATUS') >>> t ('%X00000001', 2) >>> type(t) >>> print vms_lib.get_symbol ('$STATUS')[0] %X00000001 >>> >>> vms_lib.get_symbol ('SYM_LOCAL') ('LOCAL_SYMBOL', 1) >>> vms_lib.get_symbol ('SYM_GLOBAL') ('GLOBAL_SYMBOL', 2) >>> >>> symbol = 'S' >>> vms_lib.get_symbol (symbol) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409892, '%LIB-F-NOSUCHSYM, no such symbol') >>> >>> symbol = 'S' * 257 >>> vms_lib.get_symbol (symbol) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name') >>> >>> symbol = 'S' * 65536 >>> vms_lib.get_symbol (symbol) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: symbol - string size limited to\ 65535 characters >>> >>> 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 read-only buffer, int found Python for OpenVMS -Reference Manual PAGE 2-95 vms_lib.get_symbol() routine >>> # that means 'string' ------!!!!!!!!! >>> vms_lib.get_symbol (None) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, None found >>> 20-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.41 GET_USERS_LANGUAGE - Return the User's Language Format: users_language = vms_lib.get_users_language () Returns: users_language Translation of the logical name "SYS$LANGUAGE". If the translation fails, then 'ENGLISH' is returned. Arguments: vms_lib.get_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' ! >>> 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 >>> Python for OpenVMS -Reference Manual PAGE 2-96 vms_lib.get_users_language() routine 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.42 INIT_DATE_TIME_CONTEXT - Initialize the Context Area Used in Formatting Dates and Times for Input or Output Format: context = vms_lib.init_date_time_context \ (user-context, component, init-string) Returns: context Updated 'user-context' argument. Arguments: user-context User context for repeated calls to INIT_DATE_TIME_CONTEXT - Python integer. WARNING! An invalid context value can result in an OpenVMS SS$_ROPRAND exception! component The component to be initialized. Constants like LIB_K_MONTH_NAME are available in module vms_libdtdef. init-string The characters which are to be used in formatting dates and times for input or output. Examples: >>> import vms_lib >>> import vms_libdtdef >>> context = 0 # initialize >>> month_name = "|1|2|3|4|5|6|7|8|9|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_MONTH_NAME, month_name) Traceback (innermost last): File "", line 2, in ? vms_lib.error: (1410092, '%LIB-F-NUMELEMENTS, number of elements\ incorrect for component') >>> >>> month_name = "|Januar|Februar|Maerz|April|Mai|Juni|" + \ ... "Juli|August|September|Oktober|November|Dezember|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_MONTH_NAME, month_name) >>> >>> month_name = "|Jan|Feb|Mrz|Apr|Mai|Jun|" + \ Python for OpenVMS -Reference Manual PAGE 2-97 vms_lib.init_date_time_context() routine ... "Jul|Aug|Sep|Okt|Nov|Dez|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_MONTH_NAME_ABB, month_name) >>> >>> weekday_name = "|Montag|Dienstag|Mittwoch|Donnerstag|" + \ ... "Freitag|Samstag|Sonntag|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_WEEKDAY_NAME, weekday_name) >>> >>> weekday_name = "|Mo|Di|Mi|Do|Fr|Sa|So|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_WEEKDAY_NAME_ABB, ... weekday_name) >>> >>> meridiem_id = "|Vormittag|Nachmittag|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_MERIDIEM_INDICATOR, ... meridiem_id) >>> >>> language = "|Deutsch|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_LANGUAGE, language) >>> >>> relative_day_name = "|gestern|heute|morgen|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_RELATIVE_DAY_NAME, ... relative_day_name) >>> >>> format = "|JJJJ|MM|TT|SS|MM|SS|HH| |MONAT|" >>> context = vms_lib.init_date_time_context (context, ... vms_libdtdef.LIB_K_FORMAT_MNEMONICS, format) >>> --- release this context >>> context = vms_lib.free_date_time_context (context) >>> print context 0 >>> 25-JUL-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-98 vms_lib.lp_lines() routine 2.3.43 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 ("SYS$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 ? TypeError: function requires no arguments >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.44 PARSE_ACCESS_CODE - Parse Access Encoded Name String Format: status, access-mask, end-position = vms_lib.parse_access_code \ (access-string, [access-names], ownership-category) Returns: Python for OpenVMS -Reference Manual PAGE 2-99 vms_lib.parse_access_code() routine status Condition value as returned by LIB$PARSE_ACCESS_CODE. access-mask A 16-bit value in a Python integer. end-position Indicates the offending location when a parse error occured. Arguments: access-string Each access name is abbreviated to one letter - e.g. "RWE". access-names Object of type 'vmsobj__access_names'. ownership-category See examples below and the RTL manual. Examples: >>> import vms_lib >>> import vms_sys >>> # define ownership categories >>> own_cat_sys = 0x000f >>> own_cat_own = 0x00f0 >>> own_cat_grp = 0x0f00 >>> own_cat_wld = 0xf000 >>> status, access_mask, end_position = \ ... vms_lib.parse_access_code ('S:RW', None, own_cat_sys) >>> print status, access_mask, end_position 1409588 0 0 >>> print vms_sys.getmsg (status) [0] %LIB-F-INVARG, invalid argument(s) >>> >>> print vms_lib.parse_access_code ('W', None, own_cat_sys) (1, 2, 1) >>> print vms_lib.parse_access_code ('RW', None, own_cat_sys) (1, 3, 2) >>> print vms_lib.parse_access_code ('RW', None, own_cat_grp) (1, 768, 2) >>> print hex (768) 0x300 >>> 0x300 ^^^ ||\-- system |\--- owner \---- group >>> status, access_mask, end_position = \ Python for OpenVMS -Reference Manual PAGE 2-100 vms_lib.parse_access_code() routine ... vms_lib.parse_access_code ('RWX', None, own_cat_sys) >>> print status, access_mask, end_position 1409588 0 2 >>> print vms_sys.getmsg (status) [0] %LIB-F-INVARG, invalid argument(s) >>> >>> accnam = vms_lib.get_accnam () >>> print accnam [0:4] ['READ', 'WRITE', 'EXECUTE', 'DELETE'] >>> accnam [0] = 'A' >>> accnam [1] = 'B' >>> accnam [2] = 'C' >>> accnam [3] = 'D' >>> print accnam [0:4] ['A', 'B', 'C', 'D'] >>> >>> status, access_mask, end_position = \ ... vms_lib.parse_access_code ('AB', accnam, own_cat_sys) >>> print status, access_mask, end_position 1 3 2 >>> status, access_mask, end_position = \ ... vms_lib.parse_access_code ('CD', accnam, own_cat_sys) >>> print status, access_mask, end_position 1 12 2 >>> 12-AUG-1999 ZE. ------------------------------------------------------------------------ 2.3.45 PARSE_SOGW_PROT - Parse Protection String Format: status, protection-mask, ownership-mask, end-position =\ vms_lib.parse_sogw_prot (protection-string, [access-names]) Returns: status Condition value as returned by LIB$PARSE_SOGW_PROT. protection-mask Translated OpenVMS protection mask. A 16-bit value in a Python integer. ownership-mask Indicates which ownership names (e.g. SYSTEM) were present in 'protection-string'. A 16-bit value in a Python integer. end-position Indicates the offending location when a parse error occured. Arguments: Python for OpenVMS -Reference Manual PAGE 2-101 vms_lib.parse_sogw_prot() routine protection-string See the RTL manual for details. access-names Object of type 'vmsobj__access_names'. Examples: >>> import vms_lib >>> import vms_sys >>> # define ownership categories >>> own_cat_sys = 0x000f >>> own_cat_own = 0x00f0 >>> own_cat_grp = 0x0f00 >>> own_cat_wld = 0xf000 >>> status, protection_mask, ownership_mask, end_position = \ ... vms_lib.parse_sogw_prot ('S:RW', None) >>> print (status, hex(protection_mask), \ ... hex(ownership_mask), end_position) (1, '0xfffc', '0xf', 4) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> # did protection string contain the system ownership ? >>> print ((ownership_mask & own_cat_sys) != 0) 1 <-- yes >>> # did protection string contain the owner ownership ? >>> print ((ownership_mask & own_cat_own) != 0) 0 <-- no >>> >>> status, protection_mask, ownership_mask, end_position = \ ... vms_lib.parse_sogw_prot ('S:R,O:W,G:E,W:D', None) >>> print (status, hex(protection_mask), \ ... hex(ownership_mask), end_position) (1, '0x7bde', '0xffff', 15) >>> >>> accnam = vms_lib.get_accnam () >>> print accnam [0:4] ['READ', 'WRITE', 'EXECUTE', 'DELETE'] >>> accnam [0] = 'A' >>> accnam [1] = 'B' >>> accnam [2] = 'C' >>> accnam [3] = 'D' >>> print accnam [0:4] ['A', 'B', 'C', 'D'] >>> >>> status, protection_mask, ownership_mask, end_position = \ ... vms_lib.parse_sogw_prot ('S:A,O:AB,G:ABC,W:CD', None) >>> print (status, hex(protection_mask), \ Python for OpenVMS -Reference Manual PAGE 2-102 vms_lib.parse_sogw_prot() routine ... hex(ownership_mask), end_position) (1409668, '0x0', '0x0', 2) >>> print vms_sys.getmsg(status)[0] %LIB-F-SYNTAXERR, string syntax error detected by LIB$TPARSE >>> >>> status, protection_mask, ownership_mask, end_position = \ ... vms_lib.parse_sogw_prot ('S:A,O:AB,G:ABC,W:CD', accnam) >>> print (status, hex(protection_mask), \ ... hex(ownership_mask), end_position) (1, '0x38ce', '0xffff', 19) >>> >>> long_string = 65536 * 'X' >>> status, protection_mask, ownership_mask, end_position = \ ... vms_lib.parse_sogw_prot (long_string, None) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: protection_string - string size limited\ to 65535 characters >>> >>> status, protection_mask, ownership_mask, end_position = \ ... vms_lib.parse_sogw_prot ('S:R', 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: access_names - must be\ vmsobj__access_names or None >>> 13-AUG-1999 ZE. ------------------------------------------------------------------------ 2.3.46 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 Python for OpenVMS -Reference Manual PAGE 2-103 vms_lib.put_common() routine 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.47 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 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 Python for OpenVMS -Reference Manual PAGE 2-104 vms_lib.put_output() routine 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.48 RADIX_POINT - Radix Point Symbol Format: radix_point_string = vms_lib.radix_point () Returns: 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. The logical name SYS$RADIX_POINT can be used to define a non-default radix point symbol. 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" Python for OpenVMS -Reference Manual PAGE 2-105 vms_lib.radix_point() routine >>> 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.49 RENAME_FILE - Rename One or More Files Format: status, context, old-resultant-name, new-resultant-name = \ vms_lib.rename_file (old-filespec, new-filespec \ [,default-filespec] [,related-filespec] [,flags] \ [,user-success-procedure] [,user-error-procedure] \ [,user-confirm-procedure] [,user-specified-argument] \ [,file-scan-context]) Returns: status Return code from LIB$RENAME_FILE. context Updated 'file-scan-context'. If this argument is omitted (or None), then 0 is returned. old-resultant-name The old RMS resultant file specification of the last file processed. new-resultant-name The new RMS resultant file specification of the last file processed. Arguments: old-filespec File specification of the files to be renamed. Can include wildcards. new-filespec File specification for the new file names. This specification need not be complete; fields omitted or Python for OpenVMS -Reference Manual PAGE 2-106 vms_lib.rename_file() routine specified by using the wildcard character (*) will be filled in from the existing file's name using the same rules as for the DCL command RENAME. default-filespec Default file specification of the files to be renamed. See the OpenVMS Record Management Services Reference Manual for information about default file specifications. related-filespec Related file specification of the files to be renamed. See the OpenVMS Record Management Services Reference Manual for information about related file specifications. flags flags define optional behaviour. See the OpenVMS documentation for a definition of the bits. There are no symbolic names available. user-success-procedure User-supplied success routine that LIB$RENAME_FILE calls after it successfully renamed a file. See the examples section for the arguments to this routine. user-error-procedure User-supplied error routine that LIB$RENAME_FILE calls when it detects an error. Return with the value 1 to tell LIB$RENAME_FILE to contine. Return with the value 0 to tell LIB$RENAME_FILE to stop processing immediately. See the examples section for the arguments to this routine. user-confirm-procedure The confirm-procedure can make more checks to determine if the current file should be renamed. If confirm routine returns a success status (bit 0 set), the file is then deleted; otherwise, the file is not deleted. See the examples section for the arguments to this routine. user-specified-argument This can be any Python object (including None) that is passed unchanged to the user-procedures. file-scan-context Context for renaming a list of file specifications. Supply a value of 0 for the first call. The context can be deallocated by calling the vms_lib.file_scan_end() routine with the context as its argument. Examples: >>> import vms_lib >>> import vms_sys >>> # define user-procedures >>> # user-success >>> def u_success (old_filespec, new_filespec, user_arg): ... print '*user-success-procedure' ... print type(old_filespec), old_filespec ... print type(new_filespec), new_filespec ... print type(user_arg), user_arg Python for OpenVMS -Reference Manual PAGE 2-107 vms_lib.rename_file() routine ... return 1 ... #-u_success >>> >>> # user-error >>> def u_error (old_filespec, new_filespec, l_rms_sts, l_rms_stv, \ ... l_error_source, user_arg): ... print '*user-error-procedure' ... print type(old_filespec), old_filespec ... print type(new_filespec), new_filespec ... print type(l_rms_sts), l_rms_sts ... print type(l_rms_stv), l_rms_stv ... print type(l_error_source), l_error_source ... print type(user_arg), user_arg ... return 1 ... #-u_error >>> >>> # user-confirm >>> def u_confirm (old_filespec, new_filespec, old_fab, user_arg): ... print '*user-confirm-procedure' ... print type(old_filespec), old_filespec ... print type(new_filespec), new_filespec ... print type(old_fab), old_fab ... print old_fab.FNA ... print type(user_arg), user_arg ... return 1 ... #-u_confirm >>> >>> # simple rename-test >>> file = open ('RENAME-FROM.TMP','w') >>> file.close() >>> status, context, old_result, new_result = \ ... vms_lib.rename_file ('rename-from.tmp;', 'rename-to.tmp;', \ ... None, None, None, \ ... u_success, u_error, u_confirm, 'uspec-arg') *user-confirm-procedure USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP; rename-from.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;1 uspec-arg >>> >>> print status, context 1 0 >>> vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) Python for OpenVMS -Reference Manual PAGE 2-108 vms_lib.rename_file() routine >>> print old_result USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1 >>> print new_result USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;1 >>> >>> # see if file has been renamed ... >>> import os; os.system ('DIRECTORY RENAME-*.TMP') Directory USER_HERE:[ZESSIN.RENAME] RENAME-TO.TMP;1 Total of 1 file. 1 <-- return status from subprocess >>> >>> # delete file >>> os.system ('DELETE/NOCONFIRM RENAME-*.TMP;*') 1 <-- return status from subprocess >>> >>> # try to rename a non-existing file (triggers error-procedure) >>> status, context, old_result, new_result = \ ... vms_lib.rename_file ('no-file.tmp;', 'new-file.tmp;', \ ... None, None, None, \ ... u_success, u_error, u_confirm, 'uspec-arg') *user-error-procedure USER_HERE:[ZESSIN.RENAME]NO-FILE.TMP; new-file.tmp; 98962 <-- rms_sts 2320 <-- rms_stv 0 <-- error-source uspec-arg >>> # ... print status, context 1409065 0 >>> print old_result USER_HERE:[ZESSIN.RENAME]NO-FILE.TMP; >>> print new_result new-file.tmp; >>> >>> vms_sys.getmsg (98962) # rms_sts ('%RMS-E-FNF, file not found', (0, 0, 0, 0)) >>> vms_sys.getmsg (2320) # rms_stv ('%SYSTEM-W-NOSUCHFILE, no such file', (0, 0, 0, 0)) >>> >>> vms_sys.getmsg (1409065) ('%LIB-S-ERRROUCAL, error routine called', (0, 0, 0, 0)) >>> >>> # example of wildcard delete with context Python for OpenVMS -Reference Manual PAGE 2-109 vms_lib.rename_file() routine >>> file = open ('RENAME1.TMP','w'); file.close() >>> file = open ('RENAME2.TMP','w'); file.close() >>> file = open ('RENAME3.TMP','w'); file.close() >>> context = 0 >>> status, context, old_result, new_result = \ ... vms_lib.rename_file ('rename*.tmp;', '*.t-tmp', ... None, None, None, \ ... u_success, u_error, u_confirm, \ ... 'uspec-arg', context) >>> print status, context >>> print old_result >>> print new_result *user-confirm-procedure USER_HERE:[ZESSIN.RENAME]RENAME1.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME1.T-TMP; rename*.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.RENAME]RENAME1.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME1.T-TMP;1 uspec-arg *user-confirm-procedure USER_HERE:[ZESSIN.RENAME]RENAME2.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME2.T-TMP; rename*.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.RENAME]RENAME2.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME2.T-TMP;1 uspec-arg *user-confirm-procedure USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP; rename*.tmp; uspec-arg *user-success-procedure USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1 USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;1 uspec-arg >>> print status, context 1 2374408 >>> print old_result USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1 >>> print new_result USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;1 >>> >>> import os; os.system ('DIRECTORY RENAME*.*') Directory USER_HERE:[ZESSIN.RENAME] RENAME1.T-TMP;1 RENAME2.T-TMP;1 RENAME3.T-TMP;1 Python for OpenVMS -Reference Manual PAGE 2-110 vms_lib.rename_file() routine Total of 3 files. 1 <-- return status from subprocess >>> @@ more RENAME_FILE examples >>> 01-FEB-1999 ZE. ------------------------------------------------------------------------ 2.3.50 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 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 Python for OpenVMS -Reference Manual PAGE 2-111 vms_lib.reserve_ef() routine >>> 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.51 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 Python for OpenVMS -Reference Manual PAGE 2-112 vms_lib.run_program() routine >>> 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 read-only buffer, 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; $ 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.52 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: 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. It is only put into the dictionary, when LIB$SET_LOGICAL returns a success status. Arguments: logical-name Python for OpenVMS -Reference Manual PAGE 2-113 vms_lib.set_logical() routine 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() >>> >>> 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 >>> >>> import vms_sys >>> vms_sys.getmsg (1585)[0] '%SYSTEM-S-SUPERSEDE, logical name superseded' >>> * Note: the logical name LNM3 has been replaced Python for OpenVMS -Reference Manual PAGE 2-114 vms_lib.set_logical() routine >>> 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'), ... ('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, Python for OpenVMS -Reference Manual PAGE 2-115 vms_lib.set_logical() routine ... ( ('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 >>> >>> import vms_sys >>> vms_sys.getmsg (20)[0] '%SYSTEM-F-BADPARAM, bad parameter value' >>> 17-OCT-1998 ZE. ------------------------------------------------------------------------ 2.3.53 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 1 = LIB$K_CLI_LOCAL_SYM - Local symbol table 2 = LIB$K_CLI_GLOBAL_SYM - Global symbol table If omitted or None, the local symbol table is used. Examples: >>> import vms_lib >>> LIB_K_CLI_LOCAL_SYM = 1 >>> LIB_K_CLI_GLOBAL_SYM = 2 >>> vms_lib.set_symbol ('VMS_LIB_SYM_GLOBAL', 'VALUE_GLOBAL', 2) >>> vms_lib.set_symbol ('VMS_LIB_SYM_LOCAL', 'VALUE_LOCAL', 1) >>> 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_* Python for OpenVMS -Reference Manual PAGE 2-116 vms_lib.set_symbol() routine 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') Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name') >>> >>> symbol_name = 'S' * 65536 >>> vms_lib.set_symbol (symbol_name, 'VALUE_STRING') Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: symbol - string size limited to\ 65535 characters >>> >>> value_string = 'V' * 257 >>> vms_lib.set_symbol ('SYMBOL', value_string) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> >>> value_string = 'V' * 65536 >>> vms_lib.set_symbol ('SYMBOL', value_string) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: value-string - string size limited to\ 65535 characters >>> >>> # bad table type indicator >>> vms_lib.set_symbol ('SYMBOL', 'VALUE_STRING', 999) Traceback (innermost last): File "", line 1, in ? vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)') >>> >>> vms_lib.set_symbol ('SYMBOL', 'VALUE_STRING', 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: table-type-indicator must be integer or None >>> Python for OpenVMS -Reference Manual PAGE 2-117 vms_lib.set_symbol() routine >>> vms_lib.set_symbol () Traceback (innermost last): File "", line 1, in ? TypeError: function requires at least 2 arguments; 0 given >>> 16-DEC-1998 ZE. ------------------------------------------------------------------------ 2.3.54 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 GENMAN '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 GENMAN '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 GENMAN '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 Python for OpenVMS -Reference Manual PAGE 2-118 vms_lib.sub_times() routine >>> 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 >>> 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 ? TypeError: argument 1: must be long integer >>> >>> resultant_time = vms_lib.sub_times (time1, 'X') Python for OpenVMS -Reference Manual PAGE 2-119 vms_lib.sub_times() routine Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: must be long integer >>> >>> 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 integer >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 2.3.55 TRIM_FILESPEC - Fit Long File Specification into Fixed Field Format: status, new_filespec = vms_lib.trim_filespec \ (old_filespec [,width]) Returns: status The condition value that is returned from LIB$TRIM_FILESPEC when it is SS$_NORMAL or LIB$_STRTRU. All other codes result in a Python exception. new_filespec Trimmed file specification. Arguments: old_filespec File specification to be trimmed. width Maximum field width desired. If this argument is omitted, then an internal buffer of 256 bytes is defined by the interface. Examples: >>> import vms_lib >>> import vms_sys >>> old_filspec = \ ... 'NOD"USRNAM PASWD"::DEVIC:[DIR.SUB1.SUB2]NAM.TYP;123' Python for OpenVMS -Reference Manual PAGE 2-120 vms_lib.trim_filespec() routine >>> # use default width (256 bytes) >>> status, new_filespec = vms_lib.trim_filespec (old_filspec) >>> status, new_filespec (1, 'NOD"USRNAM PASWD"::DEVIC:[DIR.SUB1.SUB2]NAM.TYP;123') >>> vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> # exact length >>> len (old_filspec) 51 >>> vms_lib.trim_filespec (old_filspec, 51) (1, 'NOD"USRNAM PASWD"::DEVIC:[DIR.SUB1.SUB2]NAM.TYP;123') >>> >>> # shorter, 1 character >>> status, new_filespec = vms_lib.trim_filespec (old_filspec, 50) >>> status, new_filespec (1, 'DEVIC:[DIR.SUB1.SUB2]NAM.TYP;123') >>> >>> vms_lib.trim_filespec (old_filspec, 32) (1, 'DEVIC:[DIR.SUB1.SUB2]NAM.TYP;123') >>> vms_lib.trim_filespec (old_filspec, 31) (1, '[DIR.SUB1.SUB2]NAM.TYP;123') >>> >>> vms_lib.trim_filespec (old_filspec, 26) (1, '[DIR.SUB1.SUB2]NAM.TYP;123') >>> vms_lib.trim_filespec (old_filspec, 25) (1, 'NAM.TYP;123') >>> >>> vms_lib.trim_filespec (old_filspec, 11) (1, 'NAM.TYP;123') >>> vms_lib.trim_filespec (old_filspec, 10) (1, 'NAM.TYP') >>> >>> vms_lib.trim_filespec (old_filspec, 7) (1, 'NAM.TYP') >>> vms_lib.trim_filespec (old_filspec, 6) (1, 'NAM') >>> vms_lib.trim_filespec (old_filspec, 3) (1, 'NAM') >>> vms_lib.trim_filespec (old_filspec, 2) (1409041, 'NA') >>> vms_sys.getmsg (1409041) ('%LIB-S-STRTRU, string truncated', (0, 0, 0, 0)) >>> >>> # invalid character ---------v >>> old_filspec = \ Python for OpenVMS -Reference Manual PAGE 2-121 vms_lib.trim_filespec() routine ... 'NOD"USRNAM PASWD"::DEVIC:{DIR.SUB1.SUB2]NAM.TYP;123' >>> vms_lib.trim_filespec (old_filspec, 200) (1, 'NOD"USRNAM PASWD"::DEVIC:') >>> >>> vms_lib.trim_filespec (old_filspec, 24) (1, 'DEVIC:') >>> >>> # wildcard character --------v >>> old_filspec = \ ... 'NOD"USRNAM PASWD"::DEVIC:*DIR.SUB1.SUB2]NAM.TYP;123' >>> vms_lib.trim_filespec (old_filspec, 50) (1, 'NOD"USRNAM PASWD"::DEVIC:*DIR.SUB1.') >>> # alternate for version (';') -----^ >>> 28-OCT-1998 ZE. ------------------------------------------------------------------------ 2.3.56 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 >>> 30-SEP-1998 ZE. ------------------------------------------------------------------------ 13-AUG-1999 ZE. (vms_lib.html) Python for OpenVMS -Reference Manual PAGE 2-122 vms_mail module 2.4 vms_mail module The 'vms_mail' module provides access to some OpenVMS MAIL$ routines. No documentation is currently available. For implemented routines, see file VMS_MAIL.C. ------------------------------------------------------------------------ ------------------------------------------------------------------------ 24-MAY-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-123 vms_smg module 2.5 vms_smg module The 'vms_smg' module provides access to most of the OpenVMS SMG$ routines. Many of these functions DO NOT return a status code; they raise the exception 'vms_smg.error' when something went wrong. Functions that behave differently have it mentioned at their description. The list of implemented interface routines is based on the documentationm for OpenVMS VAX V6.1 - it might lack routines that exist in later versions and it might contain routines that do not exist in V5.5-2 and/or V6.0. Note that the shareable image SMGSHR.EXE is always linked against the Python interpreter when in the DCL environment, because command line editing uses SMG$ calls (see PYVMS_READLINE.C). Many examples use the SMG_M_WORKSTATION flag when creating a pasteboard. The reason is that the examples were directly typed in to an interactive interpreter. Having two separate 'terminals' makes testing much easier. Also, the web-browsable documentation includes screen snapshots that have been created this way. Filenames (like VMS_SMG_001.JPG) of the pictures are embedded in the text, but do not try to interpret the numbers. ------------------------------------------------------------------------ Alphabetical list of routines: - BEGIN_DISPLAY_UPDATE - Begin Batching of Display Updates - BEGIN_PASTEBOARD_UPDATE - Begin Batching of Pasteboard Updates - CHANGE_PBD_CHARACTERISTICS - Change Pasteboard Characteristics - CHANGE_RENDITION - Change Default Rendition - CHANGE_VIEWPORT - Change Viewport associated with a Virtual Display - CHANGE_VIRTUAL_DISPLAY - Change Virtual Display - CHECK_FOR_OCCLUSION - Check for Occlusion - CONTROL_MODE - Control Mode - COPY_VIRTUAL_DISPLAY - Copy a Virtual Display - CREATE_PASTEBOARD - Create a Pasteboard - CREATE_VIEWPORT - Create a Virtual Viewport - CREATE_VIRTUAL_DISPLAY - Create a Virtual Display - CREATE_VIRTUAL_KEYBOARD - Create a Virtual Keyboard - DELETE_CHARS - Delete Characters - DELETE_LINE - Delete Line - DELETE_PASTEBOARD - Delete Pasteboard Python for OpenVMS -Reference Manual PAGE 2-124 vms_smg module - DELETE_VIEWPORT - Delete a Virtual Viewport - DELETE_VIRTUAL_DISPLAY - Delete Virtual Display - DELETE_VIRTUAL_KEYBOARD - Delete Virtual Keyboard - DRAW_CHAR - Draw a Character in a Virtual Display - DRAW_LINE - Draw a horizontal or vertical line - DRAW_RECTANGLE - Draw a Rectangle - END_DISPLAY_UPDATE - End Display Update - END_PASTEBOARD_UPDATE - End Pasteboard Update - ERASE_CHARS - Erase Characters - ERASE_COLUMN - Erase Column from Display - ERASE_DISPLAY - Erase Virtual Display - ERASE_LINE - Erase Line - ERASE_PASTEBOARD - Erase Pasteboard - FIND_CURSOR_DISPLAY - Find Display that Contains the Cursor - FLUSH_BUFFER - Flush Buffer - FLUSH_DISPLAY_UPDATE - Flush Display Update - GET_CHAR_AT_PHYSICAL_CURSOR - Return Character at Cursor - GET_DISPLAY_ATTR - Get Display Attributes - GET_KEYBOARD_ATTRIBUTES - Get Keyboard Attributes - GET_PASTEBOARD_ATTRIBUTES - Get Pasteboard Attributes - GET_PASTING_INFO - Return Pasting Information - GET_VIEWPORT_CHAR - Get Characteristics of Display Viewport - HOME_CURSOR - Home Cursor - INSERT_CHARS - Insert Characters - INSERT_LINE - Insert Line - INVALIDATE_DISPLAY - Mark a Display as Invalid - KEYCODE_TO_NAME - Translate a Key Code into a Key Name - LABEL_BORDER - Label a Virtual Display Border - LIST_PASTEBOARD_ORDER - Return Pasting Information - LIST_PASTING_ORDER - Return Virtual Display Pasting Information - LOAD_VIRTUAL_DISPLAY - Load a Virtual Display from a File - MOVE_TEXT - Move Text from One Virtual Display to Another - MOVE_VIRTUAL_DISPLAY - Move Virtual Display - NAME_TO_KEYCODE - Translate a Key Name into a Key Code - PASTE_VIRTUAL_DISPLAY - Paste Virtual Display - POP_VIRTUAL_DISPLAY - Delete a Series of Virtual Displays - PRINT_PASTEBOARD - Print Pasteboard Using a Print Queue - PUT_CHARS - Write Characters to a Virtual Display - PUT_CHARS_HIGHWIDE - Write Double-Height Double-Width Characters - PUT_CHARS_MULTI - Put Text with Multiple Renditions to Display - PUT_CHARS_WIDE - Write Double-Width Characters - PUT_HELP_TEXT - Output Help Text to the Display - PUT_LINE - Write Line to Virtual Display - PUT_LINE_HIGHWIDE - Write Double-Height and Double-Width Line - PUT_LINE_MULTI - Write Line with Multiple Renditions to Display Python for OpenVMS -Reference Manual PAGE 2-125 vms_smg module - PUT_LINE_WIDE - Write Double-Width Line - PUT_STATUS_LINE - Output Line of Text to Hardware Status Line - READ_FROM_DISPLAY - Read Text from Display - READ_KEYSTROKE - Read a Single Character - READ_STRING - Read String - REMOVE_LINE - Remove a Line from a Virtual Display - REPAINT_LINE - Repaint One or More Lines on the Current Pasteboard - REPAINT_SCREEN - Repaint Current Pasteboard - REPASTE_VIRTUAL_DISPLAY - Repaste Virtual Display - RESTORE_PHYSICAL_SCREEN - Restore Physical Pasteboard - RETURN_CURSOR_POS - Return Cursor Position - RING_BELL - Ring the Terminal Bell or Buzzer - SAVE_PHYSICAL_SCREEN - Save Physical Screen - SAVE_VIRTUAL_DISPLAY - Save the Virtual Display to a File - SCROLL_DISPLAY_AREA - Scroll Display Area - SCROLL_VIEWPORT - Scroll a Display Under a Viewport - SET_CURSOR_ABS - Set Absolute Cursor Position - SET_CURSOR_MODE - Set the Cursor Mode - SET_CURSOR_REL - Move Cursor Relative to Current Position - SET_DISPLAY_SCROLL_REGION - Create Display Scrolling Region - SET_KEYPAD_MODE - Set Keypad Mode - SET_PHYSICAL_CURSOR - Set Cursor on Physical Screen - UNPASTE_VIRTUAL_DISPLAY - Remove Virtual Display ------------------------------------------------------------------------ 2.5.1 BEGIN_DISPLAY_UPDATE - Begin Batching of Display Updates Saves, or batches, all output to a virtual display until a matching call to vms_smg.end_display_update() is encountered. Format: status = vms_smg.begin_display_update (display_id) Returns: status Condition code as returned from SMG$BEGIN_DISPLAY_UDPATE. Either SS$_NORMAL or SMG$_BATWAS_ON are returned here - all other codes produce a Python exception. (The latter code is not mentioned in the documentation of OpenVMS VAX V6.1). Arguments: display_id Virtual display for which output is to be batched. Examples: >>> import vms_smg Python for OpenVMS -Reference Manual PAGE 2-126 vms_smg.begin_display_update() routine >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> status = vms_smg.put_chars (vtdpy1, 'TXT', 2, 2) >>> Screen layout, file: VMS_SMG_006.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # begin batching of virtual display 1 >>> status = vms_smg.begin_display_update (vtdpy1) >>> Python for OpenVMS -Reference Manual PAGE 2-127 vms_smg.begin_display_update() routine >>> # again write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'BAT1', 3, 3) >>> status = vms_smg.put_chars (vtdpy1, 'BAT2', 4, 4) Notice that no new output appears inside the display. >>> # end batching of virtual display 1 >>> status = vms_smg.end_display_update (vtdpy1) >>> Screen layout, file: VMS_SMG_014.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT | ! 5! | BAT1 | ! 6! | BAT2* | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Full output is now visible. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.2 BEGIN_PASTEBOARD_UPDATE - Begin Batching of Pasteboard Updates Saves, or batches, all output to a pasteboard until a matching call to vms_smg.end_pasteboard_update() is encountered. Format: vms_smg.begin_pasteboard_update (pasteboard_id) Returns: None Arguments: pasteboard_id Python for OpenVMS -Reference Manual PAGE 2-128 vms_smg.begin_pasteboard_update() routine Pasteboard for which output is to be batched. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> Notice that an empty screen as been created. >>> # start batching of the pasteboard >>> vms_smg.begin_pasteboard_update (pasteboard_id) >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> print status 1212457 >>> >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SMG-S-BATWAS_ON, batching was on >>> Notice that the screen has not changed. >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> print status Python for OpenVMS -Reference Manual PAGE 2-129 vms_smg.begin_pasteboard_update() routine 1212457 >>> Notice that the screen still has not changed. >>> # end updates >>> status = vms_smg.end_pasteboard_update (pasteboard_id) >>> Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ Notice that the virtual displays are now visible. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.3 CHANGE_PBD_CHARACTERISTICS - Change Pasteboard Characteristics Changes the characteristics associated with a pasteboard. Python for OpenVMS -Reference Manual PAGE 2-130 vms_smg.change_pbd_characteristics() routine Format: width, height, background_color = \ vms_smg.change_pbd_characteristics (pasteboard_id, \ [desired_width], [desired_height], \ [desired_background_color]) Returns: width The physical width of the pasteboard. height The physical height of the pasteboard. background_color The background color chosen or SMG_C_COLOR_UNKNOWN. Arguments: pasteboard_id The pasteboard whose characteristics are to be changed. desired_width New width for the pasteboard. desired_height New height for the pasteboard. desired_background_color Symbolic name for the desired background color. Constants like SMG_C_COLOR_BLUE are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> It is not possible to show the screen layout here. You can take a look at file VMS_SMG_012.JPG >>> # change pasteboard characteristics >>> width, height, background_color = \ vms_smg.change_pbd_characteristics (pasteboard_id, \ 20, 5, vms_smgdef.SMG_C_COLOR_BLUE) >>> >>> print width, height, background_color 20 5 3 >>> print vms_smgdef.SMG_C_COLOR_BLUE 3 Python for OpenVMS -Reference Manual PAGE 2-131 vms_smg.change_pbd_characteristics() routine >>> It is not possible to show the screen layout here. You can take a look at file VMS_SMG_013.JPG >>> # try to change the characteristics of a non-existing pasteboard >>> status = vms_smg.change_pbd_characteristics \ ... (pasteboard_id+99, 5, 5) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212964, '%SMG-F-INVPAS_ID, invalid pasteboard-id') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.4 CHANGE_RENDITION - Change Default Rendition Changes the video attributes for all or part of a virtual display. Format: status = vms_smg.change_rendition (display_id, \ start_row, start_column, \ number_of_rows, number_of_columns, \ [rendition_set], [rendition_complement]) Returns: status Condition code as returned from SMG$CHANGE_RENDITION. Either SS$_NORMAL or SMG$_NO_CHADIS are returned here - all other codes produce a Python exception. Arguments: display_id Display whoes default rendition is to be changed. start_row Starting row position to receive the new rendition. start_column Starting column position to receive the new rendition. number_of_rows Number of rows to receive the new rendition. number_of_columns Number of columns to receive the new rendition. rendition_set Attribute specifier. Bit masks like SMG_M_BLINK are in module 'vms_smgdef'. rendition_complement Python for OpenVMS -Reference Manual PAGE 2-132 vms_smg.change_rendition() routine Attribute complement specifier. There are no symbolic values available for these bits. Please see the 'OpenVMS RTL Screen Management (SMG$) Manual'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-133 vms_smg.change_rendition() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # define the new rendition set >>> rendition_set = vms_smgdef.SMG_M_REVERSE + \ ... vms_smgdef.SMG_M_UNDERLINE >>> # change the set >>> status = vms_smg.change_rendition \ ... (vtdpy1, 2, 3, 2, 3, rendition_set) >>> Screen layout. file: VMS_SMG_011.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |AB$$$FGHIJ| ! 5! |KL$$$PQRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ It is not possible to display reverse underlined characters here, so the area is just marked with $ signs. You can also take a look at file VMS_SMG_011.JPG >>> # try to change the rendition of a non-existing display >>> status = vms_smg.change_rendition (vtdpy1+99, 1, 2, 3, 4) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') Python for OpenVMS -Reference Manual PAGE 2-134 vms_smg.change_rendition() routine >>> >>> # use a bad value for the rendition_complement >>> status = vms_smg.change_rendition (vtdpy1, 1, 2, 3, 4, 3, 99) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212940, '%SMG-F-INVARG, invalid argument') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.5 CHANGE_VIEWPORT - Change Viewport associated with a Virtual Display Change the size of an existing viewport in a virtual display. Format: vms_smg.change_viewport (display_id, \ [viewport_row_start], [viewport_column_start], \ [viewport_number_rows], [viewport_number_columns]) Returns: None Arguments: display_id Display to which the viewport is associated. viewport_row_start New row number in the virtual display that will become row 1 in the viewport. viewport_column_start New column number in the virtual display that will become column 1 in the viewport. viewport_number_rows New number of rows in the viewport. viewport_number_columns New number of columns in the viewport. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ Python for OpenVMS -Reference Manual PAGE 2-135 vms_smg.change_viewport() routine ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> >>> # create a viewport >>> status = vms_smg.create_viewport (vtdpy1, 2, 3, 4, 5) >>> The examples section of vms_smg.create_viewport() shows that this has no immediate effect if the virtual display is already pasted. It also shows the contents of the whole virtual display. >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_009.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |CDEFG| ! 4! |MNOPQ| ! 5! |cdefg| ! 6! |mnopq| ! 7! +-----+ * ! 8! ! V V 24! ! +________________________) _+ Python for OpenVMS -Reference Manual PAGE 2-136 vms_smg.change_viewport() routine >>> # change the viewport >>> vms_smg.change_viewport (vtdpy1, 1, 2, 3, 4) >>> Screen layout, file: VMS_SMG_010.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----+ ! 3! |2345| ! 4! |BCDE| ! 5! |LMNO| ! 6! +----+ ! 7! * ! 8! ! V V 24! ! +________________________) _+ >>> # errors >>> vms_smg.change_viewport (vtdpy1, 0, 0, 9, 9) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212972, '%SMG-F-INVROW, invalid row') >>> >>> vms_smg.change_viewport (vtdpy1, 1, 0, 9, 9) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212948, '%SMG-F-INVCOL, invalid column') >>> >>> # try to change the viewport of a non-existing display >>> vms_smg.change_viewport (vtdpy1+99, 1, 2, 3, 4) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> >>> # delete the viewport for the next demo >>> vms_smg.delete_viewport (vtdpy1) Notice that the virtual display has just been un-pasted. This can be checked with: vms_smg.get_pasting_info() >>> # try to change a non-existing viewport >>> vms_smg.change_viewport (vtdpy1, 1, 2, 3, 4) Traceback (innermost last): File "", line 1, in ? Python for OpenVMS -Reference Manual PAGE 2-137 vms_smg.change_viewport() routine vms_smg.error: (1213332, '%SMG-F-NO_WINASSOC, no viewport has been\ associated with the display') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.6 CHANGE_VIRTUAL_DISPLAY - Change Virtual Display Change characteristics (dimensions, border, video rendition) of a virtual display. Use vms_smg.repaste_virtual_display() to change the location and pasting order of the display within the pasteboard. Use vms_smg.move_virtual_display() to change the location, but keep the pasting order. Format: vms_smg.change_virtual_display (display_id, \ [number_of_rows], [number_of_columns], \ [display_attributes], [video_attributes], \ [character_set]) Returns: None Arguments: display_id Virtual display to be changed. number_of_rows The new number of rows. number_of_columns The new number of columns. display_attributes Bit masks like SMG_M_BORDER for the attributes of the virtual display are in module 'vms_smgdef'. video_attributes The new default rendition set for all output to this virtual display. Bit masks like SMG_M_BLINK are in module 'vms_smgdef'. character_set The new default character set for all text in this virtual display. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG Python for OpenVMS -Reference Manual PAGE 2-138 vms_smg.change_virtual_display() routine >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # CHANGE the virtual display >>> vms_smg.change_virtual_display \ ... (display_id, 7, 5, vms_smgdef.SMG_M_BLOCK_BORDER) >>> Python for OpenVMS -Reference Manual PAGE 2-139 vms_smg.change_virtual_display() routine Screen layout, file: VMS_SMG_002.JPG 1 1 8 1234567890123456 0 +________________) _+ 1! ! 2! BBBBBBB ! 3! B* B ! 4! B B ! 5! B B ! 6! B B ! 7! B B ! 8! B B ! 9! B B ! 10! BBBBBBB ! 11! ! V V 24! ! +________________) _+ legend B = block border Notice that the display is at the same location, but its dimensions have changed and it now has a block border. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.7 CHECK_FOR_OCCLUSION - Check for Occlusion Checks whether a virtual display is covered (occluded) by another virtual display. Format: status, occlusion_state = \ vms_smg.check_for_occlusion (display_id, pasteboard_id) Returns: status Condition code as returned from SMG$CHECK_FOR_OCCLUSION. Either SS$_NORMAL or SMG$_NOTPASTED are returned here - all other codes produce a Python exception. occlusion_state Returns 1 if the virtual display is occluded, 0 if not. Arguments: display_id Python for OpenVMS -Reference Manual PAGE 2-140 vms_smg.check_for_occlusion() routine Virtual display to be checked. pasteboard_id Pasteboard to be checked. Examples: >>> import vms_smg >>> import vms_smgdef >>> import vms_sys >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # check if display 1 is occluded >>> status, occlusion_state = \ ... vms_smg.check_for_occlusion (vtdpy1, pasteboard_id) >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> print occlusion_state 0 >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Python for OpenVMS -Reference Manual PAGE 2-141 vms_smg.check_for_occlusion() routine Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # again, check if display 1 is occluded >>> status, occlusion_state = \ ... vms_smg.check_for_occlusion (vtdpy1, pasteboard_id) >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> print occlusion_state 1 >>> >>> # unpaste display 1 >>> status = vms_smg.unpaste_virtual_display (vtdpy1, pasteboard_id) >>> >>> # again, check if display 1 is occluded >>> status, occlusion_state = \ ... vms_smg.check_for_occlusion (vtdpy1, pasteboard_id) >>> >>> print vms_sys.getmsg (status)[0] %SMG-F-NOTPASTED, given display is not pasted to given pasteboard >>> print occlusion_state 0 >>> Python for OpenVMS -Reference Manual PAGE 2-142 vms_smg.check_for_occlusion() routine >>> # bad pasteboard ID >>> status, occlusion_state = \ ... vms_smg.check_for_occlusion (vtdpy1, pasteboard_id+99) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212964, '%SMG-F-INVPAS_ID, invalid pasteboard-id') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.8 CONTROL_MODE - Control mode Controls the pasteboard's mode. Format: old_mode = vms_smg.control_mode \ (pasteboard_id, [new_mode], [buffer_size]) Returns: old_mode The old settings before vms_smg.control_mode() was called. Arguments: pasteboard_id The pasteboard to be changed. new_mode The new control settings to be used. Bit mask values like SMG_M_CLEAR_SCREEN are in module 'vms_smgdef'. buffer_size The buffer size in bytes. See the 'OpenVMS RTL Screen Management (SMG$) Manual' for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a pasteboard >>> # note: unlike many other examples this one does not use >>> # a separate DECterm. >>> # You should put these commands in a script for testing. >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard (None) >>> >>> # create a virtual display Python for OpenVMS -Reference Manual PAGE 2-143 vms_smg.control_mode() routine >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> old_mode = vms_smg.control_mode (pasteboard_id) >>> print old_mode 18 >>> print vms_smgdef.SMG_M_MINUPD 2 >>> print vms_smgdef.SMG_M_PROTECT 16 >>> >>> # if Python is terminated here without using >>> # vms_smg.delete_pasteboard, SMG will not >>> # clear the screen >>> >>> >>> new_mode = old_mode | vms_smgdef.SMG_M_CLEAR_SCREEN >>> old_mode = vms_smg.control_mode (pasteboard_id, new_mode) >>> >>> # if Python is terminated here without using >>> # vms_smg.delete_pasteboard, SMG will Python for OpenVMS -Reference Manual PAGE 2-144 vms_smg.control_mode() routine >>> # clear the screen 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.9 COPY_VIRTUAL_DISPLAY - Copy Virtual Display Creates a copy from an existing virtual display. Format: new_display_id = vms_smg.copy_virtual_display (current_display_id) Returns: new_display_id Id of the newly created display. Arguments: current_display_id Display identifier of the virtual display to be replicated. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> status = vms_smg.put_chars (vtdpy1, 'TXT', 2, 2) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Python for OpenVMS -Reference Manual PAGE 2-145 vms_smg.copy_virtual_display() routine Screen layout, file: VMS_SMG_006.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # copy virtual display 1 to virtual display 2 >>> vtdpy2 = vms_smg.copy_virtual_display (vtdpy1) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 6, 8, None) >>> Python for OpenVMS -Reference Manual PAGE 2-146 vms_smg.copy_virtual_display() routine Screen layout, file: VMS_SMG_007.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT | ! 5! | +----------+ ! 6! | |V1 | ! 7! | | TXT* | ! 8! +--| | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ >>> # try to copy a non-existing display >>> vtdpy2 = vms_smg.copy_virtual_display (vtdpy1+99) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.10 CREATE_PASTEBOARD - Create a Pasteboard Create a pasteboard and returns its assigned pasteboard identifier. Format: status, pasteboard_id, number_of_pasteboard_rows, \ number_of_pasteboard_columns, type_of_terminal, device_name \ = vms_smg.create_pasteboard ([output_device], [flags]) Returns: status The condition value as returned by SMG$CREATE_PASTEBOARD. Any code other than SS$_NORMAL and SMG$_PASALREXI results in a Python exception. pasteboard_id The identifier of the newly created pasteboard. number_of_pasteboard_rows Python for OpenVMS -Reference Manual PAGE 2-147 vms_smg.create_pasteboard() routine The number of rows on the device specified in the output_device argument. number_of_pasteboard_columns The number of columns on the device specified in the output_device argument. type_of_terminal The SMG$ internal device type to which the output associated with this pasteboard will be written. Constants like SMG_K_UNKNOWN are defined in module 'vms_smgdef'. device_name The device name of the device on which the output associated with this pasteboard is written. See the OpenVMS documentation for more details. Arguments: output_device The file specification or logical name to which the output associated with this pasteboard will be written. flags Specifies the attributes to be used in the pasteboard. Bit mask values like SMG_M_KEEP_CONTENTS are defined in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, \ ... pasteboard_id, \ ... number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, \ ... type_of_terminal, \ ... device_name \ ... = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> Warning! If you re-execute this command another screen is created! >>> print "status......................:", status status......................: 1 >>> print "pasteboard_id...............:", pasteboard_id pasteboard_id...............: 0 >>> print "number_of_pasteboard_rows...:", number_of_pasteboard_rows number_of_pasteboard_rows...: 24 >>> print "number_of_pasteboard_columns:", number_of_pasteboard_columns number_of_pasteboard_columns: 80 >>> print "type_of_terminal............:", type_of_terminal type_of_terminal............: 6 >>> print "device_name.................:", device_name device_name.................: _FTA20: Python for OpenVMS -Reference Manual PAGE 2-148 vms_smg.create_pasteboard() routine >>> ---------------------------------------- >>> # create a pasteboard on the current screen >>> # leaving off SMG_M_KEEP_CONTENTS will erase the screen >>> status, \ ... pasteboard_id, \ ... number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, \ ... type_of_terminal, \ ... device_name \ ... = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_KEEP_CONTENTS) >>> >>> print "status......................:", status status......................: 1 >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> print "pasteboard_id...............:", pasteboard_id pasteboard_id...............: 0 >>> print "number_of_pasteboard_rows...:", number_of_pasteboard_rows number_of_pasteboard_rows...: 24 >>> print "number_of_pasteboard_columns:", number_of_pasteboard_columns number_of_pasteboard_columns: 80 >>> print "type_of_terminal............:", type_of_terminal type_of_terminal............: 6 >>> print "device_name.................:", device_name device_name.................: SYS$OUTPUT >>> Note: if you re-execute this command a different status is returned: >>> print "status......................:", status status......................: 1212465 >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SMG-S-PASALREXI, pasteboard already exists for this device >>> ---------------------------------------- >>> # create a pasteboard on a file >>> vms_smg.create_pasteboard ('FILENAME.TMP') (1, 0, 66, 132, 0, 'FILENAME.TMP') >>> Note: if you re-execute this command another file is created. $! this logical name defines the page size $ DEFINE SYS$LP_LINES 72 [...] >>> vms_smg.create_pasteboard ('FILENAME.TMP') Python for OpenVMS -Reference Manual PAGE 2-149 vms_smg.create_pasteboard() routine (1, 0, 72, 132, 0, 'FILENAME.TMP') >>> $ directory FILENAME.TMP Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] FILENAME.TMP;2 FILENAME.TMP;1 Total of 2 files. $ see also vms_lib.lp_lines() ---------------------------------------- >>> vms_smg.create_pasteboard ('*BADNAME*') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (100164, '%RMS-F-WLD, invalid wildcard operation') >>> >>> vms_smg.create_pasteboard (1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, int found >>> >>> vms_smg.create_pasteboard ('') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1409644, '%LIB-F-BADBLOSIZ, bad block size') >>> >>> vms_smg.create_pasteboard (None, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: flags - must be integer or None >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.11 CREATE_VIEWPORT - Create a Virtual Viewport Associate a viewport with a virtual display. Format: status = vms_smg.create_viewport (display_id, \ viewport_row_start, viewport_column_start, \ viewport_number_rows, viewport_number_columns) Python for OpenVMS -Reference Manual PAGE 2-150 vms_smg.create_viewport() routine Returns: status Condition code as returned from SMG$CREATE_VIEWPORT. Either SS$_NORMAL or SMG$_NOTPASTED are returned here - all other codes produce a Python exception. Arguments: display_id Display to which the viewport is associated. viewport_row_start Row number in the virtual display that will become row 1 in the viewport. viewport_column_start Column number in the virtual display that will become column 1 in the viewport. viewport_number_rows Number of rows in the viewport. viewport_number_columns Number of columns in the viewport. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Python for OpenVMS -Reference Manual PAGE 2-151 vms_smg.create_viewport() routine Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # create a viewport >>> status = vms_smg.create_viewport (vtdpy1, 2, 3, 4, 5) >>> Notice that the effect is not immediately visible. >>> # repaste virtual display >>> vms_smg.repaste_virtual_display (vtdpy1, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_009.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |CDEFG| ! 4! |MNOPQ| ! 5! |cdefg| ! 6! |mnopq| ! 7! +-----+ * ! 8! ! V V 24! ! +________________________) _+ Python for OpenVMS -Reference Manual PAGE 2-152 vms_smg.create_viewport() routine >>> # try to associate a viewport to a non-existing display >>> status = vms_smg.create_viewport (vtdpy1+99, 1, 2, 3, 4) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.12 CREATE_VIRTUAL_DISPLAY - Create a Virtual Display Create a virtual display and return its assigned display identifier. Format: status, display_id = vms_smg.create_virtual_display \ (number_of_rows, number_of_columns, \ [display_attributes], [video_attributes], [character_set]) Returns: status The condition value as returned by SMG$CREATE_VIRTUAL_DISPLAY. Any code other than SS$_NORMAL and SMG$_PASALREXI results in a Python exception. display_id The identifier of the newly created display. Arguments: number_of_rows Height of the display. number_of_columns Width of the display. display_attributes Default display attributes. Bit mask values like SMG_M_BORDER are defined in module 'vms_smgdef'. video_attributes The default rendition to be applied to all output in this virtual display unless overridden by a call. Bit mask values like SMG_M_BLINK are defined in module 'vms_smgdef'. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg Python for OpenVMS -Reference Manual PAGE 2-153 vms_smg.create_virtual_display() routine >>> import vms_smgdef >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> print "status.....:", status status.....: 1 >>> print "display_id.:", display_id display_id.: 3131200 >>> ---------------------------------------- The display is not immediately visible. See the examples section of the vms_smg.paste_virtual_display() routine for a complete working demonstration. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.13 CREATE_VIRTUAL_KEYBOARD - Create a Virtual Keyboard Create a virtual keyboard and return its assigned keyboard identifier. Format: keyboard_id, resultant_filespec = \ vms_smg.create_virtual_keyboard ([input_device], [default_filespec], [recall_size]) Returns: keyboard_id The keyboard identifier of the newly created virtual keyboard. resultant_filespec The fully expanded file specification of the file used Arguments: input_device The file specification or logical name of the file or terminal to be used for this virtual keyboard. default_filespec The default file specification. default_filespec might be used to specify a default device and directory, leaving the input_device argument to supply the file name and type. recall_size Number of input lines to be saved for later recall. Default = 20 lines. Python for OpenVMS -Reference Manual PAGE 2-154 vms_smg.create_virtual_keyboard() routine Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual keyboard - >>> # use the device name from CREATE_PASTEBOARD >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard (device_name) >>> >>> print "device_name........:", device_name device_name........: _FTA19: >>> print "keyboard_id........:", keyboard_id keyboard_id........: 3133080 >>> print "resultant_filespec.:", resultant_filespec resultant_filespec.: _FTA19:[PYTHON.PYTHON-1_5_2.VMS].; >>> ---------------------------------------- >>> # use a non-existing device name >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard ('NOSUCHDEV:') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (99524, '%RMS-F-DEV, error in device name or\ inappropriate device type for operation') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.14 DELETE_CHARS - Delete Characters Delete characters in a virtual display. Format: status = vms_smg.delete_chars (display_id, \ number_of_characters, start_row, start_column) Returns: status Python for OpenVMS -Reference Manual PAGE 2-155 vms_smg.delete_chars() routine Condition code as returned from SMG$DELETE_CHARS. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Virtual display in which the characters are to be deleted. number_of_characters The number of characters to be deleted. start_row The row position at which to start the deletion. start_column The column position at which to start the deletion. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (display_id, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (display_id, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (display_id, 'Line3Line3Line3', 3, 3) >>> Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'n' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-156 vms_smg.delete_chars() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # delete some characters >>> status = vms_smg.delete_chars (display_id, 3, 2, 3) >>> Screen layout, file: VMS_SMG_016.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and '2' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | L*Line | ! 5! | Line3Lin| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-157 vms_smg.delete_line() routine 2.5.15 DELETE_LINE - Delete Line Deletes lines from a virtual display. Format: status = vms_smg.delete_line (display_id, \ start_row, [number_of_rows]) Returns: status Condition code as returned from SMG$DELETE_LINE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Virtual display in which the line(s) are to be deleted. start_row The row position at which to start the deletion. number_of_rows The number of rows to be deleted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (display_id, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (display_id, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (display_id, 'Line3Line3Line3', 3, 3) >>> Python for OpenVMS -Reference Manual PAGE 2-158 vms_smg.delete_line() routine Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'n' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # delete a line >>> status = vms_smg.delete_line (display_id, 2, 1) >>> Screen layout, file: VMS_SMG_017.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-159 vms_smg.delete_line() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! |* Line3Lin| ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.16 DELETE_PASTEBOARD - Delete Pasteboard Format: vms_smg.delete_pasteboard (pasteboard_id) Returns: None Arguments: pasteboard_id Pasteboard to be deleted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> Python for OpenVMS -Reference Manual PAGE 2-160 vms_smg.delete_pasteboard() routine >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> The result can be seen in the examples section of vms_smg.paste_virtual_display(). >>> # delete the pasteboard >>> vms_smg.delete_pasteboard (pasteboard_id) >>> The DECwindows terminal screen is deleted. If everything is running interactively within the same terminal session, the screen is cleared and the Python prompt (>>>) is shown in the upper left corner of the screen. >>> # trying to delete a deleted pasteboard is an error >>> vms_smg.delete_pasteboard (pasteboard_id) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212964, '%SMG-F-INVPAS_ID, invalid pasteboard-id') >>> >>> # the virtual display that was pasted does still exist >>> vms_smg.delete_virtual_display (display_id) >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.17 DELETE_VIEWPORT - Delete a Viewport Deletes the specified viewport from any pasteboards to which it is pasted. Format: vms_smg.delete_viewport (display_id) Returns: None Arguments: display_id Display to which the viewport is associated. Examples: Python for OpenVMS -Reference Manual PAGE 2-161 vms_smg.delete_viewport() routine >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> >>> # create a viewport >>> status = vms_smg.create_viewport (vtdpy1, 2, 3, 4, 5) >>> The examples section of vms_smg.create_viewport() shows that this has no immediate effect if the virtual display is already pasted. It also shows the contents of the whole virtual display. >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_009.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-162 vms_smg.delete_viewport() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |CDEFG| ! 4! |MNOPQ| ! 5! |cdefg| ! 6! |mnopq| ! 7! +-----+ * ! 8! ! V V 24! ! +________________________) _+ >>> # delete the viewport >>> vms_smg.delete_viewport (vtdpy1) >>> >>> # The display is unpasted and the screen is empty. >>> # it is not possible to delete a deleted viewport >>> vms_smg.delete_viewport (vtdpy1) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1213332, '%SMG-F-NO_WINASSOC, no viewport has been\ associated with the display') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.18 DELETE_VIRTUAL_DISPLAY - Delete Virtual Display Format: vms_smg.delete_virtual_display (display_id) Returns: None Arguments: display_id Virtual display to be deleted. Examples: >>> import vms_smg >>> import vms_smgdef Python for OpenVMS -Reference Manual PAGE 2-163 vms_smg.delete_virtual_display() routine >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> The result can be seen in the examples section of vms_smg.paste_virtual_display(). >>> # delete this display >>> vms_smg.delete_virtual_display (display_id) >>> The screen is empty, again. >>> # trying to delete a deleted virtual display is an error >>> vms_smg.delete_virtual_display (display_id) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.19 DELETE_VIRTUAL_KEYBOARD - Delete Virtual Keyboard Format: vms_smg.delete_virtual_keyboard (keyboard_id) Returns: None Arguments: keyboard_id Identifier of the virtual keyboard to be deleted. Python for OpenVMS -Reference Manual PAGE 2-164 vms_smg.delete_virtual_keyboard() routine Examples: >>> import vms_smg >>> # create a virtual keyboard - >>> # use default input >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard ('SYS$INPUT:') >>> >>> print "keyboard_id........:", keyboard_id keyboard_id........: 3131704 >>> print "resultant_filespec.:", resultant_filespec resultant_filespec.: SYS$INPUT:.; >>> >>> # delete the virtual keyboard >>> vms_smg.delete_virtual_keyboard (keyboard_id) >>> ---------------------------------------- >>> # try to delete a non-existing virtual keyboard >>> vms_smg.delete_virtual_keyboard (keyboard_id+99) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1213004, '%SMG-F-INVKBD_ID, invalid keyboard-id') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.20 DRAW_CHAR - Draw a Character in a Virtual Display Format: vms_smg.draw_char (display_id, flags, \ [row], [column], \ [rendition_set], [rendition_complement]) Returns: None Arguments: display_id Virtual Display on which to draw the character. flags Bit mask indicating the character to be drawn. Values like SMG_M_UP are in module 'vms_smgdef'. row Python for OpenVMS -Reference Manual PAGE 2-165 vms_smg.draw_char() routine Row number at which to draw the character. If omitted, the position of the current virtual cursor is used. column Column number at which to draw the character. If omitted, the position of the current virtual cursor is used. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # draw on virtual display >>> # -- upper left corner >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_DOWN, 1, 1) >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_DOWN, 2, 2) >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_RIGHT, 2, 2) >>> >>> # -- horizontal line >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_RIGHT, 2, 3) >>> >>> # upper right corner >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_DOWN, 2, 4) >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_LEFT, 2, 4) >>> >>> # left vertical line >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_UP, 3, 2) >>> >>> # right vertical line >>> vms_smg.draw_char (vtdpy1, vms_smgdef.SMG_M_UP, 3, 4) >>> >>> # diamond Python for OpenVMS -Reference Manual PAGE 2-166 vms_smg.draw_char() routine >>> vms_smg.draw_char (vtdpy1, 0, 3, 3) >>> Screen layout, file: VMS_SMG_018.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and vertical bar(|) X = diamond character V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | ___ | ! 5! | |X| | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.21 DRAW_LINE - Draw a horizontal or vertical line Format: vms_smg.draw_line (display_id, start_row, start_column, \ end_row, end_column, \ [rendition_set], [rendition_complement]) Returns: None Arguments: display_id Virtual Display on which to draw the line. start_row Row number at which to begin drawing the line. Python for OpenVMS -Reference Manual PAGE 2-167 vms_smg.draw_line() routine start_column Column number at which to begin drawing the line. end_row Row number at which the line ends. end_column Column number at which the line ends. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # draw on virtual display >>> vms_smg.draw_line (vtdpy1, 2, 2, 2, 7) >>> vms_smg.draw_line (vtdpy1, 4, 2, 4, 8) >>> vms_smg.draw_line (vtdpy1, 3, 4, 5, 4) >>> vms_smg.draw_line (vtdpy1, 4, 6, 5, 6) >>> Screen layout, file: VMS_SMG_019.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-168 vms_smg.draw_line() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | ------ | ! 5! | | | ! 6! | --+---- | ! 7! | | | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # diagonal lines are not allowed >>> vms_smg.draw_line (vtdpy1, 4, 6, 5, 7) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1213084, '%SMG-F-DIALINNOT, diagonal line not allowed') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.22 DRAW_RECTANGLE - Draw a Rectangle Format: vms_smg.draw_rectangle (display_id, start_row, start_column, \ end_row, end_column, \ [rendition_set], [rendition_complement]) Returns: None Arguments: display_id Virtual Display on which to draw the rectangle. start_row The row number of the top left-hand corner of the rectangle. start_column The column number of the top left-hand corner of the rectangle. end_row The row number of the bottom right-hand corner of the rectangle. end_column Python for OpenVMS -Reference Manual PAGE 2-169 vms_smg.draw_rectangle() routine The column number of the bottom right-hand corner of the rectangle. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # draw on virtual display >>> vms_smg.draw_rectangle (vtdpy1, 1, 1, 4, 4) >>> vms_smg.draw_rectangle (vtdpy1, 2, 2, 4, 5) >>> Screen layout, file: VMS_SMG_020.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position, also corner character V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-170 vms_smg.draw_rectangle() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |*--+ | ! 4! ||+-++ | ! 5! ||| || | ! 6! |++-++ | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.23 END_DISPLAY_UPDATE - End Display Update Ends update batching for a virtual display. Format: status = vms_smg.end_display_update (display_id) Returns: status Condition code as returned from SMG$END_DISPLAY_UPDATE. Either SS$_NORMAL, SMG$_BATWASOFF or SMG$_BATSTIPRO are returned here - all other codes produce a Python exception. Arguments: display_id The virtual display on which the batch count is to be decremented. Examples: See the examples section of the vms_smg.begin_display_update() routine. 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-171 vms_smg.end_pasteboard_update() routine 2.5.24 END_PASTEBOARD_UPDATE - End Pasteboard Update Ends update batching for a pasteboard. Format: status = vms_smg.end_pasteboard_update (pasteboard_id) Returns: status Condition code as returned from SMG$END_PASTEBOARD_UPDATE. Either SS$_NORMAL, SMG$_BATWASOFF or SMG$_BATSTIPRO are returned here - all other codes produce a Python exception. Arguments: pasteboard_id The pasteboard on which the batch count is to be decremented. Examples: See the examples section of the vms_smg.begin_pasteboard_update() routine. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.25 ERASE_CHARS - Erase Characters Erase Characters in a virtual display by replacing them with blanks. Format: vms_smg.erase_chars (display_id, number_of_characters, \ start_row, start_column) Returns: None Arguments: display_id Virtual Display from which to erase the characters. number_of_characters The number of characters to be replaced with blanks. start_row Row number at which to start erasing the characters. column Column number at which to start erasing the characters. Python for OpenVMS -Reference Manual PAGE 2-172 vms_smg.erase_chars() routine Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-173 vms_smg.erase_chars() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # erase some characters >>> vms_smg.erase_chars (vtdpy1, 2, 2, 2) >>> vms_smg.erase_chars (vtdpy1, 3, 4, 3) >>> Screen layout, file: VMS_SMG_021.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |A DEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |ab* fghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-174 vms_smg.erase_column() routine 2.5.26 ERASE_COLUMN - Erase Column from Display Erase a specific portion of the virtual display. Format: vms_smg.erase_column (display_id, [start_row], \ [column_number], [end_row]) Returns: None Arguments: display_id Virtual display from which to erase the column. start_row Line number at which the erase operation begins. column Column number at which the erase operation begins. end_row Line number at which the erase operation ends. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Python for OpenVMS -Reference Manual PAGE 2-175 vms_smg.erase_column() routine Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # erase columns >>> vms_smg.erase_column (vtdpy1, 1, 2, 2) >>> vms_smg.erase_column (vtdpy1, 3, 5, 5) >>> Screen layout, file: VMS_SMG_022.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + blank V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-176 vms_smg.erase_column() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1 34567890| ! 4! |A CDEFGHIJ| ! 5! |KLMN*PQRST| ! 6! |abcd fghij| ! 7! |klmn pqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.27 ERASE_DISPLAY - Erase Virtual Display Erase all or part of a virtual display by replacing text with blanks. Format: vms_smg.erase_display (display_id, \ [start_row], [start_column], \ [end_row], [end_column]) Returns: None Arguments: display_id Virtual display from which to erase text. start_row Line number at which the erase operation begins. start_column Column number at which the erase operation begins. end_row Line number at which the erase operation ends. end_column Column number at which the erase operation ends. Examples: >>> import vms_smg >>> import vms_smgdef Python for OpenVMS -Reference Manual PAGE 2-177 vms_smg.erase_display() routine >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # erase from virtual display >>> vms_smg.erase_display (vtdpy1, 2, 2, 3, 6) Python for OpenVMS -Reference Manual PAGE 2-178 vms_smg.erase_display() routine >>> Screen layout, file: VMS_SMG_023.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + blank V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |A* | ! 5! | QRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # erase the whole display >>> vms_smg.erase_display (vtdpy1, None, None) >>> The virtual display is empty, the cursor is positioned at the upper left-most corner. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.28 ERASE_LINE - Erase Line Erase all or part of a line in a virtual display. Format: vms_smg.erase_line (display_id, [start_row], [start_column]) Returns: None Arguments: Python for OpenVMS -Reference Manual PAGE 2-179 vms_smg.erase_line() routine display_id Virtual display from which to erase text. start_row Line number at which the erase operation begins. start_column Column number at which the erase operation (to the end of the line) begins. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-180 vms_smg.erase_line() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # erase lines from virtual display >>> vms_smg.erase_line (vtdpy1, 2, 2) >>> vms_smg.erase_line (vtdpy1, 4, 5) >>> Screen layout, file: VMS_SMG_024.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + blank V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |A | ! 5! |KLMNOPQRST| ! 6! |abcd* | ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-181 vms_smg.erase_pasteboard() routine 2.5.29 ERASE_PASTEBOARD - Erase Pasteboard Erase the contents of a pasteboard. Format: status = vms_smg.erase_pasteboard (pasteboard_id) Returns: status Condition code as returned from SMG$ERASE_PASTEBOARD. Either SS$_NORMAL or SMG$_BATWAS_ON are returned here - all other codes produce a Python exception. Arguments: pasteboard_id The pasteboard to be erased. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Python for OpenVMS -Reference Manual PAGE 2-182 vms_smg.erase_pasteboard() routine Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # erase the pasteboard >>> status = vms_smg.erase_pasteboard (pasteboard_id) >>> print status 1 >>> The entire screen is blank and the curser is in the upper left corner. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.30 FIND_CURSOR_DISPLAY - Find Display that Contains the Cursor Return the identifier of the most recently pasted virtual display that contains the physical cursor. Format: display_id = vms_smg.find_cursor_display (pasteboard_id, \ [pasteboard_row], [pasteboard_column]) Returns: display_id The identifier in which the physical cursor was found. Python for OpenVMS -Reference Manual PAGE 2-183 vms_smg.find_cursor_display() routine Arguments: pasteboard_id The pasteboard in which the physical cursor is to be found. pasteboard_row The row position at which to begin the search for the physical cursor pasteboard_column The column position at which to begin the search for the physical cursor Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Python for OpenVMS -Reference Manual PAGE 2-184 vms_smg.find_cursor_display() routine Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # check positions ... >>> display_id = vms_smg.find_cursor_display (pasteboard_id, 3, 5) >>> print display_id, vtdpy1 2962744 2962744 >>> >>> display_id = vms_smg.find_cursor_display (pasteboard_id, 5, 7) >>> print display_id, vtdpy2 2963240 2963240 >>> >>> # no virtual display at this position >>> display_id = vms_smg.find_cursor_display (pasteboard_id, 1, 3) >>> print display_id 0 >>> >>> # invalid position >>> display_id = vms_smg.find_cursor_display (pasteboard_id, 99, 1) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212972, '%SMG-F-INVROW, invalid row') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-185 vms_smg.flush_buffer() routine 2.5.31 FLUSH_BUFFER - Flush Buffer Flushes all buffered output to the terminal. Format: None = vms_smg.flush_buffer (pasteboard_id) Returns: None Arguments: pasteboard_id The pasteboard to be flushed. Examples: It is unclear how to make a visible demonstration. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.32 FLUSH_DISPLAY_UPDATE - Flush Display Update Flushes any update batching to the screen and leaves the update batching in effect. See also vms_smg.end_display_update(). Format: status = vms_smg.flush_display_update (display_id) Returns: status Condition code as returned from SMG$FLUSH_DISPLAY_UPDATE. Either SS$_NORMAL or SMG$_BATWAS_ON are returned here - all other codes produce a Python exception. (The latter code is not mentioned in the documentation of OpenVMS VAX V6.1). Arguments: display_id Virtual display for which output is to be flushed. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG Python for OpenVMS -Reference Manual PAGE 2-186 vms_smg.flush_display_update() routine >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> status = vms_smg.put_chars (vtdpy1, 'TXT', 2, 2) >>> Screen layout, file: VMS_SMG_006.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # begin batching of virtual display 1 >>> status = vms_smg.begin_display_update (vtdpy1) >>> >>> # again write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'BAT1', 3, 3) Python for OpenVMS -Reference Manual PAGE 2-187 vms_smg.flush_display_update() routine >>> Notice that no new output appears inside the display. >>> # Flush the output >>> status = vms_smg.flush_display_update (vtdpy1) >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> "BAT1" is now visible. >>> # again write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'BAT2', 4, 4) >>> >>> # end batching of virtual display 1 >>> status = vms_smg.end_display_update (vtdpy1) >>> "BAT2" is now visible: Screen layout, file: VMS_SMG_014.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT | ! 5! | BAT1 | ! 6! | BAT2* | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # it makes no sense to flush when batching is off >>> status = vms_smg.flush_display_update (vtdpy1) >>> >>> print vms_sys.getmsg (status)[0] %SMG-S-BATWASOFF, batching was off >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-188 vms_smg.get_char_at_physical_cursor() routine 2.5.33 VMS_SMG_GET_CHAR_AT_PHYSICAL_CURSOR - Return Character at Cursor Returns the character at the current physical cursor position. Format: character_code = vms_smg.get_char_at_physical_cursor (pasteboard_id) Returns: character_code The character's ASCII code. Arguments: pasteboard_id The pasteboard from which to retrieve the character. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> status = vms_smg.put_chars (vtdpy1, 'TXT', 2, 2) >>> Python for OpenVMS -Reference Manual PAGE 2-189 vms_smg.get_char_at_physical_cursor() routine Screen layout, file: VMS_SMG_006.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # move cursor within the virtual display (above '1') >>> vms_smg.set_cursor_abs (vtdpy1, 1, 2) >>> >>> character_code = vms_smg.get_char_at_physical_cursor (pasteboard_id) >>> print character_code, chr(character_code) 49 1 >>> # move cursor within the virtual display (above 'X') >>> vms_smg.set_cursor_abs (vtdpy1, 2, 3) >>> >>> character_code = vms_smg.get_char_at_physical_cursor (pasteboard_id) >>> print character_code, chr(character_code) 88 X >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.34 VMS_SMG_GET_DISPLAY_ATTR - Return Character at Cursor Returns the attributes associated with a virtual display. Format: height, width, display_attributes, video_attributes, \ character_set, flags = vms_smg.get_display_attr (display_id) Python for OpenVMS -Reference Manual PAGE 2-190 vms_smg.get_display_attr() routine Returns: height The number of rows in the display. width The number of columns in the display. display_attributes The current default display attributes. Bit masks like SMG_M_BORDER are in module 'vms_smgdef'. video_attributes The current default video attributes. Bit masks like SMG_M_BLINK are in module 'vms_smgdef'. character_set The default character set for all text in this virtual display. Valid values SMG_C_ASCII and SMG_C_SPEC_GRAPHICS are in module 'vms_smgdef'. flags Bit mask specifying attributes of the specified display. Bit masks like SMG_M_VIEWPORT are in module 'vms_smgdef'. Arguments: display_id The virtual display from which to request the information. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> status = vms_smg.put_chars (vtdpy1, 'TXT', 2, 2) >>> Python for OpenVMS -Reference Manual PAGE 2-191 vms_smg.get_display_attr() routine Screen layout, file: VMS_SMG_006.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | TXT* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # request information >>> height, width, display_attributes, video_attributes, \ ... character_set, flags = vms_smg.get_display_attr (vtdpy1) >>> >>> print height, width 5 10 >>> print display_attributes, vms_smgdef.SMG_M_BORDER 1 1 >>> print video_attributes 0 >>> print character_set, vms_smgdef.SMG_C_ASCII 1 1 >>> print flags 0 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.35 VMS_SMG_GET_KEYBOARD_ATTRIBUTES - Get Keyboard Attributes Get information about a virtual keyboard and stores it in a Python dictionary. Format: Python for OpenVMS -Reference Manual PAGE 2-192 vms_smg.get_keyboard_attributes() routine keyboard_info_table = vms_smg.get_keyboard_attributes \ (keyboard_id) Returns: keyboard_info_table This is a dictionary. See the examples section below. It shows which keys do exist. Arguments: keyboard_id The identifier of the virtual keyboard from which to read. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual keyboard - >>> # use the device name from CREATE_PASTEBOARD >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard (device_name) >>> >>> # get information about the virtual keyboard >>> keyboard_info_table = vms_smg.get_keyboard_attributes \ ... (keyboard_id) >>> >>> print type(keyboard_info_table) >>> >>> # show contents of the dictionary returned >>> for key_name in keyboard_info_table.keys(): ... print ("%14s: %s") % \ ... ( key_name, str(keyboard_info_table[key_name]) ) ... W_NUM_COLUMNS: 80 # 80 columns wide L_DEV_DEPEND: 402690992 # = 0x180093B0 - specific char 1 L_DEV_DEPEND2: -70250496 # = 0xFBD01000 - specific char 2 B_DEVTYPE: 112 # physical device type (TT$_VT300_Series) B_RECALL_NUM: 20 # size of recall buffer (byte) W_TYPEAHD_CNT: 0 # number of character in typeahead buffer L_DEV_CHAR: 0 # device characteristics B_TYPEAHD_CHAR: 0 # first character in typeahead buffer Python for OpenVMS -Reference Manual PAGE 2-193 vms_smg.get_keyboard_attributes() routine B_DEV_CLASS: 66 # DC$_TERM >>> (have entered 3 characters ('ttt') in the empty DECterm) >>> >>> # again, get information about the virtual keyboard ... keyboard_info_table = vms_smg.get_keyboard_attributes (keyboard_id) >>> >>> for key_name in keyboard_info_table.keys(): ... print ("%14s: %s") % \ ... ( key_name, str(keyboard_info_table[key_name]) ) ... W_NUM_COLUMNS: 80 L_DEV_DEPEND: 402690992 L_DEV_DEPEND2: -70250496 B_DEVTYPE: 112 B_RECALL_NUM: 20 W_TYPEAHD_CNT: 3 # 3 characters in the buffer L_DEV_CHAR: 0 B_TYPEAHD_CHAR: 116 # first character, see below B_DEV_CLASS: 66 >>> >>> print chr(keyboard_info_table['B_TYPEAHD_CHAR']) t >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.36 GET_PASTEBOARD_ATTRIBUTES - Get Pasteboard Attributes Gets pasteboard attributes and store them in the pasteboard information table. Format: pasteboard_info_table = \ vms_smg.get_pasteboard_attributes (pasteboard_id) Returns: pasteboard_info_table The pasteboard attributes. This is a dictionary - see the examples section and the 'OpenVMS RTL Screen Management (SMG$) Manual' for details. Arguments: pasteboard_id Python for OpenVMS -Reference Manual PAGE 2-194 vms_smg.get_pasteboard_attributes() routine The pasteboard from which to get the attributes. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, \ ... pasteboard_id, \ ... number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, \ ... type_of_terminal, \ ... device_name \ ... = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # get information about pasteboard >>> pasteboard_info_table = \ ... vms_smg.get_pasteboard_attributes (pasteboard_id) >>> >>> for key_name in pasteboard_info_table.keys(): ... print "%17s : %s" % (key_name, pasteboard_info_table[key_name]) ... W_SPEED : 15 # TT$C_BAUD_9600 L_CURSOR_DID : 0 # no virtual display B_PARITY : 24 # ? W_WIDTH : 80 # 80 columns wide B_DEVCLASS : 66 # DC$_TERM ($DCDEF) W_FILL : 0 # no fill characters L_DEVCHAR : 5271618 B_PHY_DEVTYPE : 112 # TT$_VT300_Series ($TTDEF) B_SMG_DEVTYPE : 6 # SMG_K_VTTERMTABLE W_PHYS_CURSOR_ROW : 1 # upper left-most W_PHYS_CURSOR_COL : 1 # corner B_COLOR : 0 # SMG_C_COLOR_UNKNOWN B_ROWS : 24 # height L_DEVDEPEND : 402690992 L_DEVDEPEND2 : -78639104 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.37 GET_PASTING_INFO - Return Pasting Information Return the row and column if the specified virtual display is pasted. Format: flags, pasteboard_row, pasteboard_column = \ Python for OpenVMS -Reference Manual PAGE 2-195 vms_smg.get_pasting_info() routine vms_smg.get_pasting_info (display_id, pasteboard_id) Returns: flags 0 or SMG_M_DISPLAY_PASTED. The value is defined in module 'vms_smgdef'. pasteboard_row Row of the pasteboard that contains row 1 of the specified virtual display. pasteboard_column Column of the pasteboard that contains column 1 of the specified virtual display. Arguments: display_id Identifier of the virtual display to be examined. pasteboard_id Identifier of the pasteboard on which the virtual display is pasted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ Python for OpenVMS -Reference Manual PAGE 2-196 vms_smg.get_pasting_info() routine ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # check virtual display 1 >>> flags, pasteboard_row, pasteboard_column = \ ... vms_smg.get_pasting_info (vtdpy1, pasteboard_id) >>> print flags, vms_smgdef.SMG_M_DISPLAY_PASTED 1 1 >>> print pasteboard_row, pasteboard_column 3 5 >>> >>> # unpaste virtual display 2 >>> status = vms_smg.unpaste_virtual_display \ ... (vtdpy2, pasteboard_id) >>> >>> print status # 1 = SS$_NORMAL 1 >>> Python for OpenVMS -Reference Manual PAGE 2-197 vms_smg.get_pasting_info() routine >>> # get info >>> flags, pasteboard_row, pasteboard_column = \ ... vms_smg.get_pasting_info (vtdpy2, pasteboard_id) >>> print flags, vms_smgdef.SMG_M_DISPLAY_PASTED 0 1 >>> print pasteboard_row, pasteboard_column 0 0 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.38 GET_VIEWPORT_CHAR - Get Characteristics of Display Viewport Return the characteristics of the specified viewport. Format: viewport_row_start, viewport_column_start, \ viewport_number_rows, viewport_number_columns = \ vms_smg.get_viewport_char (display_id) Returns: viewport_row_start The starting row number of the viewport viewport_column_start The starting column number of the specified viewport. viewport_number_rows The number of rows in the specified viewport. viewport_number_columns The number of columns in the specified viewport. Arguments: display_id Display to which the viewport is associated. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ Python for OpenVMS -Reference Manual PAGE 2-198 vms_smg.get_viewport_char() routine ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> >>> # create a viewport >>> status = vms_smg.create_viewport (vtdpy1, 2, 3, 4, 5) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_009.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |CDEFG| ! 4! |MNOPQ| ! 5! |cdefg| ! 6! |mnopq| ! 7! +-----+ * ! 8! ! V V 24! ! +________________________) _+ >>> # get information about this viewport >>> viewport_row_start, viewport_column_start, \ ... viewport_number_rows, viewport_number_columns = \ ... vms_smg.get_viewport_char (vtdpy1) >>> print viewport_row_start, viewport_column_start 2 3 >>> print viewport_number_rows, viewport_number_columns 4 5 Python for OpenVMS -Reference Manual PAGE 2-199 vms_smg.get_viewport_char() routine >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.39 HOME_CURSOR - Home Cursor Move the virtual cursor to the specified corner of a virtual display. Format: None = vms_smg.home_cursor (display_id, position_code) Returns: None Arguments: display_id Virtual display in which to move the cursor. position_code The point to which the virtual cursor moves. Constants like SMG_C_UPPER_LEFT are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (display_id, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (display_id, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (display_id, 'Line3Line3Line3', 3, 3) >>> Python for OpenVMS -Reference Manual PAGE 2-200 vms_smg.home_cursor() routine Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'n' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # move cursor to the lower right cursor >>> vms_smg.home_cursor (display_id, vms_smgdef.SMG_C_LOWER_LEFT) >>> Screen layout, file: VMS_SMG_025.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-201 vms_smg.home_cursor() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Lin| ! 6! | | ! 7! |* | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.40 INSERT_CHARS - Insert Characters Insert characters into the virtual display. Format: status = vms_smg.insert_chars (display_id, character_string, \ start_row, start_column, \ [rendition_set], [rendition_complement], \ [character_set]) Returns: status Condition code as returned from SMG$INSERT_CHARS. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Virtual display in which to insert the characters. character_string The character string to be inserted. start_row The row position at which to begin the insertion. start_column The column position at which to begin the insertion. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Python for OpenVMS -Reference Manual PAGE 2-202 vms_smg.insert_chars() routine Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (display_id, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (display_id, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (display_id, 'Line3Line3Line3', 3, 3) >>> Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'n' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-203 vms_smg.insert_chars() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # insert characters in line 1 >>> vms_smg.insert_chars (display_id, 'IN1', 1, 3) >>> >>> # insert graphic symols in line 3 >>> vms_smg.insert_chars (display_id, 'qnqxq', 3, 4, None, None, \ ... vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_026.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + 'i' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |LiIN1ne1Li| ! 4! | Line2Line| ! 5! | L-+-|-*n| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 11-SEP-2000 ZE. Python for OpenVMS -Reference Manual PAGE 2-204 vms_smg.insert_line() routine ------------------------------------------------------------------------ 2.5.41 INSERT_LINE - Insert Line Insert a line into the virtual display and scroll the display. Format: status = vms_smg.insert_line (display_id, start_row, \ [character_string], direction, \ [rendition_set], [rendition_complement], \ [flags], [character_set]) Returns: status Condition code as returned from SMG$INSERT_LINE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Virtual display in which to insert the line. start_row The row position at which the string is inserted and the scrolling begins. character_string The character string to be inserted. direction The scrolling directions. Bit mask values like SMG_M_UP ar in module 'vms_smgdef'. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. flags Optional bit mask that specifies the action to take if the text does not fit on the line. Bit masks like SMG_M_WRAP_WORD are in module 'vms_smgdef'. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG Python for OpenVMS -Reference Manual PAGE 2-205 vms_smg.insert_line() routine >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (display_id, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (display_id, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (display_id, 'Line3Line3Line3', 3, 3) >>> Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + 'n' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # insert characters in line 2 >>> status = vms_smg.insert_line \ ... (display_id, 2, 'LI1', vms_smgdef.SMG_M_DOWN) >>> Python for OpenVMS -Reference Manual PAGE 2-206 vms_smg.insert_line() routine Screen layout, file: VMS_SMG_066.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + ' ' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! |LI1* | ! 5! | Line2Line| ! 6! | Line3Lin| ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # insert graphic symols in line 4 >>> status = vms_smg.insert_line \ ... (display_id, 4, 'qnqxq', vms_smgdef.SMG_M_UP, \ ... None, None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_027.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |LI1 | ! 4! | Line2Line| ! 5! | Line3Lin| ! 6! |-+-|-* | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ The first line containing 'Line1Line1' has scrolled off the (upper row) of the screen. Python for OpenVMS -Reference Manual PAGE 2-207 vms_smg.insert_line() routine 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.42 INVALIDATE_DISPLAY - Mark a Display as Invalid Mark a display as invalid and cause the entire display to be redrawn. Format: None = vms_smg.invalidate_display (display_id) Returns: None Arguments: display_id Virtual display to be marked as invalid. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-208 vms_smg.invalidate_display() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Send a broadcast to the terminal device from another process: $ reply /terminal= _FTA23: - "BRDCST ===== ===== ===== ===== ===== ===== " Screen layout, file: VMS_SMG_028.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! | | ! 4! | | ! 5!Reply received on NODE fr ! 6!BRDCST ===== ===== ===== ! 7!* | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # cause the virtual display to be redrawn >>> vms_smg.invalidate_display (display_id) >>> Python for OpenVMS -Reference Manual PAGE 2-209 vms_smg.invalidate_display() routine Screen layout, file: VMS_SMG_029.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | |on NODE fr ! 6! | |=== ===== ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Notice that the virtual display itself and anything left from it has been redrawn. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.43 KEYCODE_TO_NAME - Translate a Key Code into a Key Name Translate the key code of a key on the keyboard into its associated key name. The opposite function is vms_smg.name_to_keycode(). Format: key_name = vms_smg.keycode_to_name (key_code) Returns: key_name The name of the key into which key_code is to be translated. key_name is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth). Arguments: key_code The key code to translate into a key name. Symbolic names like SMG_K_TRM_PF2 are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef Python for OpenVMS -Reference Manual PAGE 2-210 vms_smg.keycode_to_name() routine >>> print vms_smg.keycode_to_name (vms_smgdef.SMG_K_TRM_PF2) PF2 >>> ---------------------------------------- >>> print vms_smg.keycode_to_name (-1) Traceback (innermost last): File "", line 1, in ? ValueError: argument 1: key_code - must be between 0..65535 >>> >>> print vms_smg.keycode_to_name (30000) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1213466, '%SMG-E-INVKEYNAM, invalid key name') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.44 LABEL_BORDER - Label a Virtual Display Border Supply a label for a virtual display's border. Format: None = vms_smg.label_border (display_id, \ [text], [position_code], [units], \ [rendition-set], [rendition-complement], \ [character-set]) Returns: None Arguments: display_id Virtual display to be labeled. text The new label for this display's border. position_code Specifies which of the display's borders contains the label. Constants like SMG_K_TOP are in module 'vms_smgdef'. units Specifies the character position at which the label begins within the border. If omitted (None), the label is centered in the specified border. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. Python for OpenVMS -Reference Manual PAGE 2-211 vms_smg.label_border() routine rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Python for OpenVMS -Reference Manual PAGE 2-212 vms_smg.label_border() routine Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # label virtual display 1 >>> vms_smg.label_border (vtdpy1, 'VTDPY1') >>> (Notice that the cursor of this display became visible) >>> # label virtual display 2 >>> vms_smg.label_border (vtdpy2, 'DPY2', vms_smgdef.SMG_K_RIGHT) >>> (Notice that the cursor of this display became visible, again) Python for OpenVMS -Reference Manual PAGE 2-213 vms_smg.label_border() routine Screen layout, file: VMS_SMG_030.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +--VTDPY1--+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* D ! 6! | | P ! 7! | | Y ! 8! +-| 2 ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ Puzzled why display 2 is not labeled 'VTDPY2'? --> The name is too long for the right border! >>> vms_smg.label_border (vtdpy2, 'VTDPY2', vms_smgdef.SMG_K_RIGHT) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212940, '%SMG-F-INVARG, invalid argument') >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.45 LIST_PASTEBOARD_ORDER - Return Pasting Information Return the Pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Also, the pasteboard row 1 and column 1 (origins) of the virtual display are returned. Format: status, context, pasteboard_id, \ pasteboard_row, pasteboard_column = \ vms_smg.list_pasteboard_order (display_id, context) Returns: status Condition code as returned from SMG$LIST_PASTEBOARD_ORDER. Either SS$_NORMAL or SMG$_NOTPASTED are returned here - all other codes produce a Python exception. The OpenVMS V6.1 Python for OpenVMS -Reference Manual PAGE 2-214 vms_smg.list_pasteboard_order() routine documentation says "SMG$_NOPASTED", which is wrong. context Search context - see the OpenVMS documentation for details. pasteboard_id The identifier of the pasteboard on which the virtual display is pasted. pasteboard_row Row of the pasteboard that contains row 1 of the specified virtual display. pasteboard_column Column of the pasteboard that contains column 1 of the specified virtual display. Arguments: display_id Identifier of the virtual display that is pasted. context Search context - see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> import vms_sys >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) Python for OpenVMS -Reference Manual PAGE 2-215 vms_smg.list_pasteboard_order() routine >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # check virtual display 1 >>> status, context, pb_id_ret, \ ... pasteboard_row, pasteboard_column = \ ... vms_smg.list_pasteboard_order (vtdpy1, 0) >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> print context, pb_id_ret, pasteboard_id 2965328 1 1 >>> print pasteboard_row, pasteboard_column 3 5 >>> >>> # check if virtual display is pasted on another pasteboard >>> # (the updated context is used) >>> status, context, pb_id_ret, \ ... pasteboard_row, pasteboard_column = \ ... vms_smg.list_pasteboard_order (vtdpy1, context) Python for OpenVMS -Reference Manual PAGE 2-216 vms_smg.list_pasteboard_order() routine >>> >>> print vms_sys.getmsg (status)[0] %SMG-F-NOTPASTED, given display is not pasted to given pasteboard >>> print context, pb_id_ret, pasteboard_id 0 -1 1 >>> print pasteboard_row, pasteboard_column 0 0 >>> ---------------------------------------- >>> # unpaste virtual display 2 >>> status = vms_smg.unpaste_virtual_display \ ... (vtdpy2, pasteboard_id) >>> >>> # check virtual display 2 >>> status, context, pb_id_ret, \ ... pasteboard_row, pasteboard_column = \ ... vms_smg.list_pasteboard_order (vtdpy2, 0) >>> >>> print vms_sys.getmsg (status)[0] %SMG-F-NOTPASTED, given display is not pasted to given pasteboard >>> print context, pb_id_ret, pasteboard_id 0 -1 1 >>> print pasteboard_row, pasteboard_column 0 0 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.46 LIST_PASTING_ORDER - Return Virtual Display Pasting Information Return the identifiers of the virtual displays pasted to a specified pasteboard. Also, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned. Format: status, context, display_id, \ pasteboard_row, pasteboard_column = \ vms_smg.list_pasting_order (pasteboard_id, context) Returns: status Condition code as returned from SMG$LIST_PASTING_ORDER. Either SS$_NORMAL or SMG$_NOTPASTED are returned here - all other codes produce a Python exception. context Python for OpenVMS -Reference Manual PAGE 2-217 vms_smg.list_pasting_order() routine Search context - see the OpenVMS documentation for details. display_id The identifier of the display that is pasted. pasteboard_row Row of the pasteboard that contains row 1 of this virtual display. pasteboard_column Column of the pasteboard that contains column 1 of this virtual display. Arguments: pasteboard_id Identifier of the pasteboard on which the virtual display(s) is/are pasted. context Search context - see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> import vms_sys >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Python for OpenVMS -Reference Manual PAGE 2-218 vms_smg.list_pasting_order() routine >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # check pasteboard >>> status, context, display_id, \ ... pasteboard_row, pasteboard_column = \ ... vms_smg.list_pasting_order (pasteboard_id, 0) >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> print context, display_id, vtdpy1 3007944 3007424 3007424 >>> print pasteboard_row, pasteboard_column 3 5 >>> >>> # check if more virtual displays are pasted to this pasteboard >>> # (the updated context is used) >>> status, context, display_id, \ ... pasteboard_row, pasteboard_column = \ ... vms_smg.list_pasting_order (pasteboard_id, context) >>> >>> print vms_sys.getmsg (status)[0] Python for OpenVMS -Reference Manual PAGE 2-219 vms_smg.list_pasting_order() routine %SYSTEM-S-NORMAL, normal successful completion >>> print context, display_id, vtdpy2 3006216 3007584 3007584 >>> print pasteboard_row, pasteboard_column 5 7 >>> >>> # check if more virtual displays are pasted to this pasteboard >>> # (the updated context is used) >>> status, context, display_id, \ ... pasteboard_row, pasteboard_column = \ ... vms_smg.list_pasting_order (pasteboard_id, context) >>> >>> print vms_sys.getmsg (status)[0] %SMG-F-NOTPASTED, given display is not pasted to given pasteboard >>> print context, display_id 0 0 >>> print pasteboard_row, pasteboard_column 0 0 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.47 LOAD_VIRTUAL_DISPLAY - Load a Virtual Display from a File Create a new virtual display and loads it from a file that has been created from another virtual display saved with vms_smg.save_virtual_display(). Format: display_id = vms_smg.load_virtual_display ([filespec]) Returns: display_id Virtual display id that has been created. Arguments: filespec The file specification of the file in which a virtual display was formerly saved. (The OpenVMS V6.1 documentation says 'is saved', which is wrong - the contents from this file are loaded by this routine). If 'filespec' is omitted, the default file specification is SMGDISPLY.DAT. You must use OpenVMS format for the file specification. Examples: Python for OpenVMS -Reference Manual PAGE 2-220 vms_smg.load_virtual_display() routine >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (vtdpy1, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (vtdpy1, 'Line3Line3Line3', 3, 3) >>> Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + 'n' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Python for OpenVMS -Reference Manual PAGE 2-221 vms_smg.load_virtual_display() routine >>> # save contents to a file >>> vms_smg.save_virtual_display (vtdpy1, 'SMG.TMP') >>> The result is a file with binary contents. You should not use the DCL command 'TYPE' to view its contents. >>> # load these contents into a new virtual display >>> vtdpy2 = vms_smg.load_virtual_display ('SMG.TMP') >>> >>> # paste the new display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 7, 8, None) >>> Screen layout, file: VMS_SMG_054.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Lin| ! 6! | +----------+ ! 7! | |Line1Line1| ! 8! +--| Line2Line| ! 9! | Line3Li*| ! 10! | | ! 11! | | ! 12! +----------+ ! 13! ! V V 24! ! +________________________) _+ >>> # try to save to an invalid filespec >>> vms_smg.save_virtual_display (vtdpy1, 'BAD%@*.TMP') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (100052, '%RMS-F-SYN, file specification syntax error') >>> >>> # try to save a non-existent display id >>> vms_smg.save_virtual_display (vtdpy1+99, 'SMG.TMP') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> >>> # try to load from an invalid filespec Python for OpenVMS -Reference Manual PAGE 2-222 vms_smg.load_virtual_display() routine >>> vtdpy = vms_smg.load_virtual_display ('BAD%@*.TMP') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (100052, '%RMS-F-SYN, file specification syntax error') >>> 01-OCT-2000 ZE. ------------------------------------------------------------------------ 2.5.48 MOVE_TEXT - Move Text from One Virtual Display to Another Move a rectangle of text from one virtual display to another virtual display. Format: None = vms_smg.move_text (display_id, \ top_left_row, top_left_column, \ bottom_right_row, bottom_right_column, \ display_id2, \ [top_left_row2], [top_left_column2], \ [flags]) Returns: None Arguments: display_id The virtual display from which text is to be moved. top_left_row Top left row of the rectangle of text you want to move. top_left_column Top left column of the rectangle of text you want to move. bottom_right_row Bottom right row of the rectangle of text you want to move. bottom_right_column Bottom right column of the rectangle of text you want to move. display_id2 Specifies the virtual display to which the text is to be moved. top_left_row2 Top left row of the rectangle that is the destination of the text you want to move. If you do not specify a value, the text is moved to the current virtual cursor row. top_left_column2 Top left column of the rectangle that is the destination of the text you want to move. If you do not specify a value, the text is moved to the current virtual cursor column. flags Optional bit mask that specifies the action to take when Python for OpenVMS -Reference Manual PAGE 2-223 vms_smg.move_text() routine moving the specified text. Bit mask values like SMG_M_TEXT_SAVE are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (vtdpy1, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (vtdpy1, 'Line3Line3Line3', 3, 3) >>> Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + 'n' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-224 vms_smg.move_text() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # create another virtual display >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (6, 11, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> >>> # copy (some) text, but use an offset in the other display >>> vms_smg.move_text ( \ ... vtdpy1, # display_id ... 1, # top_left_row ... 1, # top_left_column ... 3, # bottom_right_row ... 8, # bottom_right_column ... vtdpy2, # display_id2 ... 2, # [top_left_row2] ... 2, # [top_left_column2] ... 0) # [flags] >>> Notice that the text from the old display was removed. Screen layout, file: VMS_SMG_031.JPG legend Python for OpenVMS -Reference Manual PAGE 2-225 vms_smg.move_text() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! | e1| ! 4! | +----------+ ! 5! | |* | ! 6! | | Line1Lin | ! 7! | | Line2Li | ! 8! +-| Line3L | ! 9! | | ! 9! +----------+ ! 9! ! 9! ! V V 24! ! +________________________) _+ 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.49 MOVE_VIRTUAL_DISPLAY - Move Virtual Display Moves a virtual display on the pasteboard, but keeps the pasting order. Use vms_smg.repaste_virtual_display() to move the location and change the pasting order of the display within the pasteboard. Format: status = vms_smg.move_virtual_display (display_id, \ pasteboard_id, pasteboard_row, pasteboard_column, \ [top_display_id]) Returns: status Condition code as returned from SMG$MOVE_VIRTUAL_DISPLAY. Either SS$_NORMAL or SMG$_BATWAS_ON are returned here - all other codes produce a Python exception. (The latter code is not mentioned in the documentation of OpenVMS VAX V6.1). Arguments: display_id Virtual display to be moved. pasteboard_id Pasteboard on which the virtual display is to be moved. pasteboard_row Specifies the row of the pasteboard that is to contain row 1 of the new location of the specified virtual display. Python for OpenVMS -Reference Manual PAGE 2-226 vms_smg.move_virtual_display() routine pasteboard_column Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. top_display_id Identifier of the virtual display under which the moving display_id will be pasted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Python for OpenVMS -Reference Manual PAGE 2-227 vms_smg.move_virtual_display() routine Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ >>> # now move virtual display 1 >>> status = vms_smg.move_virtual_display (vtdpy1, pasteboard_id, 3, 10) >>> Screen layout, file: VMS_SMG_004.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! +----------+ | ! 5! |V2* | | ! 6! | | | ! 7! | | | ! 8! | |--+ ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) _+ Python for OpenVMS -Reference Manual PAGE 2-228 vms_smg.move_virtual_display() routine Notice that the display 1 is at a new location, but still partially occluded by virtual display 2. Also, the cursor position has not changed, which does happen when using vms_smg.repaste_virtual_display(). 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.50 NAME_TO_KEYCODE - Translate a Key Name into a Key Code Translate the key name of a key on the keyboard into its associated key code. The opposite function is vms_smg.keycode_to_name(). Format: key_code = vms_smg.name_to_keycode (key_name) Returns: key_code The key code as translated from the key_name. Symbolic names like SMG_K_TRM_PF2 are in module 'vms_smgdef'. Arguments: key_name The name of the key to be translated into the key_code. key_name is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth). Examples: >>> import vms_smg >>> import vms_smgdef >>> key_code = vms_smg.name_to_keycode ('PF2') >>> print key_code, vms_smgdef.SMG_K_TRM_PF2 257 257 >>> ---------------------------------------- >>> print vms_smg.name_to_keycode ('*BAD*') Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1213466, '%SMG-E-INVKEYNAM, invalid key name') >>> >>> print vms_smg.name_to_keycode (0) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, int found Python for OpenVMS -Reference Manual PAGE 2-229 vms_smg.name_to_keycode() routine >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.51 PASTE_VIRTUAL_DISPLAY - Paste a Virtual Display Paste a virtual display to a pasteboard. Format: status = vms_smg.paste_virtual_display (display_id, pasteboard_id,\ [pasteboard_row], [pasteboard_column], [top_display_id]) Returns: status Condition code as returned from SMG$PASTE_VIRTUAL_DISPLAY. Either SS$_NORMAL or SMG$_BATWAS_ON are returned here - all other codes produce a Python exception. (The latter code is not mentioned in the documentation of OpenVMS VAX V6.1). Arguments: display_id Virtual display to be pasted. pasteboard_id Pasteboard to which the virtual display is to be pasted. pasteboard_row Specifies the row of the pasteboard that is to contain row 1 of the specified virtual display. pasteboard_column Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. top_display_id Identifier of the virtual display under which to paste 'display_id'. The top_display must already be pasted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ Python for OpenVMS -Reference Manual PAGE 2-230 vms_smg.paste_virtual_display() routine ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # it appears possible to re-paste an already pasted display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 15, None) >>> Notice that the display has moved to the right. ---------------------------------------- >>> status = vms_smg.paste_virtual_display (99, 299) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> >>> status = vms_smg.paste_virtual_display (display_id, 299) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212964, '%SMG-F-INVPAS_ID, invalid pasteboard-id') Python for OpenVMS -Reference Manual PAGE 2-231 vms_smg.paste_virtual_display() routine >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.52 POP_VIRTUAL_DISPLAY - Delete a Series of Virtual Displays Delete the specified virtual display and all displays that were pasted on the specified pasteboard on top of the specified virtual display. Format: None = vms_smg.pop_virtual_display (display_id, pasteboard_id) Returns: None Arguments: display_id Identifier of the lowest (first) virtual display to be deleted. pasteboard_id Identifier of the pasteboard on which the display deletions take place. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> Python for OpenVMS -Reference Manual PAGE 2-232 vms_smg.pop_virtual_display() routine >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # create virtual display 3 >>> status, vtdpy3 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 3 >>> status = vms_smg.put_chars (vtdpy3, 'V3', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> >>> # paste virtual display 3 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy3, pasteboard_id, 7, 9, None) >>> Screen layout, file: VMS_SMG_032.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-233 vms_smg.pop_virtual_display() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2 | ! 6! | | +----------+ ! 7! | | |V3* | ! 8! +-| | | ! 9! | | | ! 10! +-| | ! 11! | | ! 12! +----------+ ! 13! ! V V 24! ! +________________________) _+ >>> # pop virtual display 2 - (will also unpaste display 3) >>> vms_smg.pop_virtual_display (vtdpy2, pasteboard_id) >>> Screen layout, file: VMS_SMG_033.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | | ! 5! | | ! 6! | | ! 7! | * | ! 8! +----------+ ! 9! ! 10! ! 11! ! 12! ! 13! ! V V 24! ! +________________________) _+ Notice that the cursor is still at the old position. 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-234 vms_smg.print_pasteboard() routine 2.5.53 PRINT_PASTEBOARD - Print Pasteboard Using a Print Queue Print the contents of the specified pasteboard on a line printer. Note that the entry number of the print job is NOT returned! Format: None = vms_smg.print_pasteboard (pasteboard_id, \ [queue_name], [copies], [form_name]) Returns: None Arguments: pasteboard_id Identifier of the pasteboard to be printed. queue_name Queue name. If omitted, the default is SYS$PRINT. copies Number of copies to print. form_name Name of the form to use when printing. If omitted, the default is "DEFAULT". Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put some text in the display >>> status = vms_smg.put_chars (vtdpy1, 'Line1Line1Line1', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'Line2Line2Line2', 2, 2) >>> status = vms_smg.put_chars (vtdpy1, 'Line3Line3Line3', 3, 3) >>> Python for OpenVMS -Reference Manual PAGE 2-235 vms_smg.print_pasteboard() routine Screen layout, file: VMS_SMG_015.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position + 'n' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |Line1Line1| ! 4! | Line2Line| ! 5! | Line3Li*| ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # print the pasteboard to queue "HERE_PRINT" >>> vms_smg.print_pasteboard (pasteboard_id, "HERE_PRINT") >>> $ show queue /FULL HERE_PRINT Printer queue HERE_PRINT, stopped, on HERE::NPA0:, mounted form DEFAULT /BASE_PRIORITY=4 /DEFAULT=(FEED,FORM=DEFAULT) /OWNER=[G1,SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:S) Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 30 SMGPBD ZESSIN 4 Pending (queue stopped) Submitted 2-SEP-2000 20:01 /FORM=DEFAULT /PRIORITY=100 File: _$99$DKA100:[USER.ZESSIN]SMGPBD.LIS;1 /DELETE $! $ type _$99$DKA100:[USER.ZESSIN]SMGPBD.LIS;1 +----------+ |Line1Line1| | Line2Line| | Line3Lin| | | | | +----------+ [ 15 more empty lines omitted ] $ Python for OpenVMS -Reference Manual PAGE 2-236 vms_smg.print_pasteboard() routine 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.54 PUT_CHARS - Write Characters to a Virtual Display Write characters in a virtual display with the text you specify. Format: status = vms_smg.put_chars (display_id, text, \ [start_row], [start_column], [flags], \ [rendition_set], [rendition_complement], \ [character_set]) Returns: status Condition code as returned from SMG$PUT_CHARS. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. start_row Row number at which to put the characters. If omitted, the position of the current virtual cursor is used. start_column Column number at which to put the characters. If omitted, the position of the current virtual cursor is used. flags Bit mask that specifies the action to take before the specified text is output. Values like SMG_M_ERASE_TO_EOL are in module 'vms_smgdef'. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef Python for OpenVMS -Reference Manual PAGE 2-237 vms_smg.put_chars() routine >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, 'VTDPY1', 0, 0) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_chars (vtdpy1, 'qnqxq', 2, 2, 0, \ ... None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_034.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |VTDPY1 | ! 4! | -+-|-* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. Python for OpenVMS -Reference Manual PAGE 2-238 vms_smg.put_chars_highwide() routine ------------------------------------------------------------------------ 2.5.55 PUT_CHARS_HIGHWIDE - Write Double-Height Double-Width Characters Write double-height, double-width characters to a virtual display. Format: status = vms_smg.put_chars_highwide (display_id, text, \ [start_row], [start_column], \ [rendition_set], [rendition_complement], \ [character_set]) Returns: status Condition code as returned from SMG$PUT_CHARS_HIGHWIDE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. start_row Row number at which to put the characters. If omitted, the position of the current virtual cursor is used. start_column Column number at which to put the characters. If omitted, the position of the current virtual cursor is used. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ Python for OpenVMS -Reference Manual PAGE 2-239 vms_smg.put_chars_highwide() routine ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars_highwide (vtdpy1, 'VD1', 1, 1) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_chars_highwide (vtdpy1, 'qnx', 3, 2, \ ... None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_035.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! ||VVDD11 || ! 4! ||VVDD11 || ! 5! ||--++||** || ! 6! ||--++|| || ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ It is not possible to show an exact picture here. Please see file VMS_SMG_035.JPG 10-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-240 vms_smg.put_chars_multi() routine 2.5.56 PUT_CHARS_MULTI - Put Text with Multiple Renditions to Display Write text with multiple renditions to the virtual display. Format: status = vms_smg.put_chars_multi (display_id, text, \ [start_row], [start_column], [flags], \ [rendition_string], [rendition_complement], \ [character_set]) Returns: status Condition code as returned from SMG$PUT_CHARS_MULTI. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. start_row Row number at which to put the characters. If omitted, the position of the current virtual cursor is used. start_column Column number at which to put the characters. If omitted, the position of the current virtual cursor is used. flags Bit mask that specifies the action to take before the specified text is output. Values like SMG_M_ERASE_TO_EOL are in module 'vms_smgdef'. rendition_string Optional bit mask string that controls the video attributes. Each attribute set causes the corresponding attribute to be set for the corresponding byte in the text string in the display. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Optional bit mask string that controls the video attributes. There are no symbolic names available - please see the OpenVMS documentation for details. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG Python for OpenVMS -Reference Manual PAGE 2-241 vms_smg.put_chars_multi() routine >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars_multi (vtdpy1, 'VTDPY1', 1, 1) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_chars_multi (vtdpy1, 'qnqxq', 2, 2, 0, \ ... None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> >>> rendition_string = chr(vms_smgdef.SMG_M_BOLD) + \ ... chr(vms_smgdef.SMG_M_REVERSE) + \ ... chr(vms_smgdef.SMG_M_UNDERLINE) >>> # caution - these are control characters that can screw up >>> # a terminal's setting! - use repr() for inspection >>> print repr (rendition_string) '\001\002\010' >>> >>> status = vms_smg.put_chars_multi (vtdpy1, 'bru', 4, 1, 0, \ ... rendition_string, None, vms_smgdef.SMG_C_ASCII) >>> Screen layout, file: VMS_SMG_036.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position b = bold character 'b' r = reverse character 'r' u = underlined character 'u' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-242 vms_smg.put_chars_multi() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |VTDPY1 | ! 4! | -+-|- | ! 5! | | ! 6! |bru* | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ It is not possible to show an exact picture here. Please see file VMS_SMG_036.JPG 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.57 PUT_CHARS_WIDE - Write Double-Width Characters Write double-width characters to a virtual display. Format: status = vms_smg.put_chars_wide (display_id, text, \ [start_row], [start_column], \ [rendition_set], [rendition_complement], \ [character_set]) Returns: status Condition code as returned from SMG$PUT_CHARS_WIDE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. start_row Row number at which to put the characters. If omitted, the position of the current virtual cursor is used. start_column Column number at which to put the characters. If omitted, the Python for OpenVMS -Reference Manual PAGE 2-243 vms_smg.put_chars_wide() routine position of the current virtual cursor is used. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars_wide (vtdpy1, 'VD1', 1, 1) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_chars_wide (vtdpy1, 'qnx', 3, 1, \ ... None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_037.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-244 vms_smg.put_chars_wide() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! ||VVDD11 || ! 4! | | ! 5! ||--++|| || ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ It is not possible to show an exact picture here. Please see file VMS_SMG_037.JPG 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.58 VMS_SMG_PUT_HELP_TEXT - Output Help Text to the Display Retrieves and outputs the help text for the specified topic in the virtual display provided. Format: None = vms_smg.put_help_text (display_id, [keyboard_id], \ [help_topic], [help_library], \ [rendition_set], [rendition_complement]) Returns: None Arguments: display_id Display identifier of the virtual display to which the help text is written. keyboard_id The identifier of the virtual keyboard from which to read. help_topic The help topic - e.g. 'DIRECTORY'. help_library Help library name. The default is SYS$HELP:HELPLIB.HLB. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. Python for OpenVMS -Reference Manual PAGE 2-245 vms_smg.put_help_text() routine rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual keyboard - >>> # use the device name from CREATE_PASTEBOARD >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard (device_name) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (15, 55, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 2, 2, None) >>> >>> # output the help text >>> vms_smg.put_help_text (vtdpy1, keyboard_id, 'SHOW', 'UAFHELP') (Note that Python does not prompt back, yet) Python for OpenVMS -Reference Manual PAGE 2-246 vms_smg.put_help_text() routine Screen layout, file: VMS_SMG_059.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 3 4 5 8 123456789012345678901234567890123456789012345678901234567 0 +_________________________________________________________) _+ 1!+------------------------------------------------------+ ! 2!| | ! 3!|SHOW | ! 4!| | ! 5!| Display reports for selected UAF records on the | ! 6!| current | ! 7!| SYS$OUTPUT device. | ! 8!| | ! 9!| Format | ! 10!| | ! 11!| SHOW user-spec | ! 12!| | ! 13!| | ! 14!| | ! 15!| | ! 16!|Press RETURN to continue...* | ! 17!+------------------------------------------------------+ ! 18! ! V V 24! ! +_________________________________________________________) _+ ---------------------------------------- Pressing in the DECterm created. Python for OpenVMS -Reference Manual PAGE 2-247 vms_smg.put_help_text() routine Screen layout, file: VMS_SMG_060.JPG 1 2 3 4 5 8 123456789012345678901234567890123456789012345678901234567 0 +_________________________________________________________) _+ 1!+------------------------------------------------------+ ! 2!| | ! 3!| Additional information available: | ! 4!| | ! 5!| Parameter Qualifiers | ! 6!| /BRIEF /FULL /EXACT /HIGHLIGHT /PAGE | ! 7!| /SEARCH /WRAP | ! 8!| Examples /IDENTIFIER /PROXY | ! 9!| /RIGHTS | ! 10!| | ! 11!|SHOW Subtopic? * | ! 12!| | ! 13!| | ! 14!| | ! 15!| | ! 16!| | ! 17!+------------------------------------------------------+ ! 18! ! V V 24! ! +_________________________________________________________) _+ ---------------------------------------- Entering '/EXACT' and pressing in the DECterm created. Python for OpenVMS -Reference Manual PAGE 2-248 vms_smg.put_help_text() routine Screen layout, file: VMS_SMG_061.JPG 1 2 3 4 5 8 123456789012345678901234567890123456789012345678901234567 0 +_________________________________________________________) _+ 1!+------------------------------------------------------+ ! 2!| | ! 3!| Additional information available: | ! 4!| | ! 5!| Parameter Qualifiers | ! 6!| /BRIEF /FULL /EXACT /HIGHLIGHT /PAGE | ! 7!| /SEARCH /WRAP | ! 8!| Examples /IDENTIFIER /PROXY | ! 9!| /RIGHTS | ! 10!| | ! 11!|SHOW Subtopic? /EXACT | ! 12!| | ! 13!|SHOW | ! 14!| | ! 15!| | ! 16!|Press RETURN to continue...* | ! 17!+------------------------------------------------------+ ! 18! ! V V 24! ! +_________________________________________________________) _+ ---------------------------------------- Pressing in the DECterm created. Python for OpenVMS -Reference Manual PAGE 2-249 vms_smg.put_help_text() routine Screen layout, file: VMS_SMG_062.JPG 1 2 3 4 5 8 123456789012345678901234567890123456789012345678901234567 0 +_________________________________________________________) _+ 1!+------------------------------------------------------+ ! 2!| | ! 3!| | ! 4!| Additional information available: | ! 5!| | ! 6!| ADD Command_Summary COPY CREATE | ! 7!| DEFAULT EXIT GRANT HELP LIST | ! 8!| MODIFY REMOVE RENAME REVOKE SHOW | ! 9!| Usage_Summary | ! 10!| | ! 11!| | ! 12!|SHOW | ! 13!| | ! 14!| | ! 15!|Press RETURN to continue... Exit | ! 16!|*ress RETURN to continue... | ! 17!+------------------------------------------------------+ ! 18! ! V V 24! ! +_________________________________________________________) _+ The Python prompt ('>>>') in the interpreter's window is back. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.59 PUT_LINE - Write Line to Virtual Display Write line of text to a virtual display, beginning at the current virtual cursor position. Format: status = vms_smg.put_line (display_id, text, [line_advance], \ [rendition_set], [rendition_complement], \ [flags], [character_set], [direction]) Returns: status Condition code as returned from SMG$PUT_LINE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Python for OpenVMS -Reference Manual PAGE 2-250 vms_smg.put_line() routine Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. line_advance Specifies the number of lines to advance after output. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. flags Bit mask that specifies the action to take if the text does not fit on the line. Values like SMG_M_WRAP_CHAR are in module 'vms_smgdef'. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. direction Specifies the direction to scroll, if scrolling is necessary. Bit mask values like SMG_M_DOWN are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Python for OpenVMS -Reference Manual PAGE 2-251 vms_smg.put_line() routine Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 2, 2) >>> >>> # put line on virtual display >>> status = vms_smg.put_line (vtdpy1, 'VTDPY1') >>> Screen layout, file: VMS_SMG_038.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'K' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-252 vms_smg.put_line() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |AVTDPY1 | ! 5! |*LMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 4, 3) >>> >>> # put line on virtual display - graphics >>> status = vms_smg.put_line (vtdpy1, 'qnqxq', None, None, None, \ ... None, vms_smgdef.SMG_C_SPEC_GRAPHICS, \ ... vms_smgdef.SMG_M_DOWN ) >>> Screen layout, file: VMS_SMG_039.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'K' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |AVTDPY1 | ! 5! |*LMNOPQRST| ! 6! |ab-+-|- | ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Python for OpenVMS -Reference Manual PAGE 2-253 vms_smg.put_line() routine 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.60 PUT_LINE_HIGHWIDE - Write Double-Height and Double-Width Line Writes a line of text with double-height and double-width characters. Format: status = vms_smg.put_line_highwide (display_id, text, \ [line_advance], \ [rendition_set], [rendition_complement], \ [flags], [character_set]) Returns: status Condition code as returned from SMG$PUT_LINE_HIGHWIDE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. line_advance Specifies the number of lines to advance after output. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. flags Bit mask that specifies the action to take if the text does not fit on the line. Values like SMG_M_WRAP_CHAR are in module 'vms_smgdef'. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ Python for OpenVMS -Reference Manual PAGE 2-254 vms_smg.put_line_highwide() routine ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 2, 2) >>> >>> # put line on virtual display >>> status = vms_smg.put_line_highwide (vtdpy1, 'VD1') Python for OpenVMS -Reference Manual PAGE 2-255 vms_smg.put_line_highwide() routine >>> Screen layout, file: VMS_SMG_043.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'a' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! ||AAVVDD11 || ! 5! ||KKVVDD11 || ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Row 2, column 1+2 contain the upper half of 'A'. Row 3, column 1+2 contain the lower half of 'K'. >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 4, 3) >>> >>> # put line on virtual display - graphics >>> status = vms_smg.put_line_highwide (vtdpy1, 'qnx', None, None, None, \ ... None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_044.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'k' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-256 vms_smg.put_line_highwide() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! ||AAVVDD11 || ! 5! ||KKVVDD11 || ! 6! ||aabb--++|||| ! 7! ||**ll--++|||| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Row 4, column 1+2 contain the upper half of 'a'. Row 5, column 1+2 contain the lower half of 'k'. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.61 PUT_LINE_MULTI - Write Line with Multiple Renditions to Display Write lines with multiple renditions to the virtual display, optionally followed by cursor movement sequences. Format: status = vms_smg.put_line_multi (display_id, text, \ [rendition_string], [rendition_complement], \ [line_advance], [flags], [direction], \ [character_set]) Returns: status Condition code as returned from SMG$PUT_LINE_MULTI. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. rendition_string Optional bit mask string that controls the video attributes. Each attribute set causes the corresponding attribute to be Python for OpenVMS -Reference Manual PAGE 2-257 vms_smg.put_line_multi() routine set for the corresponding byte in the text string in the display. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Optional bit mask string that controls the video attributes. There are no symbolic names available - please see the OpenVMS documentation for details. line_advance Specifies the number of lines to advance after output. flags Bit mask that specifies the action to take if the text does not fit on the line. Values like SMG_M_WRAP_CHAR are in module 'vms_smgdef'. direction Specifies the direction to scroll, if scrolling is necessary. Bit mask values like SMG_M_DOWN are in module 'vms_smgdef'. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Python for OpenVMS -Reference Manual PAGE 2-258 vms_smg.put_line_multi() routine Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 2, 2) >>> >>> # put line on virtual display >>> status = vms_smg.put_line_multi (vtdpy1, 'VTDPY1') >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 3, 2) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_line_multi (vtdpy1, 'qnqxq', None, None, \ ... 0, None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 5, 2) >>> rendition_string = chr(vms_smgdef.SMG_M_BOLD) + \ ... chr(vms_smgdef.SMG_M_REVERSE) + \ ... chr(vms_smgdef.SMG_M_UNDERLINE) >>> # caution - these are control characters that can screw up >>> # a terminal's setting! - use repr() for inspection >>> print repr (rendition_string) '\001\002\010' >>> >>> status = vms_smg.put_line_multi (vtdpy1, 'bru', \ Python for OpenVMS -Reference Manual PAGE 2-259 vms_smg.put_line_multi() routine ... rendition_string, None, \ ... 0, 0, vms_smgdef.SMG_M_UP, \ ... vms_smgdef.SMG_C_ASCII) >>> Screen layout, file: VMS_SMG_042.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'k' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |AVTDPY1 | ! 5! |K-+-|- | ! 6! |abcdefghij| ! 7! |*bru | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ The 'b' in the last line appears bold, the 'r' in the last line appears reverse and the 'u' in the last line appears underlined. 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.62 PUT_LINE_WIDE - Write Double-Width Line Write a line of double-width text to a virtual display. Format: status = vms_smg.put_line_wide (display_id, text, \ [line_advance], \ [rendition_set], [rendition_complement], \ [flags], [character_set]) Returns: status Python for OpenVMS -Reference Manual PAGE 2-260 vms_smg.put_line_wide() routine Condition code as returned from SMG$PUT_LINE_WIDE. Either SS$_NORMAL or SMG$_WILUSERMS are returned here - all other codes produce a Python exception. Arguments: display_id Identifier of the virtual display in which to put the text. text Characters to be written to the virtual display. line_advance Specifies the number of lines to advance after output. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. flags Bit mask that specifies the action to take if the text does not fit on the line. Values like SMG_M_WRAP_CHAR are in module 'vms_smgdef'. character_set The default character set for all text. Constants like SMG_C_ASCII are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) Python for OpenVMS -Reference Manual PAGE 2-261 vms_smg.put_line_wide() routine >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 2, 2) >>> >>> # put line on virtual display >>> status = vms_smg.put_line_wide (vtdpy1, 'VD1') >>> Screen layout, file: VMS_SMG_067.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'K' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-262 vms_smg.put_line_wide() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! ||AAVVDD11 || ! 5! |*LMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 4, 3) >>> >>> # put line on virtual display - graphics >>> status = vms_smg.put_line_wide (vtdpy1, 'qnx', None, None, None, \ ... None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Screen layout, file: VMS_SMG_068.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'k' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! ||AAVVDD11 || ! 5! |LLMNOPQRST| ! 6! ||aabb--++|||| ! 7! |*lmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 10-SEP-2000 ZE. Python for OpenVMS -Reference Manual PAGE 2-263 vms_smg.put_status_line() routine ------------------------------------------------------------------------ 2.5.63 PUT_STATUS_LINE - Output Line of Text to Hardware Status Line Format: status = vms_smg.put_status_line (pasteboard_id, text) Returns: status Condition code as returned from SMG$PUT_STATUS_LINE. Either SS$_NORMAL or SMG$_OPNOTSUP are returned here - all other codes produce a Python exception. Arguments: pasteboard_id The pasteboard containing the hardware status line. text Characters to be written to the hardware status line. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Python for OpenVMS -Reference Manual PAGE 2-264 vms_smg.put_status_line() routine Screen layout, file: VMS_SMG_045.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # put text to status line >>> status = vms_smg.put_status_line (pasteboard_id, \ ... 'Text in the status-line.') >>> Screen layout, file: VMS_SMG_046.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Text in the status-line. +________________________) _+ 10-SEP-2000 ZE. Python for OpenVMS -Reference Manual PAGE 2-265 vms_smg.read_from_display() routine ------------------------------------------------------------------------ 2.5.64 READ_FROM_DISPLAY - Read Text from Display Read a line of text from a virtual display. Format: status, resultant_string, rendition_string = \ vms_smg.read_from_display (display_id, \ [terminator_string], [start_row]) Returns: status Condition code as returned from SMG$READ_FROM_DISPLAY. You need to check it yourself. resultant_string The information read from the virtual display rendition_string Optional bit mask string that controls the video attributes. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. Arguments: display_id Identifier of the virtual display from which to read text. terminator_string String containing a terminator or terminators that end the backward search, thus determining the starting position of the returned string. If terminator-string is omitted, no back searching is performed; the returned string starts with the character at the current cursor position. start_row The row of the virtual display to read from. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> Python for OpenVMS -Reference Manual PAGE 2-266 vms_smg.read_from_display() routine >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 2, 2) >>> >>> # put line on virtual display >>> status = vms_smg.put_line_multi (vtdpy1, 'VTDPY1') >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 3, 2) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_line_multi (vtdpy1, 'qnqxq', None, None, \ Python for OpenVMS -Reference Manual PAGE 2-267 vms_smg.read_from_display() routine ... 0, None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 5, 2) >>> rendition_string = chr(vms_smgdef.SMG_M_BOLD) + \ ... chr(vms_smgdef.SMG_M_REVERSE) + \ ... chr(vms_smgdef.SMG_M_UNDERLINE) >>> # caution - these are control characters that can screw up >>> # a terminal's setting! - use repr() for inspection >>> print repr (rendition_string) '\001\002\010' >>> >>> status = vms_smg.put_line_multi (vtdpy1, 'bru', \ ... rendition_string, None, \ ... 0, 0, vms_smgdef.SMG_M_UP, \ ... vms_smgdef.SMG_C_ASCII) >>> Screen layout, file: VMS_SMG_042.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'k' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |AVTDPY1 | ! 5! |K-+-|- | ! 6! |abcdefghij| ! 7! |*bru | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ The 'b' in the last line appears bold, the 'r' in the last line appears reverse and the 'u' in the last line appears underlined. >>> # read from display ... >>> status, resultant_string, rendition_string = \ ... vms_smg.read_from_display (vtdpy1, None, 5) Python for OpenVMS -Reference Manual PAGE 2-268 vms_smg.read_from_display() routine >>> >>> print status, repr(resultant_string) 1 'kbru ' >>> >>> # WARNING! the 'rendition_string' contains binary values >>> print repr(rendition_string) '\000\001\002\010\000\000\000\000\000\000' >>> >>> def show_rendition(rendition_string): ... import string, vms_smgdef ... # loop over the |rendition_string| ... for rendition_char in rendition_string: ... # convert to integer ... rendition_complement = ord(rendition_char) ... # an empty list ... rendition_name = [] ... if (rendition_complement & vms_smgdef.SMG_M_BLINK): ... rendition_name.append ('BLINK') ... if (rendition_complement & vms_smgdef.SMG_M_BOLD): ... rendition_name.append ('BOLD') ... if (rendition_complement & vms_smgdef.SMG_M_REVERSE): ... rendition_name.append ('REVERSE') ... if (rendition_complement & vms_smgdef.SMG_M_UNDERLINE): ... rendition_name.append ('UNDERLINE') ... if (rendition_complement & vms_smgdef.SMG_M_INVISIBLE): ... rendition_name.append ('INVISIBLE') ... # all rendition 'names' in one string ... rendition_text = string.join(rendition_name,',') ... print ord(rendition_char), rendition_text ... >>> show_rendition(rendition_string) 0 1 BOLD 2 REVERSE 8 UNDERLINE 0 0 0 0 0 0 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.65 READ_KEYSTROKE - Read a Single Character Read a keystroke and return that keystroke's terminator code. Format: Python for OpenVMS -Reference Manual PAGE 2-269 vms_smg.read_keystroke() routine status, terminator_code = vms_smg.read_keystroke \ (keyboard_id, [prompt_string], [timeout], \ [display_id], [rendition_set], [rendition_complement]) Returns: status Condition code as returned from SMG$READ_KEYSTROKE. You need to check it yourself. terminator_code Code indicating what character or key terminated the read. Key terminator codes are of the form SMG_K_TRM_keyname. Constants like SMG_K_TRM_F1 are in module 'vms_smgdef'. Arguments: keyboard_id The identifier of the virtual keyboard from which to read. prompt_string The prompt for the read operation. timeout Timeout count. If specified, any character typed before the timeout is returned in the buffer. display_id See the OpenVMS documentation for details. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual keyboard - >>> # use the device name from CREATE_PASTEBOARD >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard (device_name) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (8, 10, vms_smgdef.SMG_M_BORDER, None, None) Python for OpenVMS -Reference Manual PAGE 2-270 vms_smg.read_keystroke() routine >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 3, 1) >>> Screen layout, file: VMS_SMG_063.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |* | ! 6! | | ! 7! | | ! 8! | | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ >>> # read a single keystroke >>> status, terminator_code = vms_smg.read_keystroke \ ... (keyboard_id, 'IN=', None, vtdpy1) Notice that the Python interpreter does not respond with the prompt ('>>>'). Python for OpenVMS -Reference Manual PAGE 2-271 vms_smg.read_keystroke() routine Screen layout, file: VMS_SMG_064.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |IN=* | ! 6! | | ! 7! | | ! 8! | | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ Enter 'A' into the DECterm. Notice that the Python interpreter returns with the prompt: >>> >>> # check status >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print terminator_code, chr(terminator_code) 65 A >>> >>> # make another read >>> status, terminator_code = vms_smg.read_keystroke \ ... (keyboard_id, 'IN=>', None, vtdpy1) Again, the Python interpreter does not respond with a prompt ('>>>'). (no screenshot here, 'IN2=' is just placed in the next line) Hit the [PF1] key on the keypad. Again, the Python interpreter comes back: >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion Python for OpenVMS -Reference Manual PAGE 2-272 vms_smg.read_keystroke() routine >>> >>> print terminator_code, vms_smgdef.SMG_K_TRM_PF1 256 256 >>> 10-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.66 READ_STRING - Read String Read a string from a virtual keyboard. Format: status, resultant_string, \ terminator_code, terminator_string = \ vms_smg.read_string (keyboard_id, [prompt_string], \ [maximum_length], [modifiers], [timeout], \ [terminator_set], [display_id], [initial_string], \ [rendition_set], [rendition_complement]) Returns: status Condition code as returned from SMG$READ_STRING. You need to check it yourself. resultant_string String into which the input line is written. terminator_code Code indicating what character or key terminated the read. Key terminator codes are of the form SMG_K_TRM_keyname. Constants like SMG_K_TRM_F1 are in module 'vms_smgdef'. terminator_string Characters that terminated I/O. These are the actual terminating characters, not the key that was pressed to terminate the I/O. Arguments: keyboard_id The identifier of the virtual keyboard from which to read. prompt_string The prompt for the read operation. maximum_length The maximum number of characters to be read. The maximum valid value for this argument is 512. If omitted, 512 is the default. This is not enforced by the Python interface routine. modifiers Bit mask that specifies optional behavior. Values like TRM_M_TM_CVTLOW are in module 'vms_trmdef'. Python for OpenVMS -Reference Manual PAGE 2-273 vms_smg.read_string() routine timeout Timeout count. If specified, any character typed before the timeout is returned in the buffer. terminator_set Either a mask that specifies which characters are to be treated as terminators (short form) or a descriptor pointing to such a mask (long form). The Python interface uses a Python integer for the short form terminator and a Python string for the long form. @@ This part needs further investigation. display_id See the OpenVMS documentation for details. initial_string Initial character string that is put into the field as if the string has been entered from the keyboard. See the OpenVMS documentation for details. rendition_set Attribute specifier. Bit mask values like SMG_M_BOLD are in module 'vms_smgdef'. rendition_complement Attribute complement specifier. There are no symbolic names available - please see the OpenVMS documentation for details. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual keyboard - >>> # use the device name from CREATE_PASTEBOARD >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard (device_name) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (8, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display Python for OpenVMS -Reference Manual PAGE 2-274 vms_smg.read_string() routine >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 3, 1) >>> Screen layout, file: VMS_SMG_063.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |* | ! 6! | | ! 7! | | ! 8! | | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ >>> # read string >>> status, resultant_string, \ ... terminator_code, terminator_string = \ ... vms_smg.read_string (keyboard_id, 'IN=', \ ... 5, None, None, \ ... None, vtdpy1, 'AB', \ ... None, None) Notice that the Python interpreter does not respond with the prompt ('>>>'). Python for OpenVMS -Reference Manual PAGE 2-275 vms_smg.read_string() routine Screen layout, file: VMS_SMG_065.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |IN=AB* | ! 6! | | ! 7! | | ! 8! | | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ 'AB' is pre-loaded into the input buffer. 'B' is deleted by hitting the [DEL] key. 'C' is entered. Input is terminated by hitting the [PF4] key. Notice that the Python interpreter returns with the prompt: >>> >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print repr(resultant_string) 'AC' >>> print terminator_code, vms_smgdef.SMG_K_TRM_PF4 259 259 >>> print repr(terminator_string) '\033OS' >>> # '\033' is ESC >>> >>> # use a timeout of 3 seconds >>> status, resultant_string, \ ... terminator_code, terminator_string = \ ... vms_smg.read_string (keyboard_id, 'IN=', \ ... 5, None, 3, \ ... None, vtdpy1, 'AB', \ ... None, None) >>> print vms_sys.getmsg (status)[0] %SYSTEM-F-TIMEOUT, device timeout >>> Python for OpenVMS -Reference Manual PAGE 2-276 vms_smg.read_string() routine 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.67 REMOVE_LINE - Remove a Line from a Virtual Display Remove a line from a specified virtual display that was drawn with the vms_smg.draw_line() or vms_smg.draw_rectangle() routines. Format: None = vms_smg.remove_line (display_id, \ start_row, start_column, \ end_row, end_column) Returns: None Arguments: display_id Virtual Display from which to remove the line. start_row The row number at which to begin removing the line. start_column The column number at which to begin removing the line. end_row The row number at which to begin removing the line. end_column The column number at which to begin removing the line. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) Python for OpenVMS -Reference Manual PAGE 2-277 vms_smg.remove_line() routine >>> >>> # draw on virtual display >>> vms_smg.draw_rectangle (vtdpy1, 1, 1, 4, 4) >>> vms_smg.draw_rectangle (vtdpy1, 2, 2, 4, 5) >>> Screen layout, file: VMS_SMG_020.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position, also corner character V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |*--+ | ! 4! ||+-++ | ! 5! ||| || | ! 6! |++-++ | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # remove a single line >>> vms_smg.remove_line (vtdpy1, 1, 4, 4, 4) >>> Screen layout, file: VMS_SMG_047.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position, also corner character V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-278 vms_smg.remove_line() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |*--+ | ! 4! ||+--+ | ! 5! ||| | | ! 6! |++--+ | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.68 REPAINT_LINE - Repaint One or More Lines on the Current Pasteboard Format: None = vms_smg.repaint_line (pasteboard_id, \ start_row, [number_of_lines]) Returns: None Arguments: pasteboard_id The pasteboard associated with the physical screen to be repainted. start_row The pasteboard row number to start repainting. number_of_lines Number of contiguous lines to repaint. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> Python for OpenVMS -Reference Manual PAGE 2-279 vms_smg.repaint_line() routine >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Send 2 broadcasts to the terminal device from another process: $ reply /terminal= _FTA23: - "BRDCST1 ===== ===== ===== ===== ===== ===== " $ reply /terminal= _FTA23: - "BRDCST2 ===== ===== ===== ===== ===== ===== " Python for OpenVMS -Reference Manual PAGE 2-280 vms_smg.repaint_line() routine Screen layout, file: VMS_SMG_048.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! | | ! 4! | | ! 5!Reply received on NODE fr ! 6!BRDCST1 ===== ===== ===== ! 7! | | ! 8! +----------+ ! 9!Reply received on NODE fr ! 10!BRDCST2 ===== ===== ===== ! 11!* ! 12! ! V V 24! ! +________________________) _+ >>> # cause the specified lines to be redrawn >>> vms_smg.repaint_line (pasteboard_id, 6, 4) >>> Screen layout, file: VMS_SMG_049.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5!Reply received on NODE fr ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! 10!BRDCST2 ===== ===== ===== ! 11!* ! 12! ! V V 24! ! +________________________) _+ Notice that pasteboard lines 6 through 9 have been redrawn. 11-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-281 vms_smg.repaint_screen() routine 2.5.69 REPAINT_SCREEN - Repaint Current Pasteboard Format: None = vms_smg.repaint_screen (pasteboard_id) Returns: None Arguments: pasteboard_id The pasteboard to be repainted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-282 vms_smg.repaint_screen() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Send 2 broadcasts to the terminal device from another process: $ reply /terminal= _FTA23: - "BRDCST1 ===== ===== ===== ===== ===== ===== " $ reply /terminal= _FTA23: - "BRDCST2 ===== ===== ===== ===== ===== ===== " Screen layout, file: VMS_SMG_048.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! | | ! 4! | | ! 5!Reply received on NODE fr ! 6!BRDCST1 ===== ===== ===== ! 7! | | ! 8! +----------+ ! 9!Reply received on NODE fr ! 10!BRDCST2 ===== ===== ===== ! 11!* ! 12! ! V V 24! ! +________________________) _+ >>> # cause the pasteboard to be redrawn >>> vms_smg.repaint_screen (pasteboard_id) >>> Python for OpenVMS -Reference Manual PAGE 2-283 vms_smg.repaint_screen() routine Screen layout, file: VMS_SMG_001.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Notice that the entire pasteboard has been redrawn. 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.70 REPASTE_VIRTUAL_DISPLAY - Repaste Virtual Display Repastes a virtual display on the pasteboard and changes the pasting order. Use vms_smg.move_virtual_display() to move the location and keep the pasting order of the display within the pasteboard. Format: vms_smg.repaste_virtual_display (display_id, pasteboard_id, \ pasteboard_row, pasteboard_column, [top_display_id]) Returns: None Arguments: display_id Virtual display to be moved pasteboard_id Pasteboard on which the virtual display is to be moved. pasteboard_row Specifies the row of the pasteboard that is to contain row 1 of the new location of the specified virtual display. pasteboard_column Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. top_display_id Identifier of the virtual display under which the moving Python for OpenVMS -Reference Manual PAGE 2-284 vms_smg.repaste_virtual_display() routine display_id will be pasted. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display 1 >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 1 >>> status = vms_smg.put_chars (vtdpy1, 'V1', 0, 0) >>> >>> # create virtual display 2 >>> status, vtdpy2 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display 2 >>> status = vms_smg.put_chars (vtdpy2, 'V2', 0, 0) >>> >>> # paste virtual display 1 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # paste virtual display 2 >>> status = vms_smg.paste_virtual_display \ ... (vtdpy2, pasteboard_id, 5, 7, None) >>> Screen layout, file: VMS_SMG_003.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / column omitted Python for OpenVMS -Reference Manual PAGE 2-285 vms_smg.repaste_virtual_display() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1 | ! 4! | +----------+ ! 5! | |V2* | ! 6! | | | ! 7! | | | ! 8! +-| | ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) =+ >>> # now repaste virtual display 1 >>> vms_smg.repaste_virtual_display (vtdpy1, pasteboard_id, 3, 10) >>> Screen layout, file: VMS_SMG_005.JPG 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |V1* | ! 4! +--| | ! 5! |V2| | ! 6! | | | ! 7! | | | ! 8! | +----------+ ! 9! | | ! 10! +----------+ ! 11! ! V V 24! ! +________________________) =+ Notice that the display 1 is at a new location, now occludes virtual display 2 and the cursor position has changed, too (which does not happen when using vms_smg.move_virtual_display). 11-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-286 vms_smg.restore_physical_screen() routine 2.5.71 RESTORE_PHYSICAL_SCREEN - Restore Physical Pasteboard Rewrite the pasteboard image as it was at the time the vms_smg.save_physical_screen() routine was called. Format: None = vms_smg.restore_physical_screen (pasteboard_id, display_id) Returns: None Arguments: pasteboard_id The pasteboard to be restored. display_id The virtual display created by the SAVE_PHYSICAL_SCREEN routine. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_001.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-287 vms_smg.restore_physical_screen() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # save part of the physical screen >>> display_id = vms_smg.save_physical_screen (pasteboard_id, 4, 7) >>> Notice that the screen range has been blanked: Screen layout, file: VMS_SMG_052.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! | | ! 4!* ! 5! ! 6! ! 7! ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Send 2 broadcasts to the terminal device from another process: $ reply /terminal= _FTA23: - "BRDCST1 ===== ===== ===== ===== ===== ===== " $ reply /terminal= _FTA23: - "BRDCST2 ===== ===== ===== ===== ===== ===== " Screen layout, file: VMS_SMG_053.JPG Python for OpenVMS -Reference Manual PAGE 2-288 vms_smg.restore_physical_screen() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! | | ! 4! ! 5!Reply received on NODE fr ! 6!BRDCST2 ===== ===== ===== ! 7! ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ Notice that the first broadcast has scrolled away. >>> # restore (part of) the pasteboard >>> vms_smg.restore_physical_screen (pasteboard_id, display_id) >>> Screen layout, file: VMS_SMG_001.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |* | ! 4! | | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.72 RETURN_CURSOR_POS - Return Cursor Position Return the current virtual cursor position in a specified virtual display. Format: Python for OpenVMS -Reference Manual PAGE 2-289 vms_smg.return_cursor_pos() routine start_row, start_column = vms_smg.return_cursor_pos (display_id) Returns: start_row The virtual cursor's current row position within the specified virtual display. start_column The virtual cursor's current column position within the specified virtual display. Arguments: display_id The virtual display whose current virtual cursor position you are requesting. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, 'VTDPY1', 0, 0) >>> >>> # write to virtual display - graphics >>> status = vms_smg.put_chars (vtdpy1, 'qnqxq', 2, 2, 0, \ ... None, None, vms_smgdef.SMG_C_SPEC_GRAPHICS) >>> Python for OpenVMS -Reference Manual PAGE 2-290 vms_smg.return_cursor_pos() routine Screen layout, file: VMS_SMG_034.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |VTDPY1 | ! 4! | -+-|-* | ! 5! | | ! 6! | | ! 7! | | ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # report position >>> start_row, start_column = vms_smg.return_cursor_pos (vtdpy1) >>> print start_row, start_column 2 7 >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.73 RING_BELL - Ring the Terminal Bell or Buzzer The bell/buzzer will sound on any pasteboard that the virtual display is pasted to. If the display is not pasted, no sound will be emitted. Format: None = vms_smg.ring_bell (display_id, [number_of_times]) Returns: None Arguments: display_id The virtual display for which the bell or buzzer sounds. Python for OpenVMS -Reference Manual PAGE 2-291 vms_smg.ring_bell() routine number_of_times The number of times the bell or buzzer is sounded. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> >>> # sound 1x >>> vms_smg.ring_bell (display_id) >>> >>> # sound 3x >>> vms_smg.ring_bell (display_id, 3) >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.74 SAVE_PHYSICAL_SCREEN - Save Physical Screen Save the contents of the pasteboard so that a later call to vms_smg.restore_physical_screen() can restore it. Format: display_id = vms_smg.save_physical_screen (pasteboard_id, \ [desired_start_row], [desired_end_row]) Returns: display_id The display identifier of the display created to contain the contents of the specified pasteboard. Python for OpenVMS -Reference Manual PAGE 2-292 vms_smg.save_physical_screen() routine Arguments: pasteboard_id The pasteboard whose contents are to be saved. desired_start_row The first row to be saved. desired_end_row The last row to be saved. At least 2 rows must be specified. Examples: See the examples section of the vms_smg.restore_physical_screen() routine. 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.75 SAVE_VIRTUAL_DISPLAY - Save the Virtual Display to a File Save the contents of a virtual display and store them in a file. It can later be retrieved with vms_smg.load_virtual_display(). Format: None = vms_smg.save_virtual_display (display_id, [filespec]) Returns: None Arguments: display_id Virtual display to be saved. filespec The file specification of the file in which the specified virtual display is saved. A new file is created each time this routine is called. If 'filespec' is omitted, the default file specification is SMGDISPLY.DAT. You must use OpenVMS format for the file specification. Examples: See the examples section of the vms_smg.load_virtual_display() routine. 11-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-293 vms_smg.scroll_display_area() routine 2.5.76 SCROLL_DISPLAY_AREA - Scroll Display Area Scroll a rectangular region of a virtual display. A default scrolling area can be defined with the vms_smg.set_display_scroll_region() routine. Format: None = vms_smg.scroll_display_area (display_id, \ [start_row], [start_column], \ [height], [width], \ [direction], [count]) Returns: None Arguments: display_id Virtual display in which scrolling takes place. start_row The first row of the scrolling region. If omitted, row 1 is used. start_column The first column of the scrolling region. If omitted, column 1 is used. height The number of rows in the scrolling region. width The number of columns in the scrolling region. direction The direction to scroll. Bit mask values like SMG_M_UP are defined in module 'vms_smgdef'. count The number of lines or columns to scroll. If omitted, one row or column is scrolled. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) Python for OpenVMS -Reference Manual PAGE 2-294 vms_smg.scroll_display_area() routine >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # scroll down 2 lines in a 4x5 area at (2,3) >>> vms_smg.scroll_display_area (vtdpy1, \ ... 2, 3, # at: row 2, column 3 ('c') ... 4, 5, # 4 rows, 5 columns big ... vms_smgdef.SMG_M_DOWN, 2) # 2 rows down >>> Python for OpenVMS -Reference Manual PAGE 2-295 vms_smg.scroll_display_area() routine Screen layout, file: VMS_SMG_056.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and space V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |AB* HIJ| ! 5! |KL RST| ! 6! |abCDEFGhij| ! 7! |klMNOPQrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # scroll right 4 lines in a 7x3 area at (2,2) >>> vms_smg.scroll_display_area (vtdpy1, \ ... 2, 2, # row 2, column 2 ('B') ... 3, 7, # 3 rows, 7 columns ... vms_smgdef.SMG_M_RIGHT, 4) # 4 columns right >>> Screen layout, file: VMS_SMG_057.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and SPACE V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-296 vms_smg.scroll_display_area() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |A* B IJ| ! 5! |K L ST| ! 6! |a bCDij| ! 7! |klMNOPQrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # attempt to scroll more columns (4) than the area is wide (3) >>> vms_smg.scroll_display_area (vtdpy1, \ ... 2, 2, # row 2, column 2 ... 7, 3, # 7 rows, 3 columns ... vms_smgdef.SMG_M_RIGHT, 4) # 4 columns right Traceback (innermost last): File "", line 4, in ? vms_smg.error: (1212940, '%SMG-F-INVARG, invalid argument') >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.77 SCROLL_VIEWPORT - Scroll a Display Under a Viewport Scroll a virtual display under its associated viewport. Format: status = vms_smg.scroll_viewport (display_id, \ [direction], [count]) Returns: status Condition code as returned from SMG$SCROLL_VIEWPORT. You must check the status yourself - no exception is created. Arguments: display_id Virtual display to be scrolled. direction Direction specifier. Bit mask values like SMG_M_UP are in module 'vms_smgdef'. Python for OpenVMS -Reference Manual PAGE 2-297 vms_smg.scroll_viewport() routine count Number of rows or columns to scroll. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> >>> # create a viewport >>> status = vms_smg.create_viewport (vtdpy1, 2, 3, 4, 5) >>> The examples section of vms_smg.create_viewport() shows that this has no immediate effect if the virtual display is already pasted. It also shows the contents of the whole virtual display. >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> Screen layout, file: VMS_SMG_009.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-298 vms_smg.scroll_viewport() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |CDEFG| ! 4! |MNOPQ| ! 5! |cdefg| ! 6! |mnopq| ! 7! +-----+ * ! 8! ! V V 24! ! +________________________) _+ >>> # scroll the viewport >>> status = vms_smg.scroll_viewport \ ... (vtdpy1, vms_smgdef.SMG_M_DOWN, 2) >>> >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SMG-S-WINTRUNCFIT, viewport truncated to fit >>> Screen layout, file: VMS_SMG_050.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |34567| ! 4! |CDEFG| ! 5! |MNOPQ| ! 6! +-----+ ! 7! * ! 8! ! V V 24! ! +________________________) _+ >>> # scroll the viewport again >>> status = vms_smg.scroll_viewport \ ... (vtdpy1, vms_smgdef.SMG_M_LEFT, 2) >>> >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> Python for OpenVMS -Reference Manual PAGE 2-299 vms_smg.scroll_viewport() routine Screen layout, file: VMS_SMG_051.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +-----+ ! 3! |56789| ! 4! |EFGHI| ! 5! |OPQRS| ! 6! +-----+ ! 7! * ! 8! ! V V 24! ! +________________________) _+ >>> status = vms_smg.scroll_viewport (vtdpy1, vms_smgdef.SMG_M_UP, 999) >>> print vms_sys.getmsg (status)[0] %SMG-S-WINTRUNCFIT, viewport truncated to fit >>> # (the viewport has disappeared) >>> # try to scroll the viewport of a non-existing display >>> status = vms_smg.scroll_viewport (vtdpy1+99, vms_smgdef.SMG_M_UP, 1) >>> print vms_sys.getmsg (status)[0] %SMG-F-INVDIS_ID, invalid display-id >>> >>> # delete the viewport for the next demo >>> vms_smg.delete_viewport (vtdpy1) >>> # try to change a non-existing viewport >>> status = vms_smg.scroll_viewport (vtdpy1, vms_smgdef.SMG_M_UP, 1) >>> print vms_sys.getmsg (status)[0] %SMG-F-NO_WINASSOC, no viewport has been associated with the display >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-300 vms_smg.set_cursor_abs() routine 2.5.78 SET_CURSOR_ABS - Set Absolute Cursor Position Move the virtual cursor to the specified position in a virtual display. Format: None = vms_smg.set_cursor_abs (display_id, \ [start_row], [start_column]) Returns: None Arguments: display_id Virtual display in which to set the virtual cursor position. start_row The row position to which the virtual cursor moves. start_column The column position to which the virtual cursor moves. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Python for OpenVMS -Reference Manual PAGE 2-301 vms_smg.set_cursor_abs() routine Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # move cursor over '1' >>> vms_smg.set_cursor_abs (vtdpy1, 1, 1) >>> >>> # move cursor over '3' >>> vms_smg.set_cursor_abs (vtdpy1, 1, 3) >>> >>> # move cursor over 'b' >>> vms_smg.set_cursor_abs (vtdpy1, 4, 2) >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.79 SET_CURSOR_MODE - Set the Cursor Mode Turn the physical cursor on or off and select jump or smooth scrolling. Format: None = vms_smg.set_cursor_mode (pasteboard_id, flags) Returns: None Python for OpenVMS -Reference Manual PAGE 2-302 vms_smg.set_cursor_mode() routine Arguments: pasteboard_id Pasteboard identifier. flags Bit mask that specifies scrolling and cursor attributes. Values like SMG_M_CURSOR_OFF are in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-303 vms_smg.set_cursor_mode() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # turn the cursor off >>> vms_smg.set_cursor_mode (pasteboard_id, \ ... vms_smgdef.SMG_M_CURSOR_OFF) >>> The (block) cursor is no longer visible. >>> # turn the cursor back on >>> vms_smg.set_cursor_mode (pasteboard_id, \ ... vms_smgdef.SMG_M_CURSOR_ON) >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.80 SET_CURSOR_REL - Move Cursor Relative Move the virtual cursor the specified number of rows and columns from the current virtual cursor position in a virtual display. Format: None = vms_smg.set_cursor_rel (display_id, \ [delta_row], [delta_column]) Returns: None Arguments: display_id Virtual display in which to move the virtual cursor. delta_row The number of rows to move the virtual cursor. Python for OpenVMS -Reference Manual PAGE 2-304 vms_smg.set_cursor_rel() routine delta_column The number of columns to move the virtual cursor. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-305 vms_smg.set_cursor_rel() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # move cursor over '1' # X Y >>> vms_smg.set_cursor_rel (vtdpy1, -4, -9) >>> >>> # move cursor over '3' >>> vms_smg.set_cursor_rel (vtdpy1, None, 2) >>> >>> # move cursor over 'b' >>> vms_smg.set_cursor_rel (vtdpy1, 3, -1) >>> >>> # try to move outside the virtual display >>> vms_smg.set_cursor_rel (vtdpy1, 99) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212972, '%SMG-F-INVROW, invalid row') >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.81 SET_DISPLAY_SCROLL_REGION - Create Display Scrolling Region Create a virtual scrolling region in a virtual display. Explicit scrolling can be done with the vms_smg.scroll_display_area() routine. Format: None = vms_smg.set_display_scroll_region \ (display_id, [start_row], [end_row]) Returns: None Arguments: Python for OpenVMS -Reference Manual PAGE 2-306 vms_smg.set_display_scroll_region() routine display_id Virtual display in which scrolling takes place. start_row The first line of the virtual scrolling region. end_row The last line of the virtual scrolling region. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-307 vms_smg.set_display_scroll_region() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # set a scrolling region >>> vms_smg.set_display_scroll_region (vtdpy1, 2, 4) >>> >>> # change cursor position >>> vms_smg.set_cursor_abs (vtdpy1, 3, 4) >>> >>> # put lines on virtual display >>> status = vms_smg.put_line (vtdpy1, 'Line1Line1') >>> status = vms_smg.put_line (vtdpy1, 'Line2Line2') >>> status = vms_smg.put_line (vtdpy1, 'Line3Line3') >>> status = vms_smg.put_line (vtdpy1, 'Line4Line4') >>> Screen layout, file: VMS_SMG_055.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 'L' V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-308 vms_smg.set_display_scroll_region() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |Line2Line2| ! 5! |Line3Line3| ! 6! |*ine4Line4| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.82 SET_KEYPAD_MODE - Set Keypad Mode Set the terminal's numeric keypad to either numeric or applications mode. Format: None = vms_smg.set_keypad_mode (keyboard_id, [flags]) Returns: None Arguments: keyboard_id The identifier of the virtual keyboard whose mode is to be changed. flags Mask that specifies whether the keypad is to be in applications or numeric mode. Value SMG_M_KEYPAD_APPLICATION is in module 'vms_smgdef'. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ Python for OpenVMS -Reference Manual PAGE 2-309 vms_smg.set_keypad_mode() routine ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual keyboard - >>> # use the device name from CREATE_PASTEBOARD >>> keyboard_id, resultant_filespec = \ ... vms_smg.create_virtual_keyboard (device_name) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (8, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # put characters on virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> >>> # position cursor >>> vms_smg.set_cursor_abs (vtdpy1, 3, 1) >>> Screen layout, file: VMS_SMG_063.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-310 vms_smg.set_keypad_mode() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |* | ! 6! | | ! 7! | | ! 8! | | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ >>> # read a single keystroke >>> status, terminator_code = vms_smg.read_keystroke \ ... (keyboard_id, 'IN=', None, vtdpy1) Notice that the Python interpreter does not respond with the prompt ('>>>'). Screen layout, file: VMS_SMG_064.JPG 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |IN=* | ! 6! | | ! 7! | | ! 8! | | ! 9! | | ! 10! | | ! 11! +----------+ ! 12! ! V V 24! ! +________________________) _+ Enter [KP7] into the DECterm. Notice that the Python interpreter returns with the prompt: Python for OpenVMS -Reference Manual PAGE 2-311 vms_smg.set_keypad_mode() routine >>> >>> # check status >>> import vms_sys >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print terminator_code, vms_smgdef.SMG_K_TRM_KP7 267 267 >>> >>> # change keypad to numeric mode >>> vms_smg.set_keypad_mode (keyboard_id, 0) >>> >>> # make another read >>> status, terminator_code = vms_smg.read_keystroke \ ... (keyboard_id, 'IN2=', None, vtdpy1) Again, the Python interpreter does not respond with a prompt ('>>>'). (no screenshot here, 'IN2=' is just placed in the next line) Hit [KP7] key on the keypad. Again, the Python interpreter comes back: >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completio >>> >>> print terminator_code, chr(terminator_code) 55 7 >>> >>> # change keypad back to application mode >>> vms_smg.set_keypad_mode (keyboard_id, \ ... vms_smgdef.SMG_M_KEYPAD_APPLICATION) >>> >>> # make another read >>> status, terminator_code = vms_smg.read_keystroke \ ... (keyboard_id, 'IN3=', None, vtdpy1) Again, the Python interpreter does not respond with a prompt ('>>>'). (no screenshot here, 'IN3=' is just placed in the next line) Hit [KP7] key on the keypad. Again, the Python interpreter comes back: Python for OpenVMS -Reference Manual PAGE 2-312 vms_smg.set_keypad_mode() routine >>> >>> print vms_sys.getmsg (status)[0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print terminator_code, vms_smgdef.SMG_K_TRM_KP7 267 267 >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.83 SET_PHYSICAL_CURSOR - Set Cursor on Physical Screen Move the physical cursor to the specified position on the pasteboard. Format: None = vms_smg.set_physical_cursor (pasteboard_id, \ pasteboard_row, pasteboard_column) Returns: None Arguments: pasteboard_id The pasteboard whose physical cursor is to move. pasteboard_row The row to which the physical cursor moves. pasteboard_column The column to which the physical cursor moves. Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create virtual display >>> status, vtdpy1 = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> Python for OpenVMS -Reference Manual PAGE 2-313 vms_smg.set_physical_cursor() routine >>> # paste virtual display >>> status = vms_smg.paste_virtual_display \ ... (vtdpy1, pasteboard_id, 3, 5, None) >>> >>> # write to virtual display >>> status = vms_smg.put_chars (vtdpy1, '1234567890', 1, 1) >>> status = vms_smg.put_chars (vtdpy1, 'ABCDEFGHIJ', 2, 1) >>> status = vms_smg.put_chars (vtdpy1, 'KLMNOPQRST', 3, 1) >>> status = vms_smg.put_chars (vtdpy1, 'abcdefghij', 4, 1) >>> status = vms_smg.put_chars (vtdpy1, 'klmnopqrst', 5, 1) >>> Screen layout, file: VMS_SMG_008.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position and 't' V) = some rows / columns omitted 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrs*| ! 8! +----------+ ! 9! ! V V 24! ! +________________________) _+ >>> # move cursor outside the virtual display >>> vms_smg.set_physical_cursor (pasteboard_id, 9, 17) >>> Screen layout, file: VMS_SMG_058.JPG legend ! = left / right screen margin _ = top/bottom screen margin | = left / right virtual display margin - = top/bottom virtual display margin * = cursor position V) = some rows / columns omitted Python for OpenVMS -Reference Manual PAGE 2-314 vms_smg.set_physical_cursor() routine 1 2 8 12345678901234567890123 0 +________________________) _+ 1! ! 2! +----------+ ! 3! |1234567890| ! 4! |ABCDEFGHIJ| ! 5! |KLMNOPQRST| ! 6! |abcdefghij| ! 7! |klmnopqrst| ! 8! +----------+ ! 9! * ! 10! ! V V 24! ! +________________________) _+ >>> # try to move cursor outside the pasteboard >>> vms_smg.set_physical_cursor (pasteboard_id, 9, 99) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212948, '%SMG-F-INVCOL, invalid column') >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 2.5.84 UNPASTE_VIRTUAL_DISPLAY - Remove a Virtual Display Remove virtual display from pasteboard. Format: status = vms_smg.unpaste_virtual_display \ (display_id, pasteboard_id) Returns: status Condition code as returned from SMG$PASTE_VIRTUAL_DISPLAY. Either SS$_NORMAL or SMG$_BATWAS_ON are returned here - all other codes produce a Python exception. (The latter code is not mentioned in the documentation of OpenVMS VAX V6.1). Arguments: display_id Virtual display to be removed. pasteboard_id Pasteboard from which the virtual display is to be removed Python for OpenVMS -Reference Manual PAGE 2-315 vms_smg.unpaste_virtual_display() routine Examples: >>> import vms_smg >>> import vms_smgdef >>> # create a new DECwindows terminal using SMG >>> status, pasteboard_id, number_of_pasteboard_rows, \ ... number_of_pasteboard_columns, type_of_terminal, \ ... device_name = vms_smg.create_pasteboard \ ... (None, vms_smgdef.SMG_M_WORKSTATION) >>> >>> # create a virtual display >>> status, display_id = vms_smg.create_virtual_display \ ... (5, 10, vms_smgdef.SMG_M_BORDER, None, None) >>> >>> # paste the virtual display >>> status = vms_smg.paste_virtual_display \ ... (display_id, pasteboard_id, 3, 5, None) >>> The result can be seen in the examples section of vms_smg.paste_virtual_display(). >>> # unpaste this display >>> status = vms_smg.unpaste_virtual_display \ ... (display_id, pasteboard_id) >>> The screen is empty, again. >>> # trying to unpaste an unpasted virtual display is an error >>> status = vms_smg.unpaste_virtual_display \ ... (display_id, pasteboard_id) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1213044, '%SMG-F-NOTPASTED, given display is not\ pasted to given pasteboard') >>> ---------------------------------------- >>> status = vms_smg.unpaste_virtual_display \ ... (display_id, 299) Traceback (innermost last): File "", line 1, in ? vms_smg.error: (1212964, '%SMG-F-INVPAS_ID, invalid pasteboard-id') >>> >>> status = vms_smg.unpaste_virtual_display \ ... (99, pasteboard_id) Traceback (innermost last): File "", line 1, in ? Python for OpenVMS -Reference Manual PAGE 2-316 vms_smg.unpaste_virtual_display() routine vms_smg.error: (1212956, '%SMG-F-INVDIS_ID, invalid display-id') >>> 11-SEP-2000 ZE. ------------------------------------------------------------------------ 11-SEP-2000 ZE. (VMS_SMG.HTML) Python for OpenVMS -Reference Manual PAGE 2-317 vms_sys module 2.6 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: - ADD_HOLDER - Add Holder Record to Rights Database - ADD_IDENT - Add Identifier to Rights Database - ADD_PROXY - Add or Modify Proxy - ASCEFC - Associate Common Event Flag Cluster - 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 - BRKTHRUW - Breakthrough and Wait - CANWAK - Cancel Wakeup - CLREF - Clear Event Flag - CRELNM - Create Logical Name - CRELNT - Create Logical Name Table - CREPRC - Create Process - DACEFC - Disassociate Common Event Flag Cluster - DASSGN - Deassign I/O Channel - DELETE_INTRUSION - Delete Intrusion Records - DELETE_PROXY - Delete or Modify Proxy - DELLNM - Delete Logical Name - DELPRC - Delete Process - DEQ - Dequeue Lock Request - DEVICE_SCAN - Scan for Devices - DISMOU - Dismount Volume - DISPLAY_PROXY - Display Proxy Information - DLCEFC - Delete Common Event Flag Cluster - ENQW - Enqueue Lock Request - FILESCAN - Scan String for File Specification - FIND_HELD - Find Identifiers Held by User - FIND_HOLDER - Find Holder of Identifier - FINISH_RDB - Terminate Rights Database Context - FORCEX - Force Exit - FORMAT_ACL - Format Access Control List Entry - GETJPIW - Get Job/Process Information - GETMSG - Get Message - GETQUIW - Get Queue Information - GETTIM - Returns the current system time in a 64-bit format - GETUAI - Get User Authorization Information - GETUTC - Get UTC Time Python for OpenVMS -Reference Manual PAGE 2-318 vms_sys module - GET_SECURITY - Get Security Characteristics - GRANTID - Grant Identifier to Process - HIBER - Hibernate - IDTOASC - Translate Identifier to Identifier Name - INIT_VOL - Initialize Volume - MOD_HOLDER - Modify Holder Record in Rights Database - MOD_IDENT - Modify Identifier in Rights Database - MOUNT - Mount Volume - NUMTIM - Convert Binary Time to Numeric Time - NUMUTC - Convert UTC Time to Numeric Components - PARSE_ACL - Parse Access Control List Entry - PERSONA_ASSUME - Assume Persona - PERSONA_CREATE - Create Persona - PERSONA_DELETE - Delete Persona - PROCESS_SCAN - Process Scan - PURGWS - Purge Working Set - READEF - Read Event Flags - REM_HOLDER - Remove Holder Record from Rights Database - REM_IDENT - Remove Identifier from Rights Database - RESUME - Resume Process - REVOKID - Revoke Identifier from Process - SCAN_INTRUSION - Scan Intrusion Database - SCHDWK - Schedule Wakeup - SETDDIR - Set Default Directory - SETDFPROT - Set Default File Protection - SETEF - Set Event Flag - SETPRI - Set Priority - SETPRN - Set Process Name - SETPRN - Set Privilege - SETSWM - Set Process Swap Mode - SETUAI - Set User Authorization Information - SET_RESOURCE_DOMAIN - Set Resource Domain - SET_SECURITY - Set Security Characteristics - SHOW_INTRUSION - Show Intrusion Information - SNDJBCW - Send to Job Controller - SUBSYSTEM - Subsystem - SUSPND - Suspend Process - TIMCON - Time Converter - TRNLNM - Translate Logical Name - VERIFY_PROXY - Verify a Proxy - WAITFR - Wait for Single Event Flag - WAKE - Wake Process from Hibernation - WFLAND - Wait for Logical AND of Event Flags - WFLOR - Wait for Logical OR of Event Flags ------------------------------------------------------------------------ 2.6.1 ADD_HOLDER - Add Holder Record to Rights Database Adds a specified holder record to a target identifier. Format: Python for OpenVMS -Reference Manual PAGE 2-319 vms_sys.add_holder() routine vms_sys.add_holder (id, holder [,attrib]) Returns: None Arguments: id Target identifier granted to the specified holder. holder Holder identifier that is granted access to the target identifier. The Python function only accepts a tuple of 2 integers - not a quadword represented by a Python long integer. For OpenVMS V6.1 the first element is the holder's UIC identifier, the second element must be 0. Check the system services reference manual for your version of OpenVMS. attrib Attributes to be placed in the record. A holder is granted a specified attribute only if the target identifier has the attribute. Bitmask values are defined in module 'vms_kgbdef'. Examples: UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 DYNAMIC UAF> ! identifiers are not granted to any user >>> import vms_sys >>> import vms_kgbdef >>> id_1 = 0x80010011 >>> id_2 = 0x80010012 >>> uic_system = 0x10004 >>> attributes = vms_kgbdef.KGB_M_DYNAMIC + vms_kgbdef.KGB_M_RESOURCE >>> vms_sys.add_holder (id_1, (uic_system,0), attributes) >>> # nothing is returned - system service succeded UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE UAF> ! DYNAMIC attribute not available !!! >>> # no attributes to be assigned - argument 3 = (0 or None) Python for OpenVMS -Reference Manual PAGE 2-320 vms_sys.add_holder() routine >>> vms_sys.add_holder (id_2, (uic_system,0), None) UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 DYNAMIC Holder Attributes SYSTEM UAF> ! empty ------------------------!!!!!!!! >>> # identifier has already been assigned and argument 3 left off >>> vms_sys.add_holder (id_1, (uic_system,0) ) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8748, '%SYSTEM-F-DUPIDENT, duplicate identifier') >>> >>> id_x = 0x80012345 # identifier value has no text assigned >>> vms_sys.add_holder (id_x, (uic_system,0), attributes) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> uic_x = 0x300003 # UIC has no text assigned >>> vms_sys.add_holder (id_1, (uic_x,0), attributes) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> vms_sys.add_holder (id_1, uic_system, attributes) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - must be a tuple of 2 integers >>> vms_sys.add_holder (id_1, (uic_system,0,0), attributes) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - must be a tuple of 2 integers >>> vms_sys.add_holder (id_1, ('X',0), attributes) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - tuple-element:0 is not an integer >>> vms_sys.add_holder (id_1, (uic_system,'X'), attributes) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - tuple-element:1 is not an integer >>> 27-SEP-1998 ZE. Python for OpenVMS -Reference Manual PAGE 2-321 vms_sys.add_ident() routine ------------------------------------------------------------------------ 2.6.2 ADD_IDENT - Add Identifier to Rights Database Adds the specified identifier to the rights database. Format: resid = vms_sys.add_ident (name [,id] [,attrib]) Returns: resid Identifier value assigned by the system. Arguments: name Identifier name to be added to the rights database. id Identifier to be created. If the id argument is omitted or 'None', ADD_IDENT selects a unique available value from the general identifier space and returns it in 'resid' (resid is always returned by the Python function). attrib Attributes to be placed in the identifier's record. Bitmask values are defined in module 'vms_kgbdef'. Examples: >>> import vms_sys >>> vms_sys.add_ident ('NEW_ID_1') -2147418093 >>> hex (-2147418093) '0x80010013' >>> UAF> show /identifier /full NEW_ID_1 Name Value Attributes NEW_ID_1 %X80010013 UAF> >>> import vms_kgbdef >>> attrib = vms_kgbdef.KGB_M_DYNAMIC >>> resid = vms_sys.add_ident ('NEW_ID_2', 0x80010014, attrib) >>> hex (resid) '0x80010014' >>> UAF> show /identifier /full NEW_ID_2 Python for OpenVMS -Reference Manual PAGE 2-322 vms_sys.add_ident() routine Name Value Attributes NEW_ID_2 %X80010014 DYNAMIC UAF> >>> vms_sys.add_ident ('x23456789012345678901234567890123') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8740, '%SYSTEM-F-IVIDENT, invalid identifier format') >>> # name is too long >>> vms_sys.add_ident ('X%X') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8740, '%SYSTEM-F-IVIDENT, invalid identifier format') >>> # bad character in name >>> vms_sys.add_ident ('NEW_ID_2', None, None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name') >>> # name already exists >>> vms_sys.add_ident ('NEW_ID_2X', 0x80010014) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8748, '%SYSTEM-F-DUPIDENT, duplicate identifier') >>> # identifier value (0x80010014) already in use >>> vms_sys.add_ident ('NEW_ID_2X', 'BAD-PARAM') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: id - must be integer or None >>> >>> vms_sys.add_ident ('NEW_ID_2X', None, 'BAD-PARAM') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: attrib - must be integer or None >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.3 ADD_PROXY - Add or Modify Proxy Format: vms_sys.add_proxy (rem_node, rem_user, local_user [,flags]) Returns: Python for OpenVMS -Reference Manual PAGE 2-323 vms_sys.add_proxy() routine None Arguments: rem_node Remote node name. rem_user Remote username. local_user Local user name. It must be known to the local system. flags Functional specification and type of local_user (NOdefault). The bit masks are not available from a separate module ($PRXDEF). Examples: >>> import vms_sys >>> vms_sys.add_proxy ('REMNOD', 'REMUSR', 'NOPRIV') UAF> show /proxy r*::* Default proxies are flagged with (D) REMNOD::REMUSR NOPRIV UAF> >>> PRX_M_DEFAULT = 256 >>> vms_sys.add_proxy ('REM2D', 'REMUSR', 'NOPRIV', PRX_M_DEFAULT) UAF> show /proxy r*::* Default proxies are flagged with (D) REM2D::REMUSR NOPRIV (D) REMNOD::REMUSR NOPRIV UAF> >>> vms_sys.add_proxy ('REM2D', 'REMUSR', 'NOPRIV') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (116311642, '%SECSRV-E-DUPLICATEUSER, username\ already exists in the proxy record') >>> 21-JAN-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-324 vms_sys.ascefc() routine 2.6.4 ASCEFC - Associate Common Event Flag Cluster Associates a named common event flag cluster with a process. Format: vms_sys.ascefc (efn, name [,prot] [,perm] Returns: None Arguments: efn Number of any event flag contained within the desired common event flag cluster. name Name of the common event flag cluster with which to associate. The character string descriptor can be 1 to 15 bytes in length, and each byte may be any 8-bit value. CEF clusters are accessible only to processes having the same UIC group number. prot Protection specifier that allows or disallows access to the common event flag cluster for processes with the same UIC group number as the creating process. The default value 0 specifies that any process with the same UIC group number as the creating process may access the event flag cluster. perm The default value 0 specifies that the cluster is temporary. The value 1 specifies that the cluster is permanent. Examples: >>> import vms_sys @@ ASCEFC not yet (15-SEP-1998) tested >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.5 ASCTIM - Convert Binary Time to ASCII String Format: timbuf = vms_sys.asctim (timadr [,cvtflg]) Returns: Python for OpenVMS -Reference Manual PAGE 2-325 vms_sys.asctim() routine timbuf Converted Date and Time as an ASCII string. Arguments: timadr 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. cvtflg Conversion indicator. Please consult the system services 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 ? TypeError: argument 1: timadr - must be long integer >>> vms_sys.asctim ('string') Traceback (innermost last): File "", line 1, in ? Python for OpenVMS -Reference Manual PAGE 2-326 vms_sys.asctim() routine TypeError: argument 1: timadr - must be long integer >>> # this is only an integer, not a long integer >>> vms_sys.asctim (0x12345) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: timadr - must be long integer >>> # '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 >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.6 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= [' + oct(uic_group)[1:] + ',' + \ ... oct(uic_member)[1:] + ']' >>> print uic_spec UIC= [1,4] Python for OpenVMS -Reference Manual PAGE 2-327 vms_sys.asctoid() routine >>> 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' 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 read-only buffer, 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') >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.7 ASCUTC - Convert UTC to ASCII Format: timbuf = vms_sys.ascutc (utcadr [,cvtflg]) Returns: timbuf ASCII String Arguments: utcadr 128-bit UTC value - a Python long integer cvtflg conversion indicator Python for OpenVMS -Reference Manual PAGE 2-328 vms_sys.ascutc() routine 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 21584378040929278433485881180047287456L >>> print vms_sys.ascutc (utc_tim) 9-JAN-1999 20:01:58.89 >>> print vms_sys.asctim () 9-JAN-1999 20:02:29.97 >>> utc_tim = vms_sys.binutc ('29-FEB-2000 12:34:56.78') >>> print utc_tim 21584378040929278433486240335826187456L >>> print vms_sys.ascutc (utc_tim) 29-FEB-2000 12:34:56.78 >>> print vms_sys.ascutc () 9-JAN-1999 20:03:31.58 >>> print vms_sys.ascutc (None) 9-JAN-1999 20:03:40.65 >>> print vms_sys.ascutc ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: utcadr - must be long integer >>> 09-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.8 BINTIM - Convert ASCII String to Binary Time Format: timadr = vms_sys.bintim (timbuf) Returns: timadr 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Python for OpenVMS -Reference Manual PAGE 2-329 vms_sys.bintim() routine 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 # that means 'string' ----------^^^^^^^^^^^^^^^^ >>> 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 # that means 'string' ----------^^^^^^^^^^^^^^^^ >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.9 BINUTC - Convert ASCII String to UTC Binary Time Format: utcadr = vms_sys.binutc (timbuf) Python for OpenVMS -Reference Manual PAGE 2-330 vms_sys.binutc() routine Returns: utcadr 128-bit UTC value - a Python long integer. 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 21584378040929278433486240335826187456L >>> 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 >>> 09-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.10 BRKTHRUW - Breakthrough and Wait Format: status, iosb = vms_sys.brkthruw ([efn], msgbuf, [sendto], \ [sndtyp], [iosb], [carcon], [flags], [reqid],\ [timout], [astadr], [astprm]) Returns: status Condition value as returned by SYS$BRKTHRUW. Note that this code only tells whether the system service started successfully. The final status code is in the 'iosb'. iosb A 'vmsobj_iosb' object that provides storage for the OpenVMS IOSB (I/O status block). See the description of 'status' Python for OpenVMS -Reference Manual PAGE 2-331 vms_sys.brkthruw() routine above and the 'iosb' argument below. The final status code is in the first word of the IOSB - see the Examples section below. Arguments: efn Event flag number. msgbuf The message string. See the 'OpenVMS System Services Reference Manual' for information about length limits. Look for the argument description and under 'Required Quota'. sendto Name of a single device (terminal) or username to which the message in 'msgbuf' should be sent. sndtyp Type of terminal where the message is to be sent to. Constants like BRK_C_USERNAME are in module 'vms_brkdef'. iosb I/O status block. An IOSB should ALWAYS specified, because this is the only place that contains the status code AFTER the system service completed. 'status', as returned only gives information whether the system service has been started successfully. The Python interface routine expects a vmsobj_iosb object. If the programmer specifies 'None' for the iosb argument, then the interface routine automatically generates a vmsobj_iosb object, passes the OpenVMS IOSB to SYS$BRKTHRUW and returns the object after the system service has completed! carcon Carriage control specifier - see the 'OpenVMS System Services Reference Manual' for details. flags Options for SYS$BRKTHRUW. Bitmasks like BCK_M_CLUSTER are in module 'vms_brkdef'. BRK$V_ERASE_LINES is not in this module - see the manual to understand how to specify the number of lines to erase. requid 'class requester identification' - again, see the manual for details. Constants for class names like BRK_C_GENERAL or BRK_C_MAIL are in module 'vms_brkdef'. timout Timeout value, a Python integer. See the 'OpenVMS System Services Reference Manual' for details about valid values. astadr This argument is ignored. astprm This argument is ignored. Examples: >>> import vms_sys >>> import vms_brkdef Python for OpenVMS -Reference Manual PAGE 2-332 vms_sys.brkthruw() routine >>> timeout = 8 >>> status, iosb = vms_sys.brkthruw \ ... (None # [efn] ... ,'XX\n**' # msgbuf ... ,'ZESSIN' # [sendto] ... ,vms_brkdef.BRK_C_USERNAME # [sndtyp] ... ,None # [iosb] ... ,None # [carcon] ... ,None # [flags] ... ,vms_brkdef.BRK_C_GENERAL # [reqid] ... ,timeout # [timout] ... ) XX ** >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print iosb.w (1, 5, 0, 5) >>> status_final, send_ok, send_tmo, send_nobrdcst = iosb.w or >>> status_final = iosb.w0 >>> print vms_sys.getmsg (status_final) [0] %SYSTEM-S-NORMAL, normal successful completion >>> @@ more examples for BRKTHRUW >>> 15-AUG-1999 ZE. ------------------------------------------------------------------------ 2.6.11 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 (SYS$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 Python for OpenVMS -Reference Manual PAGE 2-333 vms_sys.canwak() routine as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.canwak() raises a 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') Python for OpenVMS -Reference Manual PAGE 2-334 vms_sys.canwak() routine >>> vms_sys.canwak (None,'NONEXPRC') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process') >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.12 CLREF - Clear Event Flag Clears (sets to 0) an event flag in a local or common event flag cluster. Format: setflg = vms_sys.clref (efn) Returns: setflg The system service returns SS$_WASSET or SS$_WASCLR to indicate if the specified event flag was previously set (1) or cleared (0). Any other code returned from the system service results in a Python exception. Arguments: efn Number of the event flag to be cleared. SYS$CLREF uses only the low-order byte. Examples: >>> import vms_sys >>> setflg, state = vms_sys.readef (17) >>> setflg, state (0, -536870909) >>> print state & (2**17) 0 >>> # EFN 17 is clear >>> setflg, state = vms_sys.readef (1) >>> setflg, state (1, -536870909) >>> print state & (2**1) 2 >>> # EFN 1 is set (first EFN is EFN 0!) Python for OpenVMS -Reference Manual PAGE 2-335 vms_sys.clref() routine >>> vms_sys.clref (1) 1 >>> # EFN was set >>> vms_sys.clref (1) 0 >>> # EFN was clear >>> vms_sys.setef (17) 0 >>> # EFN was clear >>> vms_sys.setef (17) 1 >>> # EFN was set >>> setflg, state = vms_sys.readef (1) >>> setflg, state (0, -536739839) >>> print state & (2**1) 0 >>> # EFN 1 is now clear (first EFN is EFN 0!) >>> print state & (2**17) 131072 >>> # EFN 17 is now set >>> setflg = vms_sys.clref (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> setflg, state = vms_sys.readef (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> setflg = vms_sys.setef (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> >>> setflg = vms_sys.clref ('X') Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> >>> # 72 is in a common EFC that was not associated >>> setflg = vms_sys.clref (72) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (564, '%SYSTEM-F-UNASEFC, unassociated event flag cluster') Python for OpenVMS -Reference Manual PAGE 2-336 vms_sys.clref() routine >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.13 CRELNM - Create Logical Name Creates a logical name and specifies its equivalence names. vms_sys.crelnm() does _not_ raise an exception when the SYS$CRELNM routine returns an error. You must check 'status' in the dictionary that is returned. Format: dict = vms_sys.crelnm ([attr] ,tabnam ,lognam \ ,[acmode] ,[itmlst]) Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$CRELNM. 'LNM$_name' Any output items that have been specified in the item-list and that are supported by SYS$CRELNM. It is only put into the dictionary, when SYS$CRELNM returns a success status. Arguments: attr Attributes to be associated with the logical name. See the system services reference manual for details. Bitmask values (LNM_M_name) are available in module 'vms_lnmdef'. tabnam Name of the table in which to create the logical name. lognam Name of the logical name to be created. acmode Access mode to be associated with the logical name. Normally, the access mode is 'maximized'. Because the interface runs in USER mode the logical name would normally get this mode. If the process has SYSNAM privilege, any access mode can be specified! itmlst Item list describing the equivalence names for this logical Python for OpenVMS -Reference Manual PAGE 2-337 vms_sys.crelnm() routine name. You can also specify 'LNM$_TABLE' as an output item. Examples: $ set PROCESS /PRIVILEGE= SYSNAM >>> import vms_sys >>> import vms_lnmdef >>> PSL_C_SUPER = 2 >>> >>> dict = vms_sys.crelnm (vms_lnmdef.LNM_M_CONFINE, \ ... 'LNM$JOB', 'LNM1', PSL_C_SUPER, \ ... ( ('LNM$_STRING', 'VALUE'), \ ... ('LNM$_TABLE', None ) ... ) ... ) >>> >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_TABLE LNM$JOB_814E29C0 status 1 >>> >>> import os >>> os.system ('show logical /job /full LNM1*') (LNM$JOB_814E29C0) [kernel] [shareable] [Quota=(928,2048)] [Protection=(RWCD,RWCD,,)] [Owner=[HOME,ZESSIN]] "LNM1" [super] = "VALUE" 1 <-- return status from os.system() >>> >>> dict = vms_sys.crelnm (vms_lnmdef.LNM_M_CONFINE, \ ... 'LNM$GROUP', 'LNM1', PSL_C_SUPER, \ ... ( ('LNM$_ATTRIBUTES', vms_lnmdef.LNM_M_CONCEALED), \ ... ('LNM$_STRING', 'VALUE1'), \ ... ('LNM$_ATTRIBUTES', 0), \ ... ('LNM$_STRING', 'VALUE2'), \ ... ('LNM$_TABLE', None ) ... ) ... ) >>> >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_TABLE LNM$GROUP_010040 status 1 >>> >>> import os >>> os.system ('show logical /group /full LNM1*') Python for OpenVMS -Reference Manual PAGE 2-338 vms_sys.crelnm() routine (LNM$GROUP_010040) [kernel] [shareable,group] [Protection=(RWCD,R,R,)] [Owner=[HOME,*]] "LNM1" [super] = "VALUE1" [concealed] = "VALUE2" 1 <-- return status from os.system() >>> >>> dict = vms_sys.crelnm (None, \ ... 'LNM$PROCESS', 'LNM1', PSL_C_SUPER, \ ... ( ('LNM$_STRING', 'VALUE'), \ ... ('LNM$_TABLE', None ) ... ) ... ) >>> >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_TABLE LNM$PROCESS_TABLE status 1 >>> >>> dict = vms_sys.crelnm (None, \ ... 'LNM$PROCESS', 'LNM1', PSL_C_SUPER, \ ... ( ('LNM$_STRING', 'VALUE'), \ ... ('LNM$_TABLE', None ) ... ) ... ) >>> >>> status = dict.get('status') >>> status 1585 >>> vms_sys.getmsg (status) ('%SYSTEM-S-SUPERSEDE, logical name superseded', (0, 0, 0, 0)) >>> ------------------------------ >>> dict = vms_sys.crelnm (None, \ ... 'LNM$PROCESS', 'LNM1', PSL_C_SUPER, \ ... ( ('LNM$_STRING', 'VALUE'), \ ... ('LNM$_ACMODE',3), ... ('LNM$_TABLE', None ) ... ) ... ) >>> >>> for k in dict.keys(): ... print k, dict.get(k) ... status 20 >>> >>> status = dict.get('status') >>> vms_sys.getmsg (status) ('%SYSTEM-F-BADPARAM, bad parameter value', (0, 0, 0, 0)) Python for OpenVMS -Reference Manual PAGE 2-339 vms_sys.crelnm() routine >>> @@ more examples for CRELNM 29-NOV-1998 ZE. ------------------------------------------------------------------------ 2.6.14 CRELNT - Create Logical Name Table Creates a process-private or shareable logical name table. Format: status, resnam = vms_sys.crelnt ([attr] ,[quota] \ ,[promsk] ,[tabnam] ,partab ,[acmode]) Returns: status The binary equivalent of the following condition values can be returned: SS$_NORMAL The logical name table already exists. SS$_LNMCREATED The logical name table was created. SS$_SUPERSEDE The logical name table was created and its logical name superseded already existing logical names in the directory table. All other condition codes result in a Python exception. resnam Name of the newly created logical name table, returned by $CRELNT. Arguments: attr Attributes for the creation of the logical name table and to be associated with that table. See the system services reference manual for details. Bitmask values (LNM_M_name) are available in module 'vms_lnmdef'. quota Maximum number of bytes to be allocated for logical names in this table. WARNING: Specifying 0 or None means unlimited quota! promsk UIC-based protection mask for the logical name table. This is a Python int, but the interface limits its size to 16 bit. See the system services reference manual for details how to construct the mask. Python for OpenVMS -Reference Manual PAGE 2-340 vms_sys.crelnt() routine tabnam Name for the logical name table to be created. If None is specified, the system creates an artifical name that is returned in 'resnam'. partab Name of the parent logical name table. acmode Access mode that is to be associated with the logical name table. Normally, the access mode is 'maximized'. Because the interface runs in USER mode the logical name table would normally get this mode. If the process has SYSNAM privilege, any access mode can be specified! Examples: >>> import vms_sys >>> import vms_lnmdef -- need to create non-shared logical name tables in supervisor mode because a user mode table is deleted after image rundown $ set PROCESS /PRIVILEGE= SYSNAM >>> PSL_C_SUPER = 2 >>> status, resnam = vms_sys.crelnt (vms_lnmdef.LNM_M_CONFINE, \ ... 123, None, 'NEW_TABLE', 'LNM$PROCESS_DIRECTORY', \ ... PSL_C_SUPER) >>> status, resnam (1713, 'NEW_TABLE') >>> >>> vms_sys.getmsg (status)[0] '%SYSTEM-S-LNMCREATED, logical name table did not exist; has been created' >>> >>> import sys >>> sys.exit(1) # image rundown $ write sys$output f$message(65537) %RMS-S-NORMAL, normal successful completion $ show logical N* /table=LNM$PROCESS_DIRECTORY /full (LNM$PROCESS_DIRECTORY) [kernel] [directory] [no protection information] "NEW_TABLE" [super,confine,table] = "" [terminal] $ show logical /table=NEW_TABLE /full (NEW_TABLE) [super] [Quota=(123,123)] [no protection information] %SHOW-S-NOTRAN, no translation for logical name * $ ---------------------------------------- Python for OpenVMS -Reference Manual PAGE 2-341 vms_sys.crelnt() routine -- create a shareable logical name table $ set PROCESS /PRIVILEGE= SYSNAM >>> PSL_C_EXEC = 1 >>> status, resnam = vms_sys.crelnt (vms_lnmdef.LNM_M_NO_ALIAS, \ ... 123, None, 'NEW_TABLE_S', 'LNM$SYSTEM_DIRECTORY', \ ... PSL_C_EXEC) >>> status, resnam (1713, 'NEW_TABLE_S') >>> >>> vms_sys.getmsg (status)[0] '%SYSTEM-S-LNMCREATED, logical name table did not exist; has been created' >>> >>> import sys >>> sys.exit(1) # image rundown $ write sys$output f$message(65537) %RMS-S-NORMAL, normal successful completion $ show logical N* /table=LNM$SYSTEM_DIRECTORY /full (LNM$SYSTEM_DIRECTORY) [kernel] [shareable,directory] [Protection=(RWC,RWC,R,R)] [Owner=[G1,SYSTEM]] "NEW_TABLE_S" [exec,no_alias,table] = "" [terminal] $ show logical /table=NEW_TABLE_S /full (NEW_TABLE_S) [exec] [shareable] [Quota=(123,123)] [Protection=(RW,RW,R,R)] [Owner=[HOME,ZESSIN]] %SHOW-S-NOTRAN, no translation for logical name * $ ---------------------------------------- @@ more examples for CRELNT 17-OCT-1998 ZE. ------------------------------------------------------------------------ 2.6.15 CREPRC - Create Process Creates a subprocess or detached process on behalf of the calling process. Format: pidadr = vms_sys.creprc ([image] ,[input] ,[output] ,[error] ,\ [prvadr] ,[quota] ,[prcnam] ,[baspri] ,\ [uic] ,[mbxunt] ,[stsflg] ) Returns: Python for OpenVMS -Reference Manual PAGE 2-342 vms_sys.creprc() routine pidadr Process identification (PID) of the newly created proces. Arguments: image Name of the image to be activated in the newly created process. The image name can have a maximum of 63 characters - this is not enforced by the Python interface to SYS$CREPRC. input Equivalence name to be associated with the logical name SYS$INPUT in the logical name table of the created process. output Equivalence name to be associated with the logical name SYS$OUTPUT in the logical name table of the created process. error Equivalence name to be associated with the logical name SYS$ERROR in the logical name table of the created process. prvadr Privileges to be given to the created process. This must be a Python long integer. Bitmasks values (PRV_M_name) are available in module 'vms_prvdef'. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. quota Process quotas to be established for the created process. The process quota list must be delivered to the Python interface as a 'tuple of tuples' - see the examples section below. See the system services reference manual for explanations about quotas. prcnam Process name to be assigned to the created process. It can be a 1- to 15-character process name string, but the length is not enforced by the Python interface to SYS$CREPRC. baspri Base priority for the new process. uic User identification code (UIC) to be assigned to the created process. This must be a Python integer. Bits 0 - 15 indicate the UIC member number and bits 16 - 31 indicate the UIC group number. mbxunt Unit number of a mailbox to receive a termination message when the created process is deleted. This must be a Python integer, but the system service expects the 'mbxunt' argument to be a 16-bit word containing this number - the Python interface enforces this. stsflg Options selected for the created process. Bitmask values (PRC_M_name) for this argument are in module Python for OpenVMS -Reference Manual PAGE 2-343 vms_sys.creprc() routine 'vms_prcdef'. Examples: >>> import vms_sys >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE','CREPRC_1.COM', ... 'CREPRC_1.LOG', None, None, None, 'CREPRC_1P',3) >>> l_pid 343 >>> import vms_lib >>> vms_lib.getjpi ('JPI$_PRCNAM',l_pid) (343, 'CREPRC_1P') >>> # test done, remove process from system to clean up >>> vms_sys.delprc (l_pid) 343 <-- DELPRC returns the PID - please look up >>> # the description of DELPRC why this is so $ type CREPRC_1.COM $ show process/quota $ wait 01:00:00 $ exit 1 $! ----- $ type CREPRC_1.LOG $ show process/quota 15-OCT-1998 17:43:26.96 User: ZESSIN Process ID: 00000157 Node: HERE Process name: "CREPRC_1P" Process Quotas: Account name: HOME CPU limit: Infinite Direct I/O limit: 100 Buffered I/O byte count quota: 121536 Buffered I/O limit: 100 Timer queue entry quota: 29 Open file quota: 297 Paging file quota: 36492 Subprocess quota: 9 Default page fault cluster: 64 AST quota: 99 Enqueue quota: 4000 Shared file limit: 0 Max detached processes: 0 Max active jobs: 0 $ wait 01:00:00 $! ---------------------------------------- >>> import vms_prcdef >>> l_stsflg = vms_prcdef.PRC_M_DETACH + \ ... vms_prcdef.PRC_M_NOUAF + \ ... vms_prcdef.PRC_M_HIBER >>> process_quota_list = ( ('PQL$_ENQLM',1111), ('PQL$_FILLM', 123) ) >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, process_quota_list, 'CREPRC_1P',3, ... None, None, l_stsflg) # base priority -----^ >>> >>> import vms_lib >>> vms_lib.getjpi ('JPI$_ENQLM', l_pid) Python for OpenVMS -Reference Manual PAGE 2-344 vms_sys.creprc() routine (355, 1111) >>> # ^^^^ >>> vms_lib.getjpi ('JPI$_FILLM', l_pid) (355, 123) >>> # ^^^ >>> >>> hex(l_pid) '0x163' ^^^------------------------------vvv $! ----- !!! $ show process/quota/identification=163 15-OCT-1998 19:14:24.80 User: ZESSIN Process ID: 00000163 Node: HERE Process name: "CREPRC_1P" Process Quotas: Account name: HOME CPU limit: Infinite Direct I/O limit: 100 Buffered I/O byte count quota: 39872 Buffered I/O limit: 100 Timer queue entry quota: 8 Open file quota: 123 PQL$_FILLM set ------------------------------------------->^^^ Paging file quota: 31997 Subprocess quota: 8 Default page fault cluster: 64 AST quota: 100 Enqueue quota: 1111 Shared file limit: 0 PQL$_ENQLM set --------------->^^^^ Max detached processes: 0 Max active jobs: 0 $! ----- $ show process /identification=163 15-OCT-1998 19:17:04.13 User: ZESSIN Process ID: 00000163 Node: HERE Process name: "CREPRC_1P" Terminal: User Identifier: [HOME,ZESSIN] Base priority: 3 <-- base priority set Default file spec: Not available $! ----- $ stop /identification=163 ---------------------------------------- >>> # specify a different UIC >>> l_uic = 0x120035 # [22,65] >>> # show octal >>> print oct(l_uic/65536), oct(l_uic & 0xffff) 022 065 >>> >>> import vms_prcdef >>> l_stsflg = vms_prcdef.PRC_M_DETACH + \ ... vms_prcdef.PRC_M_NOUAF + \ ... vms_prcdef.PRC_M_HIBER >>> >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, None, 'CREPRC_1P',None, Python for OpenVMS -Reference Manual PAGE 2-345 vms_sys.creprc() routine ... l_uic, None, l_stsflg) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (36, '%SYSTEM-F-NOPRIV, insufficient privilege\ or object protection violation') $ set process/privilege=detach >>> >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, None, 'CREPRC_1P',None, ... l_uic, None, l_stsflg) >>> hex(l_pid) '0x161' >>> $ show process/identification=161 16-OCT-1998 19:41:58.26 User: ZESSIN Process ID: 00000161 Node: HERE Process name: "CREPRC_1P" Terminal: User Identifier: [22,65] Base priority: 0 <-- base priority was 'None' Default file spec: Not available $ ---------------------------------------- >>> import vms_prvdef >>> q_prvadr = vms_prvdef.PRV_M_ALLSPOOL + \ ... vms_prvdef.PRV_M_DIAGNOSE + \ ... vms_prvdef.PRV_M_BUGCHK >>> >>> # the privilege mask is a quadword, >>> # which is represented by a Python long integer >>> print q_prvadr 8388688L >>> >>> import vms_prcdef >>> l_stsflg = vms_prcdef.PRC_M_DETACH + \ ... vms_prcdef.PRC_M_NOUAF + \ ... vms_prcdef.PRC_M_HIBER >>> >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, q_prvadr, None, 'CREPRC_1P',3, ... None, 999, l_stsflg) >>> hex (l_pid) '0x160' >>> ^^^------------------------------------vvv $show process /privileges /identification=160 16-OCT-1998 19:24:23.48 User: ZESSIN Process ID: 00000160 Python for OpenVMS -Reference Manual PAGE 2-346 vms_sys.creprc() routine Node: HERE Process name: "CREPRC_1P" Authorized privileges: ALLSPOOL BUGCHK DIAGNOSE Process privileges: ALLSPOOL may allocate spooled device BUGCHK may make bug check log entries DIAGNOSE may diagnose devices Process rights: INTERACTIVE LOCAL System rights: SYS$NODE_HERE $ analyze /system VAX/VMS System analyzer SDA> set process "CREPRC_1P" Process index: 0020 Name: CREPRC_1P Extended PID: 00000160 -------------------------------------------------------------- Status : 001C0009 res,inquan,phdres,hiber,login Status2: 00009800 class_scheduled,class_supplied,windfall PCB address 815192C0 JIB address 8151DEC0 PHD address 81F09A00 Swapfile disk address 00000000 Master internal PID 00050020 Subprocess count 0 Internal PID 00050020 Creator internal PID 00000000 Extended PID 00000160 Creator extended PID 00000000 State HIB Termination mailbox 03E7 [...] vvv--------------------------------------------^^^^ SDA> evaluate 3E7 Hex = 000003E7 Decimal = 999 BUG$_SYSTRMERR+00007 SDA> ---------------------------------------- >>> process_quota_list = ( ('PQL$_FILLM', 123), ('PQL$_BAD_LM',1) ) >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, process_quota_list, 'CREPRC_1P',3, ... None, None, None) Traceback (innermost last): File "", line 1, in ? ValueError: argument 6: quota-list - unknown quota code: PQL$_BAD_LM >>> ---------------------------------------- >>> # a process name must be unique in a UIC group >>> >>> import vms_prcdef >>> l_stsflg = vms_prcdef.PRC_M_DETACH + \ ... vms_prcdef.PRC_M_NOUAF + \ Python for OpenVMS -Reference Manual PAGE 2-347 vms_sys.creprc() routine ... vms_prcdef.PRC_M_HIBER >>> >>> # start first process >>> l_pid1 = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, None, 'CREPRC_TST',3, ... None, None, l_stsflg) >>> hex(l_pid1) '0x164' >>> # try to start second process with same name >>> l_pid2 = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, None, 'CREPRC_TST',3, ... None, None, l_stsflg) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name') >>> # test done, remove first process from system to clean up >>> vms_sys.delprc (l_pid1) 356 <-- DELPRC returns the PID - please look up >>> # the description of DELPRC why this is so ---------------------------------------- >>> # the termination mailbox unit number is a 16-bit value >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, None, 'CREPRC_TST',3, ... None, 65536, None) Traceback (innermost last): File "", line 1, in ? TypeError: argument 10: mbxunt - must be a 16-bit integer or None >>> ---------------------------------------- >>> # the system service reports invalid status flags >>> l_stsflg = -1 >>> l_pid = vms_sys.creprc('SYS$SYSTEM:LOGINOUT.EXE',None, ... None, None, None, None, 'CREPRC_TST',3, ... None, None, l_stsflg) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (380, '%SYSTEM-F-IVSTSFLG, invalid status flag') >>> @@ more examples for CREPRC 24-MAR-1999 ZE. ------------------------------------------------------------------------ 2.6.16 DACEFC - Disassociate Common Event Flag Cluster Releases the calling process's association with a common event flag cluster. Python for OpenVMS -Reference Manual PAGE 2-348 vms_sys.dacefc() routine Format: vms_sys.dacefc (efn) Returns: None Arguments: efn Number of any event flag in the common cluster to be disassociated. The number must be in the range of 64 through 95 for cluster 2, and 96 through 127 for cluster 3. Examples: >>> import vms_sys @@ DACEFC not yet (15-SEP-1998) tested >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.17 DASSGN - Deassign I/O Channel Deassigns (releases) an I/O channel previously acquired using the Assign I/O Channel ($ASSIGN) service. Format: vms_sys.dassgn (chan) Returns: None Arguments: chan Number of the I/O channel to be deassigned. Specify a positive 16-bit integer (0 - 65535). Examples: >>> import vms_sys @@ DASSGN - a short test on 29-NOV-1998 with vms_lib.asn_wth_mbx(). 29-NOV-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-349 vms_sys.delete_intrusion() routine 2.6.18 DELETE_INTRUSION - Delete Intrusion Records Format: vms_sys.delete_intrusion (user_criteria, [flags]) Returns: None Arguments: user_criteria Description of intruder or suspect - a Python string. flags Functional specification for the service. Bitmasks (like CIA_M_IGNORE_RETURN) are available in the 'vms_ciadef' module. Examples: $ show INTRUSION Intrusion Type Count Expiration Source NETWORK SUSPECT 4 22:18:54.62 HERE::ZESSIN $ >>> import vms_sys >>> vms_sys.delete_intrusion ('HERE::ZESSIN') $ show INTRUSION %SHOW-F-NOINTRUDERS, no intrusion records match specification $ ----- >>> vms_sys.delete_intrusion ('HERE::ZESSIN') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (116311746, '%SECSRV-E-CIADBEMPTY, no intruders\ or suspects currently exist') >>> >>> # this conflicts with the documentation that says that >>> # SECURITY privilege is required >>> vms_sys.delete_intrusion ('HERE::ZESSIN') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (10468, '%SYSTEM-F-NOSYSPRV, operation requires\ SYSPRV privilege') >>> >>> 31-MAY-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-350 vms_sys.delete_proxy() routine 2.6.19 DELETE_PROXY - Delete or Modify Proxy Format: vms_sys.delete_proxy (rem_node, rem_user [,local_user] [,flags]) Returns: None Arguments: rem_node Remote node name. rem_user Remote username. local_user Local user name. It must be known to the local system. flags Functional specification and type of local_user (NOdefault). The bit masks are not available from a separate module ($PRXDEF). Examples: >>> import vms_sys >>> vms_sys.add_proxy ('REMNOD', 'REMUSR', 'NOPRIV') >>> PRX_M_DEFAULT = 256 >>> vms_sys.add_proxy ('REM2D', 'REMUSR', 'NOPRIV', PRX_M_DEFAULT) UAF> show /proxy r*::* Default proxies are flagged with (D) REM2D::REMUSR NOPRIV (D) REMNOD::REMUSR NOPRIV UAF> >>> vms_sys.delete_proxy ('REM2D', 'REMUSR', 'NOPRIV') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (116311650, '%SECSRV-E-INVALIDDELETE, you cannot delete\ the last user of a record, you must delete the entire record') >>> >>> vms_sys.delete_proxy ('REM2D', 'REMUSR') UAF> show /proxy r*::* Default proxies are flagged with (D) Python for OpenVMS -Reference Manual PAGE 2-351 vms_sys.delete_proxy() routine REMNOD::REMUSR NOPRIV UAF> >>> vms_sys.delete_proxy ('REMNOD_NO', 'REMUSR_NO') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (116311666, '%SECSRV-E-NOSUCHPROXY, no proxy record\ matches your specification') >>> 21-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.20 DELLNM - Delete Logical Name Format: vms_sys.dellnm (tabnam, [lognam], [acmode]) Returns: None Arguments: tabnam Name of a logical name table or list of tables to be searched for the logical name to be deleted. lognam Logical name to be deleted. acmode Access mode to be used in the delete operation. @@ As of 30-AUG-1998 there is no 'vms_psldef' module which would provide names like PSL_C_SUPER. Remember that the access mode is maximized (the least privileged mode is selected) unless the process has SYSNAM privilege. WARNING! As has been mentioned in the GENMAN 'programming' chapter the Python executable should NOT be installed with privileges! Examples: $ define TEST_LNM "value" $ show logical /full TEST_LNM "TEST_LNM" [super] = "value" (LNM$PROCESS_TABLE) $! the process does not have SYSNAM privilege $ python -c "import vms_sys; vms_sys.dellnm('LNM$PROCESS','TEST_LNM')" Python for OpenVMS -Reference Manual PAGE 2-352 vms_sys.dellnm() routine Traceback (innermost last): File "", line 1, in ? vms_sys.error: (444, '%SYSTEM-F-NOLOGNAM, no logical name match') $! -> the access was maximized and $! a user-mode logical name did not exist $ define TEST_LNM /USER_MODE "value" $ python -c "import vms_sys; vms_sys.dellnm('LNM$PROCESS','TEST_LNM')" $! no error message - the user-mode logical name was deleted $ set PROCESS /PRIVILEGE=SYSNAM $ define /executive_mode /table=LNM$PROCESS_DIRECTORY - TEST_LNM_EXEC "value" $ show logical /table=LNM$PROCESS_DIRECTORY /full (LNM$PROCESS_DIRECTORY) [kernel] [directory] [no protection information] "LNM$GROUP" [kernel] = "LNM$GROUP_010040" [terminal] "LNM$JOB" [kernel] = "LNM$JOB_81524540" [terminal] "LNM$PROCESS" [kernel] = "LNM$PROCESS_TABLE" [terminal] "LNM$PROCESS_DIRECTORY" [kernel,no_alias,nodelete,table] = "" [terminal] "LNM$PROCESS_TABLE" [kernel,no_alias,table] = "" [terminal] "TEST_LNM_EXEC" [exec] = "value" $! $ python Python 1.5.1 (V001P4, Aug 29 1998, 21:12:47) [DECC] on vms Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam portions Copyright 1996-1998 Uwe Zessin >>> import vms_sys >>> PSL_C_EXEC = 1 >>> vms_sys.dellnm ('LNM$PROCESS_DIRECTORY', 'TEST_LNM_EXEC', ... PSL_C_EXEC) >>> import os >>> os.system('show logical /table=LNM$PROCESS_DIRECTORY /full') (LNM$PROCESS_DIRECTORY) [kernel] [directory] [no protection information] "LNM$GROUP" [kernel] = "LNM$GROUP_010040" [terminal] "LNM$JOB" [kernel] = "LNM$JOB_81524540" [terminal] "LNM$PROCESS" [kernel] = "LNM$PROCESS_TABLE" [terminal] "LNM$PROCESS_DIRECTORY" [kernel,no_alias,nodelete,table] = "" [terminal] "LNM$PROCESS_TABLE" [kernel,no_alias,table] = "" [terminal] 1 <-- return status from os.system() >>> $! create a new logical name table $ create /name_table TEST_LNT /parent_table= LNM$PROCESS_DIRECTORY $ show logical /table=LNM$PROCESS_DIRECTORY /full (LNM$PROCESS_DIRECTORY) [kernel] [directory] Python for OpenVMS -Reference Manual PAGE 2-353 vms_sys.dellnm() routine [no protection information] "LNM$GROUP" [kernel] = "LNM$GROUP_010040" [terminal] "LNM$JOB" [kernel] = "LNM$JOB_814AC4C0" [terminal] "LNM$PROCESS" [kernel] = "LNM$PROCESS_TABLE" [terminal] "LNM$PROCESS_DIRECTORY" [kernel,no_alias,nodelete,table] = "" [terminal] "LNM$PROCESS_TABLE" [kernel,no_alias,table] = "" [terminal] "TEST_LNT" [super,table] = "" [terminal] $! delete the logical name table $ python [...] >>> import vms_sys >>> PSL_C_SUPER = 2 >>> vms_sys.dellnm ('LNM$PROCESS_DIRECTORY','TEST_LNT',PSL_C_SUPER) $ show logical /table=LNM$PROCESS_DIRECTORY /full (LNM$PROCESS_DIRECTORY) [kernel] [directory] [no protection information] "LNM$GROUP" [kernel] = "LNM$GROUP_010040" [terminal] "LNM$JOB" [kernel] = "LNM$JOB_81524540" [terminal] "LNM$PROCESS" [kernel] = "LNM$PROCESS_TABLE" [terminal] "LNM$PROCESS_DIRECTORY" [kernel,no_alias,nodelete,table] = "" [terminal] "LNM$PROCESS_TABLE" [kernel,no_alias,table] = "" [terminal] $ 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.21 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. Python for OpenVMS -Reference Manual PAGE 2-354 vms_sys.delprc() routine 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 $ $ 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') Python for OpenVMS -Reference Manual PAGE 2-355 vms_sys.delprc() routine >>> 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 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.22 DEQ - Dequeue Lock Request Note: the 'vms_lckdef' module contains bitmasks and constants that are defined in '$LCKDEF'. Format: status, valblk = vms_sys.deq ([lkid], [valblk],\ [acmode] ,[flags]) Returns: status The condition value from SYS$DEQ(). valblk The lock value block as altered by SYS$DEQ(). It is always returned, even if you specified 'None' for the 'valblk' argument. Arguments: lkid Lock identification of the lock to be dequeued. A Python integer. valblk Lock value block for the resource to be dequeued. A Python long integer. The programmer defines the meanings of these 128 bits. acmode Processor access mode. A Python integer. There is no 'vms_psldef' module. The interface code currently runs in user-mode only. As the access mode is maximized this implies always user-mode. flags Options for the DEQueue operation. A Python integer. Bitmasks are available in module 'vms_lckdef' - see the 'OpenVMS System Services Reference Manual' for details about these bits. Examples: Python for OpenVMS -Reference Manual PAGE 2-356 vms_sys.deq() routine See the examples section of the vms_sys.enqw() routine. 30-MAY-1999 ZE. ------------------------------------------------------------------------ 2.6.23 DEVICE_SCAN - Scan for Devices Returns the names of all devices that match a specified set of search criteria. Format: return_devnam, contxt = vms_sys.device_scan \ ([search_devnam], [itmlst], [contxt)) Returns: return_devnam the device name of the first or next matching (if context is used) device name. contxt The contxt argument which was updated from SYS$DEVICE_SCAN. If the 'contxt' argument to the routine is not used, then a 'None' otherwise a Python long integer is returned. That means a value is _always_ returned for consistency. Arguments: search_devnam Name of the device for which SYS$DEVICE_SCAN is to search. Wildcards are allowed - please see the system services reference manual or the following examples section. itmlst Input item list to specify search criteria. See the examples section below. contxt Value used to indicate the current position of a SYS$DEVICE_SCAN search. On the initial call a 0L (a Python long integer) must be delivered. For the next calls the returned 'contxt' must be delivered. Special notes about the item codes: Device types and device classes are located in module 'vms_dcdef'. WARNING! This module contains over 500 constants. Unfortunately there is currently (10-OCT-1998) no way to access them via the 'pyvms' module. Examples: >>> import vms_sys >>> # a simple loop over ALL devices Python for OpenVMS -Reference Manual PAGE 2-357 vms_sys.device_scan() routine >>> # Note: no networking software was active on this system >>> ctx = 0L >>> while (1): ... dev, ctx = vms_sys.device_scan('*',None,ctx) ... print dev ... _$99$DKB100: _HERE$OPA0: _HERE$MBA1: _HERE$MBA2: [...] _HERE$MBA368: _NLA0: _HERE$PKB0: _HERE$LTA0: _HERE$TTA0: _HERE$TTA1: _HERE$TTA2: _HERE$TTA3: _HERE$PKA0: _ESA0: _GAA0: _$99$DKA0: _$99$DKA100: _HERE$FTA0: _HERE$FTA5: [...] _HERE$FTA16: _INA0: _IMA0: _IKA0: _WSA0: _WSA1: _HERE$PXA0: _HERE$HPA0: Traceback (innermost last): File "", line 2, in ? vms_sys.error: (2648, '%SYSTEM-W-NOMOREDEV, no more devices') >>> # >>> # loop over a limited set of devices specified by wildcard >>> search_devnam = '*$DKA*' # $99$DKB100: does exist >>> ctx = 0L >>> while (1): ... dev, ctx = vms_sys.device_scan(search_devnam,None,ctx) ... print dev, ctx ... _$99$DKA0: 2169249856L _$99$DKA100: 431665979456L Traceback (innermost last): File "", line 2, in ? vms_sys.error: (2648, '%SYSTEM-W-NOMOREDEV, no more devices') >>> Python for OpenVMS -Reference Manual PAGE 2-358 vms_sys.device_scan() routine >>> # search for disks, get maxblock >>> import vms_lib >>> import vms_sys >>> DC__DISK = 1 # bypass module 'vms_dcdef' >>> itmlst = (('DVS$_DEVCLASS',DC__DISK),) >>> ctx = 0L >>> while (1): ... dev, ctx = vms_sys.device_scan('*',itmlst,ctx) ... print dev, vms_lib.getdvi('DVI$_MAXBLOCK',None,dev) ... _$99$DKB100: 2091144 _$99$DKA0: 0 _$99$DKA100: 2091144 Traceback (innermost last): File "", line 2, in ? vms_sys.error: (2648, '%SYSTEM-W-NOMOREDEV, no more devices') >>> # Note: _$99$DKA0: was not mounted >>> # search for a combination of device class and type >>> # two terminals have been set to VT100 >>> DC__TERM = 66 # bypass module 'vms_dcdef' >>> DT_VT100 = 96 >>> itmlst = (('DVS$_DEVCLASS',DC__TERM),\ ... ('DVS$_DEVTYPE', DT_VT100) ) >>> ctx = 0L >>> while (1): ... dev, ctx = vms_sys.device_scan('*',itmlst,ctx) ... print dev ... _HERE$FTA13: _HERE$FTA17: Traceback (innermost last): File "", line 2, in ? vms_sys.error: (2648, '%SYSTEM-W-NOMOREDEV, no more devices') >>> >>> # if no context is specified, then 'None' is returned >>> dev, ctx = vms_sys.device_scan('*') >>> print dev,ctx _$99$DKB100: None >>> >>> dev, ctx = vms_sys.device_scan('*',None,'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: contxt - must be long integer or None >>> >>> dev, ctx = vms_sys.device_scan('*','X') Traceback (innermost last): Python for OpenVMS -Reference Manual PAGE 2-359 vms_sys.device_scan() routine File "", line 1, in ? TypeError: itmlst - must be a tuple >>> # it doesn't say which argument, because this message >>> # is from a generic routine at a deeper level >>> dev, ctx = vms_sys.device_scan(1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, int found >>> # that means 'string' --- ^^^^^^^^^^^^^^^^ >>> 10-DEC-1998 ZE. ------------------------------------------------------------------------ 2.6.24 DISMOU - Dismount Volume Dismounts a mounted volume or volume sets. Format: vms_sys.dismou (devnam [,flags]) Returns: None Arguments: devnam Name of the device to be dismounted. flags Options for the dismount operation. Bitmask values are defined in module 'vms_dmtdef'. Examples: $ mount /SYSTEM DKA0: D0 %MOUNT-I-MOUNTED, D0 mounted on _$99$DKA0: (HERE) $ open /write TEMP_FILE DKA0:[000000]TMP.TMP $ python [...] >>> import vms_sys >>> vms_sys.dismou('DKA0:') %DISM-W-CANNOTDMT, DKA0: cannot be dismounted %DISM-W-USERFILES, 1 user file open on volume Traceback (innermost last): File "", line 1, in ? vms_sys.error: (7573552, '%DISM-W-USERFILES, 0 user files open on volume') >>> Python for OpenVMS -Reference Manual PAGE 2-360 vms_sys.dismou() routine >>> print vms_sys.getmsg (7573552) [0] %DISM-W-USERFILES, !UW user file!%S open on volume >>> >>> import vms_dmtdef >>> l_flags = vms_dmtdef.DMT_M_ABORT + \ ... vms_dmtdef.DMT_M_OVR_CHECKS + \ ... vms_dmtdef.DMT_M_UNLOAD >>> vms_sys.dismou('DKA0:', l_flags) %DISM-I-USERFILES, 1 user file open on volume %DISM-I-MARKEDDMT, DKA0: has been marked for dismount Traceback (innermost last): File "", line 1, in ? vms_sys.error: (7577603, '%DISM-I-MARKEDDMT, !AS has been marked\ for dismount') >>> >>> print vms_sys.getmsg (7577603) [0] %DISM-I-MARKEDDMT, !AS has been marked for dismount >>> @@ DISMOU - more examples, text >>> 15-JUL-1999 ZE. ------------------------------------------------------------------------ 2.6.25 DISPLAY_PROXY - Display Proxy Information Format: proxy_node, proxy_user, default_user, \ (local_users), context = vms_sys.display_proxy \ (rem_node, rem_user, flags [,context])\n\ Returns: proxy_node Node name of a proxy matching the remote node name specified by the rem_node argument and the remote user name specified by the rem_user argument. proxy_user User name of a matching proxy. default_user The default user of a matching proxy. (local_users) A tuple of all local user names associated with a matching proxy. If there aren't any, then 'None' is returned. context Context information between calls of SYS$DISPLAY_PROXY. Note that contexts become invalid after one-half hour of non-use. Arguments: Python for OpenVMS -Reference Manual PAGE 2-361 vms_sys.display_proxy() routine rem_node Remote node name. rem_user Remote username. flags Functional specification and type of local_user (NOdefault). The bitmasks are not available from a separate module ($PRXDEF). context Context information between calls of SYS$DISPLAY_PROXY. Supply a 0 to initialize a new context. Note that contexts become invalid after one-half hour of non-use. Examples: >>> import vms_sys >>> vms_sys.add_proxy ('REMNOD', 'REMUSR1', 'NOPRIV') >>> vms_sys.add_proxy ('REMNOD', 'REMUSR1', 'SYSTEM') >>> vms_sys.add_proxy ('REMNOD', 'REMUSR2', 'NOPRIV') >>> vms_sys.add_proxy ('REMNOD', 'REMUSR3', 'SYSTEM') UAF> show /proxy r*::* Default proxies are flagged with (D) REMNOD::REMUSR3 SYSTEM REMNOD::REMUSR1 NOPRIV SYSTEM REMNOD::REMUSR2 NOPRIV UAF> >>> import vms_sys >>> l_context = 0 >>> proxy_node, proxy_user, default_user, \ ... local_users, context = vms_sys.display_proxy \ ... ('REMNOD', 'REMUSR1', 0, l_context) >>> >>> proxy_node, proxy_user, default_user, \ ... local_users, context ('REMNOD', 'REMUSR1', '', ('NOPRIV', 'SYSTEM'), 0) >>> >>> l_context = 0 ... while (1): ... proxy_node, proxy_user, default_user, \ ... local_users, context_out = vms_sys.display_proxy \ ... ('REMNOD', 'R*', 0, l_context) ... print proxy_node, proxy_user, default_user, \ Python for OpenVMS -Reference Manual PAGE 2-362 vms_sys.display_proxy() routine ... local_users, context_out ... l_context = context_out ... #-while: ... REMNOD REMUSR3 ('SYSTEM',) 231 REMNOD REMUSR1 ('NOPRIV', 'SYSTEM') 231 REMNOD REMUSR2 ('NOPRIV',) 231 Traceback (innermost last): File "", line 2, in ? vms_sys.error: (1777, '%SYSTEM-S-NOMOREITEMS, no more items to be\ returned') >>> >>> 21-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.26 DLCEFC - Delete Common Event Flag Cluster Marks a permanent common event flag cluster for deletion. Format: vms_sys.dlcefc (name) Returns: None Arguments: name Name of the common event flag cluster to be deleted. Examples: >>> import vms_sys @@ DLCEFC not yet (15-SEP-1998) tested >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.27 ENQW - Enqueue Lock Request Note: the 'vms_lckdef' module contains bitmasks and constants that are defined in '$LCKDEF'. Python for OpenVMS -Reference Manual PAGE 2-363 vms_sys.enqw() routine Format: dict = vms_sys.enqw ([efn], lkmode, lksb, [flags], [resnam], [parid], [astadr], [astprm], [blkast], [acmode], [rsdm_id]) Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$ENQW. Note that this code only tells whether the system service started successfully. The final status code is in the 'lksb'. 'lksb' A 'vmsobj_lksb' object that provides storage for the OpenVMS LKSB (LocK Status Block). See the description of 'status' above and the 'lksb' argument below. Arguments: efn Number of the event flag to be set when the lock request has been granted or canceled. If 'None' instead of a number is passed, then EFN 0 is used. lkmode Lock mode requested. Constants like LCK_K_NLMODE are available from module 'vms_lckdef'. lksb LocK Status Block in which SYS$ENQW writes the final completion status. An LKSB should ALWAYS specified, because this is the only place that contains the status code AFTER the system service completed. 'status', as returned only gives information whether the system service has been started successfully. The Python interface routine expects a 'vmsobj_lksb' object. If the programmer specifies 'None' for the lksb argument, then the interface routine automatically generates a vmsobj_lksb object, passes the OpenVMS LKSB to SYS$ENQW and returns the object in 'dict'! Storage for the lock value block (LVB) is always allocated. flags for specifying options for the SYS$ENQW operation. Bitmasks like LCK_M_NOQUEUE are available from module 'vms_lckdef'. resnam Name of the resource to be locked. This is a Python string. parid Lock identification of the parent lock. astadr Python for OpenVMS -Reference Manual PAGE 2-364 vms_sys.enqw() routine This argument is ignored. astprm This argument is ignored. blkast This argument is ignored. acmode Processor access mode. A Python integer. There is no 'vms_psldef' module. The interface code currently runs in user-mode only. As the access mode is maximized this implies always user-mode. rsdm_id Recource domain identification. This is returned after a call to vms_sys.set_resource_domain(). Examples: $ set PROCESS /NAME= PY_ENQW_TST $ python [...] >>> import vms_sys, import vms_lckdef >>> l_lkmode = vms_lckdef.LCK_K_NLMODE >>> # Note: LKSB will be created automatically -v >>> dict = vms_sys.enqw (None, l_lkmode, None, None, ... 'PY_RESNAM', None, None, ... None, None, None, None) >>> for key in dict.keys(): ... print key, '=', dict.get(key) ... #-for ... lksb = status = 1 <-- from SYS$ENQW() >>> >>> # check status inside LKSB >>> r_lksb = dict.get ('lksb') >>> w_status = r_lksb.W_STATUS >>> print vms_sys.getmsg (w_status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> ----- From a different process: $ analyze /SYSTEM VAX/VMS System analyzer SDA> set process PY_ENQW_TST SDA> SDA> show process /lock Process index: 0022 Name: PY_ENQW_TST Extended PID: 000000A2 ---------------------------------------------------------------- Lock data: Lock id: 2100000A PID: 00020022 Flags: Python for OpenVMS -Reference Manual PAGE 2-365 vms_sys.enqw() routine Par. id: 00000000 SUBLCKs: 0 LKB: 814A7040 BLKAST: 00000000 PRIORTY: 0000 Granted at NL 00000000-FFFFFFFF Resource: 414E5345 525F5950 PY_RESNA Status: Length 09 00000000 0000004D M....... User mode 00000000 00000000 ........ Group 040 00000000 00000000 ........ Local copy SDA> ----- >>> w_status = r_lksb.W_STATUS >>> # release the lock >>> l_lockid = r_lksb.L_LOCKID >>> print l_lockid 553648138 >>> >>> (status, o_valblk) = vms_sys.deq (l_lockid) >>> print (status, o_valblk) (1, 0L) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> ----- SDA> show process /lock Process index: 0022 Name: PY_ENQW_TST Extended PID: 000000A2 ---------------------------------------------------------------- %SDA-I-NOPRLOCK, no locks taken out by this process SDA> ---------------------------------------- @@ more vms_sys.enqw() examples >>> 18-JUL-1999 ZE. ------------------------------------------------------------------------ 2.6.28 FILESCAN - Scan String for File Specification Searches a string for a file specification and parses the components of that file specification. Python for OpenVMS -Reference Manual PAGE 2-366 vms_sys.filescan() routine vms_sys.filescan() does _not_ raise an exception when the SYS$FILESCAN routine returns an error. You must check 'status' in the dictionary that is returned. Format: dict = vms_sys.filescan (srcstr, valuelst)\n\ Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$FILESCAN. 'fldflags' A 32-bit mask to which SYS$FILESCAN sets a bit for each file specification component found in the input string. Bitmask values (FSCN_M_name) for this field are located in module 'vms_fscndef'. Note: the system services reference manual (OpenVMS VAX V6.1) names these bits as 'FSCN$V_name' - these are bit-offset values, which are not available within Python. It is only put into the dictionary, when SYS$FILESCAN returns a success status. 'FSCN$_name' Any output items that have been specified in the item-list and whose components could be located by SYS$FILESCAN. The Python interface always specifies an 'auxout' buffer that is 65535 characters big to the SYS$FILESCAN system service. It is only put into the dictionary, when SYS$FILESCAN returns a success status. @@ The auxout argument is new with OpenVMS V6.1 - handling on older OpenVMS versions is currently (28-AUG-1999) unclear. Arguments: srcstr String to be searched for the file specification. valuelst A tuple of strings in the form ('FSCN$_name1', 'FSCN$_name2', ..). Each item specifies a component that is to be returned by SYS$FILESCAN. Python for OpenVMS -Reference Manual PAGE 2-367 vms_sys.filescan() routine Items that the system service could not locate will not be returned in the dictionary ('dict'). Examples: >>> import vms_sys >>> import vms_fscndef >>> srcstr = 'NODNAM::DEV_STR:[UFD.SD]NAM.TYP;VER' >>> valuelst = ('FSCN$_NODE', 'FSCN$_NAME', 'FSCN$_TYPE') >>> dict = vms_sys.filescan (srcstr, valuelst) >>> # check if service completed successfully >>> status = dict.get ('status') >>> status 1 >>> vms_sys_getmsg.html">vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> # show contents of the dictionary that was returned >>> for key in dict.keys(): ... key, dict.get (key) ... ('FSCN$_NODE', 'NODNAM::') ('FSCN$_NAME', 'NAM') ('FSCN$_TYPE', '.TYP') ('fldflags', 251) ('status', 1) >>> >>> # this shows which components are PRESENT in the source string >>> # can be more than those that have been requested by 'valuelst' >>> fldflags = dict.get ('fldflags') >>> fldflags & vms_fscndef.FSCN_M_NODE 1 >>> fldflags & vms_fscndef.FSCN_M_NODE_PRIMARY 128 >>> fldflags & vms_fscndef.FSCN_M_NODE_ACS 0 >>> fldflags & vms_fscndef.FSCN_M_NODE_SECONDARY 0 >>> fldflags & vms_fscndef.FSCN_M_ROOT 0 >>> fldflags & vms_fscndef.FSCN_M_DEVICE 2 >>> fldflags & vms_fscndef.FSCN_M_DIRECTORY 8 >>> fldflags & vms_fscndef.FSCN_M_NAME 16 >>> fldflags & vms_fscndef.FSCN_M_TYPE 32 >>> fldflags & vms_fscndef.FSCN_M_VERSION 64 Python for OpenVMS -Reference Manual PAGE 2-368 vms_sys.filescan() routine >>> ---------------------------------------- >>> # a single-item tuple --v >>> valuelst = ('FSCN$__BAD', ) >>> dict = vms_sys.filescan ('X', valuelst) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: valuelst - unknown item code: FSCN$__BAD >>> >>> # need string for item code ------------v >>> valuelst = ('FSCN$_NODE', 'FSCN$_TYPE', 999) >>> dict = vms_sys.filescan ('X', valuelst) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: valuelst - item:2 is not a string >>> # ^ >>> # The first index in a tuple is number 0 >>> dict = vms_sys.filescan ('X') Traceback (innermost last): File "", line 1, in ? TypeError: function requires exactly 2 arguments; 1 given >>> >>> dict = vms_sys.filescan ('X','Y') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: valuelst - must be a tuple of strings >>> ---------------------------------------- @@ more examples for FILESCAN 28-AUG-1999 ZE. ------------------------------------------------------------------------ 2.6.29 FIND_HELD - Find Identifiers Held by User Returns the identifiers held by a specified holder. Format: id, attrib, fnd_ctx = vms_sys.find_held (holder [,contxt]) Returns: id Identifier value found. Python for OpenVMS -Reference Manual PAGE 2-369 vms_sys.find_held() routine attrib Attributes associated with the holder returned in 'id' when FIND_HELD completes execution. Bitmask values are defined in module 'vms_kgbdef'. fnd_ctx Context value after the call to FIND_HELD. This value must be delivered unchanged into the 'contxt' argument on the next call. A value is always returned, even if the 'contxt' argument is omitted. Arguments: holder Holder whose identifiers are to be found. The Python function only accepts a tuple of 2 integers - not a quadword represented by a Python long integer. For OpenVMS V6.1 the first element is the holder's UIC identifier, the second element must be 0. Check the system services reference manual for your version of OpenVMS. contxt Context value used when repeatedly calling FIND_HELD. See the system services reference manual for more information. Examples: UAF> add /identifier ID_1 /attributes=resource %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=dynamic %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database UAF> grant /identifier ID_1 SYSTEM /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to SYSTEM UAF> grant /identifier ID_2 SYSTEM /attributes=dynamic %UAF-I-GRANTMSG, identifier ID_2 granted to SYSTEM UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 DYNAMIC Holder Attributes SYSTEM DYNAMIC UAF> >>> import vms_sys >>> uic = 0x10004 # SYSTEM has UIC [1,4] >>> id, attrib, fnd_ctx = vms_sys.find_held ((uic,0), None) >>> id, attrib, fnd_ctx (-2147418095, 1, 0) Python for OpenVMS -Reference Manual PAGE 2-370 vms_sys.find_held() routine >>> >>> # idtoasc() can be used, but a second context MUST be supplied or >>> # the current context is destroyed! >>> namlen, nambuf, resid, attrib, id_ctx = vms_sys.idtoasc (id,0) >>> nambuf 'ID_1' >>> fnd_ctx, id_ctx # FIND_HELD and IDTOASC contexts (0, 1) # can be different if other contexts are active >>> vms_sys.finish_rdb (id_ctx) # clear idtoasc context 0 >>> # Note: there is no sign that [1,4] has more identifiers >>> # granted - a loop (as shown below) must be used >>> vms_sys.finish_rdb (fnd_ctx) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (316, '%SYSTEM-F-IVCHAN, invalid I/O channel') >>> # Note: no context was established >>> uic = 0x10004 # SYSTEM is UIC [1,4] >>> contxt = 0 # initialize context >>> id, attrib, fnd_ctx = vms_sys.find_held ((uic,0), contxt) >>> id, attrib, fnd_ctx (-2147418095, 1, 1) >>> print hex (id) 0x80010011 <-- this is ID_1 >>> namlen, nambuf, resid, attrib, id_ctx = vms_sys.idtoasc (id, 0) >>> nambuf 'ID_1' >>> fnd_ctx, id_ctx # FIND_HELD and IDTOASC contexts (1, 2) # can be different if other contexts are active >>> vms_sys.finish_rdb (id_ctx) # clear IDTOASC context 0 >>> import vms_kgbdef >>> print attrib, vms_kgbdef.KGB_M_RESOURCE 1 1 >>> >>> # next call to FIND_HELD >>> contxt = fnd_ctx >>> id, attrib, fnd_ctx = vms_sys.find_held ((uic,0), contxt) >>> id, attrib, fnd_ctx (-2147418094, 2, 1) >>> print hex (id) 0x80010012 <-- this is ID_2 >>> print attrib, vms_kgbdef.KGB_M_DYNAMIC 2 2 >>> >>> # next call to FIND_HELD >>> contxt = fnd_ctx >>> id, attrib, fnd_ctx = vms_sys.find_held ((uic,0), contxt) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') Python for OpenVMS -Reference Manual PAGE 2-371 vms_sys.find_held() routine >>> # SS$_NOSUCHID signals the end of the search loop >>> # it is not necessary to call FINISH_RDB in his situation >>> vms_sys.finish_rdb (fnd_ctx) 0 <-- the context has been cleared >>> uic = 0x20003 # no grants on UIC [2,3] >>> id, attrib, fnd_ctx = vms_sys.find_held ((uic,0), None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> id_check = 0x80000001 # this is a rights identifier >>> id, attrib, fnd_ctx = vms_sys.find_held ((id_check,0)) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8740, '%SYSTEM-F-IVIDENT, invalid identifier format') >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.30 FIND_HOLDER - Find Holder of Identifier Returns the holder of a specified identifier. Format: (holder,0), attrib, fnd_ctx = vms_sys.find_holder (id [,contxt]) Returns: (holder, 0) Holder identifier returned when FIND_HOLDER completes execution. This is a tuple. The first value is the identifier. The second value is 0 (description of OpenVMS VAX V6.1). attrib Mask of attributes associated with the holder record specified by holder. Bitmask values are defined in module 'vms_kgbdef'. fnd_ctx Context value after the call to FIND_HOLDER. This value must be fed unchanged into the 'contxt' argument on the next call. A value is always returned, even if the 'contxt' argument is omitted. Arguments: id Binary identifier value whose holders are to be found by Python for OpenVMS -Reference Manual PAGE 2-372 vms_sys.find_holder() routine FIND_HOLDER. contxt Context value used when repeatedly calling FIND_HOLDER. See the system services reference manual for more information. Examples: UAF> add /identifier ID_1 /attributes=resource %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=dynamic %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database UAF> grant /identifier ID_1 SYSTEM /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to SYSTEM UAF> grant /identifier ID_1 ZESSIN /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to ZESSIN UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE ZESSIN RESOURCE UAF> >>> import vms_sys >>> def show_uic (uic_value): ... high_word = uic_value / 65536 ... low_word = uic_value - (high_word * 65536) ... # Note: [1:], because octal values are preceeded by '0' ... uic_string = \ ... '[' + oct(high_word)[1:] + ',' + oct(low_word)[1:] + ']' ... print uic_string ... >>> >>> id = 0x80010011 # identifier ID_1 >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, None) >>> uic, attrib, fnd_ctx ((65540, 0), 1, 0) >>> show_uic (uic[0]) [1,4] <-- UIC of user SYSTEM >>> >>> # idtoasc() can be used, but a second context MUST be supplied or >>> # the current context is destroyed! >>> namlen, nambuf, resid, attrib, id_ctx = vms_sys.idtoasc (uic[0],0) >>> nambuf 'SYSTEM' >>> fnd_ctx, id_ctx # FIND_HELD and IDTOASC contexts (0, 1) # can be different if other contexts are active >>> vms_sys.finish_rdb (id_ctx) # clear idtoasc context Python for OpenVMS -Reference Manual PAGE 2-373 vms_sys.find_holder() routine 0 >>> # Note: there is no sign that 0x80010011 is granted to more >>> # users - a loop (as shown below) must be used >>> vms_sys.finish_rdb (fnd_ctx) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (316, '%SYSTEM-F-IVCHAN, invalid I/O channel') >>> # Note: no context was established >>> id = 0x80010011 # identifier ID_1 >>> contxt = 0 # initialize context >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, contxt) >>> uic, attrib, fnd_ctx ((65540, 0), 1, 1) >>> show_uic (uic[0]) [1,4] <-- UIC of user SYSTEM >>> namlen, nambuf, resid, attrib, id_ctx = vms_sys.idtoasc (uic[0], 0) >>> nambuf 'SYSTEM' >>> fnd_ctx, id_ctx # FIND_HELD and IDTOASC contexts (1, 2) # can be different if other contexts are active >>> vms_sys.finish_rdb (id_ctx) # clear IDTOASC context 0 >>> >>> import vms_kgbdef >>> print attrib, vms_kgbdef.KGB_M_RESOURCE 1 1 >>> >>> # next call to FIND_HOLDER >>> contxt = fnd_ctx >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, contxt) >>> uic, attrib, fnd_ctx ((270532617, 0), 1, 1) >>> show_uic (uic[0]) [10040,11] <-- UIC of user ZESSIN >>> # one can call vms_sys.idtoasc here, >>> # but MUST specify a new context! >>> >>> # next call to FIND_HOLDER >>> contxt = fnd_ctx >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, contxt) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> # SS$_NOSUCHID signals the end of the search loop >>> # it is not necessary to call FINISH_RDB in his situation >>> vms_sys.finish_rdb (fnd_ctx) 0 <-- the context has been cleared >>> id = 0x80000001 # this identifier not granted to any UIC Python for OpenVMS -Reference Manual PAGE 2-374 vms_sys.find_holder() routine >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> id = 0x80011234 # this identifier does not exist >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> uic_check = 0x10004 # this is a UIC >>> uic, attrib, fnd_ctx = vms_sys.find_holder (uic_check) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> 27-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.31 FINISH_RDB - Terminate Rights Database Context Deallocates the record stream and clears the context value used with FIND_HELD, FIND_HOLDER or IDTOASC. Format: new_ctx = vms_sys.finish_rdb (contxt) Returns: new_ctx Context value after FINISH_RDB completed execution. Arguments: contxt Context value to be cleared when $FINISH_RDB completes execution. Examples: Omitted. See the examples sections of FIND_HELD, FIND_HOLDER or IDTOASC which use FINISH_RDB. 27-SEP-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-375 vms_sys.forcex() routine 2.6.32 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: 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') Python for OpenVMS -Reference Manual PAGE 2-376 vms_sys.forcex() routine >>> 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 >>> 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): Python for OpenVMS -Reference Manual PAGE 2-377 vms_sys.forcex() routine 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 ? TypeError: argument 2: expected read-only buffer, int found >>> vms_sys.forcex (None,None,'BAD') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: code - must be integer or None >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.33 FORMAT_ACL - Format Access Control List Entry Formats the specified access control entry (ACE) into a text string. Note the difference between an 'access control list' (ACL) and an ACE - an ACL is comprised by one or more ACEs. Format: status, aclstr = vms_sys.format_acl (aclent ,[width] ,[trmdsc] ,[indent] ,[accnam] ,[nullarg]) Returns: status Condition value from SYS$FORMAT_ACL. Can be SS$_NORMAL or SS$_BUFFEROVF. All other codes raise a Python exception. aclstr Formatted ACE resulting when SYS$FORMAT_ACL completes its execution. The 'acllen' argument from SYS$FORMAT_ACL is not returned - use the len() function from Python. Arguments: aclent Input ACE, binary. See the system services reference manual for an explanation of how it is formatted, width Maximum width of the formatted ACE. trmdsc Python for OpenVMS -Reference Manual PAGE 2-378 vms_sys.format_acl() routine Line termination characters used in the formatted ACE. It is used when the total length exceeds the size of the 'width' argument. indent Number of blank characters beginning each line of the formatted ACE. accnam Names of the bits in the access mask. Specify 'None' to indicate omission of this argument or a 'vmsobj__access_names' object. nullarg Placeholder argument - any input other than None is an error. Examples: $ copy _NLA0: ACL.DAT $ set ACL ACL.DAT - /ACL= ( (identifier= [1,4], access= read+write), - (identifier= [2,4], access= delete+execute), - (identifier= [3,4], access= control) ) $! $ directory /acl ACL.DAT Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] ACL.DAT;1 (IDENTIFIER=[G1,SYSTEM],ACCESS=READ+WRITE) (IDENTIFIER=[2,4],ACCESS=EXECUTE+DELETE) (IDENTIFIER=[3,4],ACCESS=CONTROL) Total of 1 file. $! ---------------------------------------- >>> import pyvms, vms_sys >>> >>> fab = pyvms.vmsobj_fab () >>> xabpro = pyvms.vmsobj_xabpro () >>> >>> fab.FNA = 'ACL.DAT' >>> fab.XAB = xabpro >>> >>> # allocate a read/write buffer for the ACL >>> aclbuf = pyvms.vmsobj__membuf (200) >>> xabpro.ACLBUF = aclbuf >>> xabpro.L_ACLCTX = 0 # read begin of ACL >>> >>> status = vms_sys.open (fab) >>> print vms_sys.getmsg (status) ('%RMS-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> print vms_sys.getmsg (fab.L_STS) ('%RMS-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> # ACL status Python for OpenVMS -Reference Manual PAGE 2-379 vms_sys.format_acl() routine >>> print vms_sys.getmsg (xabpro.L_ACLSTS) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> # 1st ACE >>> print vms_sys.format_acl (aclbuf.buffer[0:xabpro.W_ACLLEN], \ ... 90, '*', 4) (1, ' (IDENTIFIER=[G1,SYSTEM],ACCESS=READ+WRITE)') >>> aclsiz = ord (aclbuf.buffer[:1]) >>> >>> # 2nd ACE >>> vms_sys.format_acl \ ... (aclbuf.buffer[aclsiz:xabpro.W_ACLLEN-aclsiz], \ ... 60, '*', 4) (1, ' (IDENTIFIER=[2,4],ACCESS=EXECUTE+DELETE)') >>> >>> # 3rd ACE ignored >>> >>> status = vms_sys.close (fab) >>> print vms_sys.getmsg (status) ('%RMS-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> @@ more vms_sys.format_acl() examples >>> 11-JUL-1999 ZE. ------------------------------------------------------------------------ 2.6.34 GETJPIW - Get Job/Process Information This routine allows the programmer to receive a single or several items of information per call from the specified process. The vms_lib.getjpi() routine provides support for only a single item, but uses a much simpler interface. Note: the 'vms_jpidef' module contains bitmasks and constants that are defined in '$JPIDEF'. Access to the item codes ("JPI$_name") is possible via the 'pyvms' module. Format: dict = vms_sys.getjpiw ([efn] [,pidadr] [,prcnam], itmlst \ [,iosb] [,astadr] [,astprm]) Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$GETJPIW. Note that this code only tells whether the system service Python for OpenVMS -Reference Manual PAGE 2-380 vms_sys.getjpiw() routine started successfully. The final status code is in the 'iosb'. 'pidadr' The process identification of the target process or a context value of a wildcard operation. See additional comments at the 'pidadr' argument below. 'iosb' A 'vmsobj_iosb' object that provides storage for the OpenVMS IOSB (I/O status block). See the description of 'status' above and the 'iosb' argument below. 'JPI$_name' Any output item that has been specified in the item-list and that is supported by SYS$GETJPIW. Note that the 'data' that is returned can itself be a tuple for some items - see below. It is only put into the dictionary, when SYS$GETJPIW returns a success status. A 'counted ASCII string' (ASCIC) - which means that the first byte contains the string length - is returned as a normal string (one without the count byte at the beginning). You can use Python's len() function to find out how long the returned string is. Arguments: efn Number of the event flag to be set when SYS$GETJPIW returns the requested information. If 'None' instead of a number is passed, then EFN 0 is used. pidadr Process identification (PID) of the target process or a pid-context that can be used for the next step in a wildcard lookup. Note that vms_sys.process_scan() can be used to establish a context to select a subset of processes. prcnam Name of process to lookup. Normally 'pidadr' overrides 'prcnam'! Use 'pidadr' = 'None' to force usage of 'prcnam'. itmlst Item list specifying which information from the specified process is to be returned. You must specify a tuple of strings. See the examples below. It is possible to put an item tuple - e. g.: ('JPI$_PRCNAM',None) - instead of a single string - e. g.: 'JPI$_PRCNAM' -, but this is not required for output-only items. iosb I/O status block. An IOSB should ALWAYS specified, because Python for OpenVMS -Reference Manual PAGE 2-381 vms_sys.getjpiw() routine this is the only place that contains the status code AFTER the system service completed. 'status', as returned only gives information whether the system service has been started successfully. The Python interface routine expects a vmsobj_iosb object. If the programmer specifies 'None' for the iosb argument, then the interface routine automatically generates a vmsobj_iosb object, passes the OpenVMS IOSB to SYS$GETJPIW and returns the object in 'dict'! astadr This argument is ignored. astprm This argument is ignored. Examples: >>> import vms_sys >>> # Note: no IOSB is specified, but the interface routine creates >>> # one anyway and returns it in 'dict'. >>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ACCOUNT',) ) >>> # pidadr = 0 means current process >>> # v >>> dict = vms_sys.getjpiw (None, 0, None, itmlst) >>> for key in dict.keys(): ... print key, '=', dict.get(key) ... #-for ... JPI$_PRCNAM = ZESSIN_FTA14 pidadr = 341 <-- the real PID is always returned iosb = JPI$_ACCOUNT = HOME status = 1 >>> >>> # 'status' only tells if $GETJPIW was started successfully >>> status = dict.get ('status') >>> print status 1 >>> print vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> # The final status code of $GETJPIW is in the first longword >>> # of the iosb (I/O status block). >>> iosb = dict.get ('iosb') >>> status_final = iosb.l0 >>> print status_final 1 >>> print vms_sys.getmsg (status_final) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> Python for OpenVMS -Reference Manual PAGE 2-382 vms_sys.getjpiw() routine >>> # Create an iosb object and pass it to the interface routine - >>> # the same object will be returned in 'dict'. >>> import pyvms >>> iosb = pyvms.vmsobj_iosb() >>> >>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ACCOUNT',) ) >>> dict = vms_sys.getjpiw (None, 0, None, itmlst, iosb) >>> for key in dict.keys(): ... print key, '=', dict.get(key) ... #-for ... JPI$_PRCNAM = ZESSIN_FTA14 pidadr = 341 iosb = JPI$_ACCOUNT = HOME status = 1 >>> >>> # same id means same object >>> id (iosb) 2209888 >>> dict_iosb = dict.get('iosb') >>> id (dict_iosb) 2209888 >>> >>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ERR',) ) >>> dict = vms_sys.getjpiw (None, 0, None, itmlst) Traceback (innermost last): File "", line 1, in ? ValueError: itmlst - unknown item code: JPI$_ERR >>> >>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ACCOUNT',) ) >>> >>> # vmsobj_iosb or None expected -----------------v >>> dict = vms_sys.getjpiw (None, 0, None, itmlst, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 5: iosb - must be vmsobj_iosb or None >>> @@ more vms_sys.getjpiw() examples >>> 12-JUN-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-383 vms_sys.getmsg() routine 2.6.35 GETMSG - Get Message Format: bufadr, outadr = vms_sys.getmsg (msgid [,flags]) Returns: bufadr The message string. outadr Optional information returned by SYS$GETMSG. This is a 4-byte tuple. Byte 0 Reserved. Byte 1 Count of FAO arguments associated with message. Byte 2 User-specified value in message, if any. Byte 3 Reserved. Arguments: msgid Condition value to be translated - a Python integer. flags A Python integer which indicates what message components are to be returned. See the system services reference manual that explains which bit affects which component. Examples: >>> import vms_sys >>> bufadr, outadr = vms_sys.getmsg(0xc) >>> bufadr, outadr ('%SYSTEM-F-ACCVIO, access violation, reason mask=!XB, virtual\ address=!XL,PC=!XL, PSL=!XL', (0, 4, 0, 0)) >>> # 4 FAO arguments -------------^ (!XB, !XL !XL !XL) >>> bufadr, outadr = vms_sys.getmsg(0x2c) >>> bufadr, outadr ('%SYSTEM-F-ABORT, abort', (0, 0, 0, 0)) >>> # no FAO argument ---------^ >>> # get only the message text (standard Python functionality) >>> vms_sys.getmsg(0x2c)[0] '%SYSTEM-F-ABORT, abort' >>> >>> # omit argument 2, use process default-v Python for OpenVMS -Reference Manual PAGE 2-384 vms_sys.getmsg() routine >>> bufadr, outadr = vms_sys.getmsg (0x2c, None) >>> bufadr '%SYSTEM-F-ABORT, abort' >>> >>> # omit argument 2, use process default-v >>> bufadr, outadr = vms_sys.getmsg (0x2c, 0) >>> bufadr '%SYSTEM-F-ABORT, abort' >>> $ set MESSAGE /noSEVERITY /noTEXT $ python [...] >>> import vms_sys >>> bufadr, outadr = vms_sys.getmsg(0x2c, 0) >>> bufadr '%SYSTEM-ABORT' >>> $ set MESSAGE /SEVERITY /TEXT >>> # use flags argument to define which component to show >>> bufadr, outadr = vms_sys.getmsg(0x2c, 5) >>> bufadr '%F, abort' >>> bufadr, outadr = vms_sys.getmsg(0x2c, 10) >>> bufadr '%SYSTEM-ABORT' >>> # the following names for the bits of the 'flags' argument >>> # are 'artifically' constructed >>> GETMSGFLG_M_TXT = 1 >>> GETMSGFLG_M_MESSAGE = 2 >>> GETMSGFLG_M_SEVERITY = 4 >>> GETMSGFLG_M_FACILITY = 8 >>> flags = GETMSGFLG_M_FACILITY + \ ... GETMSGFLG_M_SEVERITY + \ ... GETMSGFLG_M_TXT >>> bufadr, outadr = vms_sys.getmsg(0x2c, flags) >>> bufadr '%SYSTEM-F, abort' >>> >>> vms_sys.getmsg ('X') Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> vms_sys.getmsg (1,'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: flags - must be integer or None >>> 17-OCT-1998 ZE. Python for OpenVMS -Reference Manual PAGE 2-385 vms_sys.getquiw() routine ------------------------------------------------------------------------ 2.6.36 GETQUIW - Get Queue Information This routine allows the programmer to receive a single or several items of queue information. The vms_lib.getqui() routine provides support for only a single item, but uses a much simpler interface. On the other hand, for repeated access to the same object one has to 'freeze' the context. Note: the 'vms_quidef' module contains bitmasks and constants that are defined in '$QUIDEF'. Access to the item codes ("QUI$_name") is possible via the 'pyvms' module. Format: dict = vms_sys.getquiw ([efn], func, [context], [itmlst], \ [iosb], [astadr], [astprm]) Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$GETQUIW. Note that this code only tells whether the system service started successfully. The final status code is in the 'iosb'. 'context' Number of a context stream when wildcard processing is done. This key is only present when the 'context' argument below has been used. 'iosb' A 'vmsobj_iosb' object that provides storage for the OpenVMS IOSB (I/O status block). See the description of 'status' above and the 'iosb' argument below. 'QUI$_name' Any output item that has been specified in the item-list and that is supported by SYS$GETQUIW. Note that the 'data' that is returned can itself be a tuple for some items - see below. It is only put into the dictionary, when SYS$GETQUIW returns a success status. A 'counted ASCII string' (ASCIC) - which means that the first byte contains the string length - is returned as a normal string (one without the count byte at the beginning). You can use Python's len() function to find out how long the returned string is. Python for OpenVMS -Reference Manual PAGE 2-386 vms_sys.getquiw() routine Arguments: efn Number of the event flag to be set when SYS$GETQUIW returns the requested information. If 'None' instead of a number is passed, then EFN 0 is used. func Function code specifying the function that SYS$GETQUIW is to perform. context Use 'None' to indicate that no context stream is to be used or -1 to create a new context stream. After a call the updated value is returned as key 'context' in the dictionary 'dict'. itmlst Item list specifying which information is to be returned. You must specify a tuple of strings/ tuples. See the examples below. It is possible to put an item tuple - e. g.: ('QUI$_ACCOUNT',None) - instead of a single string - e. g.: 'QUI$_ACCOUNT' -, but this is not required for output-only items. iosb I/O status block. An IOSB should ALWAYS specified, because this is the only place that contains the status code AFTER the system service completed. 'status', as returned only gives information whether the system service has been started successfully. The Python interface routine expects a vmsobj_iosb object. If the programmer specifies 'None' for the iosb argument, then the interface routine automatically generates a vmsobj_iosb object, passes the OpenVMS IOSB to SYS$GETQUIW and returns the object in 'dict'! astadr This argument is ignored. astprm This argument is ignored. special notes about some item codes: QUI$_FILE_IDENTIFICATION This item is stored in the (28-byte) buffer of the OpenVMS item list and returned to Python by a 'converter function'. The data is stored in a 3-item tuple with the following format: device The device name is a string with a maximum length of 15 characters. This is internally stored as an ASCIC - the first byte is the length. fid The file identification is returned as a 3-item tuple Python for OpenVMS -Reference Manual PAGE 2-387 vms_sys.getquiw() routine where each item is a 16-bit integer. Internally this is stored as an array of 3 words. The first item is the file-number. the second item is the sequence numer. The third item is the relative volume number. did The directory file identification is returned as a 3-item tuple where each item is a 16-bit integer. Internally this is stored the same way as the 'fid' that is described above. An example of how to use the QUI$_FILE_IDENTIFICATION item code is shown in the examples section. Examples: >>> import vms_sys --------------- >>> # a simple call and analysis of returned data >>> # >>> # Note: no IOSB was specified, but the interface routine creates >>> # one anyway and returns it in 'dict'. >>> itmlst = ( ("QUI$_SEARCH_NAME",'*'), ("QUI$_QUEUE_NAME") ) >>> context = -1 >>> dict = vms_sys.getquiw (None, "QUI$_DISPLAY_QUEUE", \ ... context, itmlst) >>> >>> # 'status' only tells if $GETQUIW was started successfully >>> status = dict.get ('status') >>> print status 1 >>> print vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> for key in dict.keys(): ... print key, '=', dict.get(key) ... #-for ... QUI$_QUEUE_NAME = BATQ_BACKUP context = 1 iosb = status = 1 >>> >>> # The final status code of $GETQUIW is in the first longword >>> # of the iosb (I/O status block). >>> iosb = dict.get ('iosb') >>> status_final = iosb.l0 # status is in first longword >>> print status_final 262145 >>> print vms_sys.getmsg (status_final) ('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> Python for OpenVMS -Reference Manual PAGE 2-388 vms_sys.getquiw() routine >>> print dict.get ('QUI$_QUEUE_NAME') BATQ_BACKUP >>> >>> # The context must be fed as argument to the next call >>> # when using a loop. >>> context = dict.get ('context') >>> print context 1 >>> >>> # Release this context and use an explicit IOSB. >>> # >>> # Create an iosb object and pass it to the interface routine - >>> # the same object will be returned in 'dict'. >>> import pyvms >>> iosb = pyvms.vmsobj_iosb() >>> print iosb >>> >>> dict = vms_sys.getquiw (None, 'QUI$_CANCEL_OPERATION', \ ... context, None, iosb) >>> >>> for key in dict.keys(): ... print key, '=', dict.get(key) ... iosb = context = 1 status = 1 >>> >>> iosb = dict.get ('iosb') >>> status = iosb.l0 >>> print vms_sys.getmsg (status) ('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> print iosb >>> # same memory address ^^^^^^^^^ >>> -------------------- >>> # loop over all queues and show their names and >>> # description texts >>> >>> import vms_sys >>> >>> itmlst = (("QUI$_SEARCH_NAME",'*'), ... ("QUI$_QUEUE_NAME"), ... ("QUI$_QUEUE_DESCRIPTION") ... ) >>> context = -1 >>> >>> while (1): Python for OpenVMS -Reference Manual PAGE 2-389 vms_sys.getquiw() routine ... dict = vms_sys.getquiw (None, "QUI$_DISPLAY_QUEUE", \ ... context, itmlst) ... status = dict.get ('status') ... if not (status & 1): ... print '*', vms_sys.getmsg (status) ... break # abort loop ... else: ... iosb = dict.get ('iosb') ... status = iosb.l0 ... if not (status & 1): ... print vms_sys.getmsg (status) ... break # abort loop ... else: ... queue_name = dict.get ('QUI$_QUEUE_NAME') ... queue_description = dict.get ('QUI$_QUEUE_DESCRIPTION') ... print "%s (%s)" % (queue_name, queue_description) ... context = dict.get ('context') # feed into next call ... BATQ_BACKUP () BATQ_BATCH () BATQ_RAYTRACE01 () BATQ_RAYTRACE02 () BATQ_SYSTEM () HERE_BACKUP () HERE_BATCH () HERE_PRINT () HERE_RAYTRACE01 (Raytracing, PRIO:1) HERE_RAYTRACE02 (Raytracing, PRIO:2) HERE_SYSTEM () UUCP_BATCH (UUCP Daemons and Administrative Processing) ('%JBC-E-NOMOREQUE, no more queues found', (0, 0, 0, 0)) >>> --------------- >>> # This code loops over all queues, all jobs in all queues and >>> # all files of all jobs. >>> # >>> # The prompt characters are not included to save some width >>> # for the printed documentation import vms_quidef, vms_sys # itmlst_queue = (("QUI$_SEARCH_NAME",'*') \ ,"QUI$_QUEUE_NAME" \ ,"QUI$_QUEUE_DESCRIPTION" ) itmlst_job = (("QUI$_SEARCH_FLAGS", \ vms_quidef.QUI_M_SEARCH_ALL_JOBS+ \ vms_quidef.QUI_M_SEARCH_WILDCARD) \ ,"QUI$_JOB_NAME" \ ,"QUI$_ENTRY_NUMBER" \ ) Python for OpenVMS -Reference Manual PAGE 2-390 vms_sys.getquiw() routine itmlst_file = (("QUI$_SEARCH_FLAGS", \ vms_quidef.QUI_M_SEARCH_WILDCARD) \ ,"QUI$_FILE_IDENTIFICATION" \ ,"QUI$_FILE_SPECIFICATION" \ ) context = -1 # create a new wildcard context while 1: dict = vms_sys.getquiw (None, "QUI$_DISPLAY_QUEUE", \ context, itmlst_queue) status = dict.get ('status') if not (status & 1): print '[q1]',vms_sys.getmsg (status) break else: iosb = dict.get ('iosb') status = iosb.l0 if not (status & 1): print '[q2]',status, vms_sys.getmsg (status) break else: queue_name = dict.get ('QUI$_QUEUE_NAME') queue_description = dict.get ('QUI$_QUEUE_DESCRIPTION') print "%s (%s)" % (queue_name, queue_description) context = dict.get ('context') # feed into next call # while (1): dict = vms_sys.getquiw (None, "QUI$_DISPLAY_JOB", \ context, itmlst_job) status = dict.get ('status') if not (status & 1): print '[j1]',vms_sys.getmsg (status) break else: iosb = dict.get ('iosb') status = iosb.l0 if not (status & 1): print '[j2]',status, vms_sys.getmsg (status) break else: job_name = dict.get ('QUI$_JOB_NAME') job_entry = dict.get ('QUI$_ENTRY_NUMBER') print "%d (%s)" % (job_entry, job_name) context = dict.get ('context') # feed into next call # while (1): dict = vms_sys.getquiw (None, "QUI$_DISPLAY_FILE", \ context, itmlst_file) status = dict.get ('status') if not (status & 1): print '[f1]',vms_sys.getmsg (status) break else: Python for OpenVMS -Reference Manual PAGE 2-391 vms_sys.getquiw() routine iosb = dict.get ('iosb') status = iosb.l0 if not (status & 1): print '[f2]',status, vms_sys.getmsg (status) break else: file_ident = dict.get ('QUI$_FILE_IDENTIFICATION') file_spec = dict.get ('QUI$_FILE_SPECIFICATION') print file_ident print file_spec context = dict.get ('context') # feed into next call # # while (file) # while (job) # while (queue) ** This is the output - the example was run on a different system ** than which is normally used for development so you see ** other queue / device names. BATQ_BACKUP () [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) BATQ_BATCH () [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) BATQ_SYSTEM () [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) FM_TE_LA (HP Laserjet 4+) [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) NET1_PS (HP Laserjet 5/via PS-converter) [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) NET_1 (HP Laserjet 5) [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) ROCH_BACKUP () [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) ROCH_BATCH () 2 (DEMO1) ('_ROCH$DKC300', (15393, 22, 0), (21027, 9, 0)) _ROCH$DKC300:[USER.ZESSIN.WWW]DEMO1.COM;1 [f2] 295314 ('%JBC-E-NOMOREFILE, no more files found', (0, 0, 0, 0)) [j2] 295330 ('%JBC-E-NOMOREJOB, no more jobs found', (0, 0, 0, 0)) ROCH_LN15 () [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) ROCH_SYSTEM () 3 (DEMO1) ('_ROCH$DKC300', (15393, 22, 0), (21027, 9, 0)) _ROCH$DKC300:[USER.ZESSIN.WWW]DEMO1.COM;1 ('_ROCH$DKC300', (9206, 34, 0), (21027, 9, 0)) _ROCH$DKC300:[USER.ZESSIN.WWW]DEMO2.COM;1 [f2] 295314 ('%JBC-E-NOMOREFILE, no more files found', (0, 0, 0, 0)) 4 (DEMO1) ('_ROCH$DKC300', (15393, 22, 0), (21027, 9, 0)) _ROCH$DKC300:[USER.ZESSIN.WWW]DEMO1.COM;1 ('_ROCH$DKC300', (9206, 34, 0), (21027, 9, 0)) _ROCH$DKC300:[USER.ZESSIN.WWW]DEMO2.COM;1 Python for OpenVMS -Reference Manual PAGE 2-392 vms_sys.getquiw() routine [f2] 295314 ('%JBC-E-NOMOREFILE, no more files found', (0, 0, 0, 0)) [j2] 295330 ('%JBC-E-NOMOREJOB, no more jobs found', (0, 0, 0, 0)) SYS$BATCH () [j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0)) [q2] 295338 ('%JBC-E-NOMOREQUE, no more queues found', (0, 0, 0, 0)) >>> -------------------- >>> dict = vms_sys.getquiw ('BADEFN', 'QUI$_DISPLAY_JOB') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: efn - must be integer or None >>> >>> dict = vms_sys.getquiw (None, 'QUI$_QUEUE_NAME') Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: func - not a function code:QUI$_QUEUE_NAME >>> >>> dict = vms_sys.getquiw (None, 'QUI$_DISPLAY_JOB', 'BADCTX') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: context - must be integer or None >>> >>> itmlst = ( 'QUI$_ERR', ) >>> dict = vms_sys.getquiw (None, 'QUI$_DISPLAY_JOB', \ ... None, itmlst) Traceback (innermost last): File "", line 1, in ? ValueError: itmlst - unknown item code: QUI$_ERR >>> >>> itmlst = ( 'QUI$_ENTRY_NUMBER', ) >>> dict = vms_sys.getquiw (None, 'QUI$_DISPLAY_JOB', \ ... None, itmlst, 'X') >>> # IOSB or None expected ---------------^ Traceback (innermost last): File "", line 1, in ? TypeError: argument 5: iosb - must be vmsobj_iosb or None >>> @@ more vms_sys.getquiw() examples >>> 31-MAY-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-393 vms_sys.gettim() routine 2.6.37 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 GENMAN 'Programming', 'special OpenVMS datatypes' for details. Arguments: vms_sys.gettim() does not take any arguments. Examples: >>> import vms_sys >>> q_bintim = vms_sys.gettim () >>> q_bintim 44096363555600000L >>> vms_sys.asctim (q_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 >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.38 GETUAI - Get User Authorization Information Returns authorization information about a specified user. vms_sys.getuai() does _not_ raise an exception when the SYS$GETUAI routine returns an error. You must check 'status' in the dictionary that is returned. Format: Python for OpenVMS -Reference Manual PAGE 2-394 vms_sys.getuai() routine dict = vms_sys.getuai (None, [contxt], usrnam, itmlst \ [,None] [,None] [,None]) Returns: dict A dictionary that has the following keys: 'status' the condition value returned from SYS$GETUAI. 'contxt' the context value if and only if the 'contxt' argument was specified. It is only put into the dictionary, when SYS$GETUAI returns a success status. 'UAI$_name' Any output item that has been specified in the item-list and that is supported by SYS$GETUAI. Note that the 'data' that is returned can itself be a tuple for some items - see below. It is only put into the dictionary, when SYS$GETUAI returns a success status. A 'counted ASCII string' (ASCIC) - which means that the first byte contains the string length - is returned as a normal string (one without the count byte at the beginning). Use Python's "len()" function to find out how long the returned string is. Arguments: None Placeholder arguments, that are currently ignored. You MUST specify the first argument, you can leave off the last 3 arguments. contxt Used to maintain authorization file context. On the initial call, it should contain the value -1. You must use 'None' - not 0 - to indicate omission of this argument. After the call to SYS$GETUAI the modified value is returned in the 'dict' object under the key 'contxt'. Feed this value into the 'contxt' argument for the next call to vms_sys.getuai(). Note: the contxt argument is only useful for repeated access to _the same_ username! SYS$GETUAI does not provide any wildcard access over all usernames in the user authorization file (UAF). The pyvms.uaf_get_usernames() function can be used to get a Python for OpenVMS -Reference Manual PAGE 2-395 vms_sys.getuai() routine list of all usernames that are stored in the UAF. usrnam Name of the user about whom SYS$GETUAI should return information. itmlst Item list specifying which information from the specified user's user authorization file (UAF) record is to be returned. You must specify a tuple of strings. See the examples below. It is possible to put an item tuple - e. g.: ('UAI$_ACCOUNT',None) - instead of a single string - e. g.: 'UAI$_ACCOUNT' -, but this is not required for output-only items. According to the OpenVMS V6.1 documentation on which the implementation is based SYS$GETUAI does not take any input items. If the programmer specifies one, the behaviour is unpredictable! special notes about some item codes: UAI$_ACCOUNT is returned as delivered by the system service - with trailing spaces UAI$_BATCH_ACCESS_P + UAI$_BATCH_ACCESS_S are returned as a 3-integer tuple UAI$_DEF_PRIV is returned as an unsigned 'Python long integer' which emulates VMS quadwords. Privilege bitmask values are stored in module vms_prvdef. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. UAI$_DIALUP_ACCESS_P + UAI$_DIALUP_ACCESS_S are returned as a 3-integer tuple UAI$_EXPIRATION is returned as a 'Python long integer' which emulates VMS quadwords. vms_sys.asctim() can be used to translate the value to its ASCII representation. UAI$_ENCRYPT + UAI$_ENCRYPT2 constants (UAI_C_name) for these fields are in module 'vms_uaidef'. UAI$_FLAGS Bitmask values for this field are in module 'vms_uaidef'. UAI$_LASTLOGIN_I + UAI$_LASTLOGIN_N are returned as 'Python long integer' which emulate VMS quadwords. vms_sys.asctim() can be used to translate the values to their ASCII representations. UAI$_LOCAL_ACCESS_P + UAI$_LOCAL_ACCESS_S are returned as a 3-integer tuple UAI$_NETWORK_ACCESS_P + UAI$_NETWORK_ACCESS_P are returned as a 3-integer tuple UAI$_PRCCNT the documentation of OpenVMS V6.1 describes the data type as a longword - this is wrong, a WORD is returned. UAI$_PRIMEDAYS Python for OpenVMS -Reference Manual PAGE 2-396 vms_sys.getuai() routine Bitmask values for this field (UAI_M_MONDAY through UAI_M_SUNDAY) are defined in module 'vms_uaidef'. The documentation of OpenVMS V6.1 describes the data type as a longword - this is wrong, a BYTE is returned. UAI$_PRIV is returned as an unsigned 'Python long integer' which emulates VMS quadwords. Privilege bitmask values are stored in module vms_prvdef. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. UAI$_PWD + UAI$_PWD2 are returned as unsigned 'Python long integers' which emulate VMS quadwords. UAI$_PWD_DATE + UAI$_PWD2_DATE are returned as 'Python long integers' which emulate VMS quadwords. vms_sys.asctim() can be used to translate the values to their ASCII representations. UAI$_PWD_LIFETIME + UAI$_PWD2_LIFETIME are returned as 'Python long integers' which emulate VMS quadwords vms_sys.asctim() can be used to translate the values to their ASCII representations. UAI$_REMOTE_ACCESS_P + UAI$_REMOTE_ACCESS_S are returned as a 3-integer tuple Examples: UAF> add GETUAI_TST /owner= "PYTHON-getuai-TEST" - /uic= [12345,13524] /account= "PYTHON_G" - /cli= "CLI_TEST" /clitables= "DCLTABLES_TEST" - /lgicmd= "LGICMD_TEST" - /flags= (dismail, disuser, restrict) - /privileges= (noALL, TMPMBX) /defprivileges= (noALL, TMPMBX) UAF> modify GETUAI_TST - /device= "DEFDEV_TEST" /directory= [DEFDIRTEST] UAF> modify GETUAI_TST - /interactive /batch /network UAF> modify GETUAI_TST /primedays= (noSATURDAY, noSUNDAY) - /expiration= "29-FEB-2000 12:34:56.78" /pwdminimum= 12 - /pwdlifetime= "12-21:43:56.87" UAF> modify GETUAI_TST /maxjobs= 11 /maxacctjobs= 12 /prclm= 13 - /priority= 14 /queprio= 15 /cputime= "11-22:33:44.55" - /fillm= 111 /shrfillm= 112 /biolm= 113 /diolm= 114 - /astlm= 115 /tqelm= 116 /enqlm= 117 UAF> modify GETUAI_TST /bytlm= 1111 /pbytlm= 1112 /jtquota= 1113 - /wsdefault= 1114 /wsquota= 1115 /wsextent= 1116 - /pgflquota= 1117 /password= XYZ UAF> modify GETUAI_TST /local= - (PRIMARY, 1-3,7,12-15, SECONDARY, 1-8,9,11,17-21,23) Python for OpenVMS -Reference Manual PAGE 2-397 vms_sys.getuai() routine UAF> modify GETUAI_TST /network= - (PRIMARY, 1,3,5,7,9,11,13,15,17,19,21,23, - SECONDARY, 0,2,4,6,8,10,12,14,16,18,20,22) UAF> show GETUAI_TST Username: GETUAI_TST Owner: PYTHON-getuai-TEST Account: PYTHON_G UIC: [12345,13524] ([PYTHON_G,GETUAI_TST]) CLI: CLI_TEST Tables: DCLTABLES_TEST Default: DEFDEV_TEST:[DEFDIRTEST] LGICMD: LGICMD_TEST Flags: DefCLI Restricted DisUser DisMail Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: -#-#-#-#-#-#-#-#-#-#-#-# #-#-#-#-#-#-#-#-#-#-#-#- Batch: ##### Full access ###### ##### Full access ###### Local: -###---#----####-------- -#########-#-----#####-# Dialup: ##### Full access ###### ##### Full access ###### Remote: ##### Full access ###### ##### Full access ###### Expiration: 29-FEB-2000 12:34 Pwdminimum: 12 Login Fails: 0 Pwdlifetime: 12 21:43 Pwdchange: (pre-expired) Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 11 Fillm: 111 Bytlm: 1111 Maxacctjobs: 12 Shrfillm: 112 Pbytlm: 1112 Maxdetach: 0 BIOlm: 113 JTquota: 1113 Prclm: 13 DIOlm: 114 WSdef: 1114 Prio: 14 ASTlm: 115 WSquo: 1115 Queprio: 15 TQElm: 116 WSextent: 1116 CPU: 11 22:33:44 Enqlm: 117 Pgflquo: 1117 Authorized Privileges: TMPMBX Default Privileges: TMPMBX UAF> >>> import vms_sys >>> dict = vms_sys.getuai (None,None,'GETUAI_TST',('UAI$_OWNER',)) >>> # even a single item-code must be passed as a tuple -------^ >>> type (dict) >>> dict {'UAI$_OWNER': 'PYTHON-getuai-TEST', 'status': 1} >>> dict = vms_sys.getuai (None,None,'GETUAI_TST', \ ... ('UAI$_OWNER', 'UAI$_EXPIRATION')) >>> returned_items = dict.items() >>> returned_items.sort() Python for OpenVMS -Reference Manual PAGE 2-398 vms_sys.getuai() routine >>> for itm in range(len(returned_items)): ... print returned_items[itm] ... ('UAI$_EXPIRATION', 44585444967800000L) ('UAI$_OWNER', 'PYTHON-getuai-TEST') ('status', 1) >>> >>> q_expdat = dict.get('UAI$_EXPIRATION') >>> q_expdat 44585444967800000L >>> type (q_expdat) >>> vms_sys.asctim (q_expdat) '29-FEB-2000 12:34:56.78' >>> >>> # UAI$_CPUTIM is expressed in 10ms steps >>> # this example shows how to make this into a delta-time >>> dict = vms_sys.getuai (None,None,'GETUAI_TST',('UAI$_CPUTIM',)) >>> # even a single item-code must be passed as a tuple --------^ >>> l_cputim = dict.get('UAI$_CPUTIM') >>> # convert 10ms ticks into 100ns ticks >>> q_cputim = l_cputim * 100000L >>> # a delta-time must be negative >>> q_cputim = -q_cputim >>> # show ASCII representation >>> vms_sys.asctim (q_cputim) ' 11 22:33:44.55' >>> >>> # this example shows how to deal with access 'times' >>> dict = vms_sys.getuai (None,None,'GETUAI_TST', \ ... ('UAI$_LOCAL_ACCESS_P', 'UAI$_LOCAL_ACCESS_S' )) >>> returned_items = dict.items() >>> returned_items.sort() >>> for itm in range(len(returned_items)): ... print returned_items[itm] ... ('UAI$_LOCAL_ACCESS_P', (113, 15, 255)) ('UAI$_LOCAL_ACCESS_S', (1, 244, 65)) ('status', 1) >>> >>> ba_local_access_s = dict.get ('UAI$_LOCAL_ACCESS_S') >>> ba_local_access_s (1, 244, 65) >>> l_local_access_s = \ ... ba_local_access_s[0] + (ba_local_access_s[1]*256) + \ ... ba_local_access_s[2] * 65536 Python for OpenVMS -Reference Manual PAGE 2-399 vms_sys.getuai() routine >>> l_local_access_s 4322305 >>> hex (l_local_access_s) '0x41f401' >>> Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Local: -###---#----####-------- -#########-#-----#####-# ^ !---- this is the least significant bit reverse: #-## ###- ---- #-## #### ###- -4-- ---1 8421 -4-- ---- ---1 | | | | | | 4 1 f 4 0 1 >>> # get lots of items >>> dict = vms_sys.getuai (None,None,'GETUAI_TST', ... ('UAI$_ACCOUNT' ,'UAI$_ASTLM' ... ,'UAI$_BATCH_ACCESS_P' ,'UAI$_BATCH_ACCESS_S' ... ,'UAI$_BIOLM' ,'UAI$_BYTLM' ... ,'UAI$_CLITABLES' ,'UAI$_CPUTIM' ... ,'UAI$_DEFCLI' ,'UAI$_DEFDEV' ... ,'UAI$_DEFDIR' ,'UAI$_DEF_PRIV' ... ,'UAI$_DFWSCNT' ,'UAI$_DIALUP_ACCESS_P' ... ,'UAI$_DIALUP_ACCESS_S' ,'UAI$_DIOLM' ... ,'UAI$_ENCRYPT' ,'UAI$_ENCRYPT2' ... ,'UAI$_ENQLM' ,'UAI$_EXPIRATION' ... ,'UAI$_FILLM' ,'UAI$_FLAGS' ... ,'UAI$_GRP' ,'UAI$_JTQUOTA' ... ,'UAI$_LASTLOGIN_I' ,'UAI$_LASTLOGIN_N' ... ,'UAI$_LGICMD' ,'UAI$_LOCAL_ACCESS_P' ... ,'UAI$_LOCAL_ACCESS_S' ,'UAI$_LOGFAILS' ... ,'UAI$_MAXACCTJOBS' ,'UAI$_MAXDETACH' ... ,'UAI$_MAXJOBS' ,'UAI$_MEM' ... ,'UAI$_NETWORK_ACCESS_P' ,'UAI$_NETWORK_ACCESS_S' ... ,'UAI$_OWNER' ,'UAI$_PBYTLM' ... ,'UAI$_PGFLQUOTA' ,'UAI$_PRCCNT' ... ,'UAI$_PRI' ,'UAI$_PRIMEDAYS' ... ,'UAI$_PRIV' ,'UAI$_PWD' ... ,'UAI$_PWD2' ,'UAI$_PWD2_DATE' ... ,'UAI$_PWD_DATE' ,'UAI$_PWD_LENGTH' ... ,'UAI$_PWD_LIFETIME' ,'UAI$_QUEPRI' ... ,'UAI$_REMOTE_ACCESS_P' ,'UAI$_REMOTE_ACCESS_S' ... ,'UAI$_SALT' ,'UAI$_SHRFILLM' ... ,'UAI$_TQCNT' ,'UAI$_UIC' ... ,'UAI$_USERNAME' ,'UAI$_USER_DATA' ... ,'UAI$_WSEXTENT' ,'UAI$_WSQUOTA' ... )) >>> >>> returned_items = dict.items() >>> returned_items.sort() Python for OpenVMS -Reference Manual PAGE 2-400 vms_sys.getuai() routine >>> for itm in range(len(returned_items)): ... print returned_items[itm] ... ('UAI$_ACCOUNT', 'PYTHON_G ') ('UAI$_ASTLM', 115) ('UAI$_BATCH_ACCESS_P', (0, 0, 0)) ('UAI$_BATCH_ACCESS_S', (0, 0, 0)) ('UAI$_BIOLM', 113) ('UAI$_BYTLM', 1111) ('UAI$_CLITABLES', 'DCLTABLES_TEST') ('UAI$_CPUTIM', 103162455) ('UAI$_DEFCLI', 'CLI_TEST') ('UAI$_DEFDEV', 'DEFDEV_TEST:') ('UAI$_DEFDIR', '[DEFDIRTEST]') ('UAI$_DEF_PRIV', 32768L) ('UAI$_DFWSCNT', 1114) ('UAI$_DIALUP_ACCESS_P', (0, 0, 0)) ('UAI$_DIALUP_ACCESS_S', (0, 0, 0)) ('UAI$_DIOLM', 114) ('UAI$_ENCRYPT', 3) ('UAI$_ENCRYPT2', 0) ('UAI$_ENQLM', 117) ('UAI$_EXPIRATION', 44585444967800000L) ('UAI$_FILLM', 111) ('UAI$_FLAGS', 154) ('UAI$_GRP', 5349) ('UAI$_JTQUOTA', 1113) ('UAI$_LASTLOGIN_I', 0L) ('UAI$_LASTLOGIN_N', 0L) ('UAI$_LGICMD', 'LGICMD_TEST') ('UAI$_LOCAL_ACCESS_P', (113, 15, 255)) ('UAI$_LOCAL_ACCESS_S', (1, 244, 65)) ('UAI$_LOGFAILS', 0) ('UAI$_MAXACCTJOBS', 12) ('UAI$_MAXDETACH', 0) ('UAI$_MAXJOBS', 11) ('UAI$_MEM', 5972) ('UAI$_NETWORK_ACCESS_P', (85, 85, 85)) ('UAI$_NETWORK_ACCESS_S', (170, 170, 170)) ('UAI$_OWNER', 'PYTHON-getuai-TEST') ('UAI$_PBYTLM', 1112) ('UAI$_PGFLQUOTA', 1117) ('UAI$_PRCCNT', 13) ('UAI$_PRI', 14) ('UAI$_PRIMEDAYS', 96) ('UAI$_PRIV', 32768L) # @@ construct an example with ('UAI$_PWD', -3994283066824042557L) # @@ module vms_prvdef ('UAI$_PWD2', 0L) ('UAI$_PWD2_DATE', 0L) ('UAI$_PWD_DATE', -1L) ('UAI$_PWD_LENGTH', 12) ('UAI$_PWD_LIFETIME', -11150368700000L) ('UAI$_QUEPRI', 15) ('UAI$_REMOTE_ACCESS_P', (0, 0, 0)) Python for OpenVMS -Reference Manual PAGE 2-401 vms_sys.getuai() routine ('UAI$_REMOTE_ACCESS_S', (0, 0, 0)) ('UAI$_SALT', 29702) ('UAI$_SHRFILLM', 112) ('UAI$_TQCNT', 116) ('UAI$_UIC', 350558036) ('UAI$_USERNAME', 'GETUAI_TST ') ('UAI$_USER_DATA', '') ('UAI$_WSEXTENT', 1116) ('UAI$_WSQUOTA', 1115) ('status', 1) >>> >>> dict = vms_sys.getuai (None,None,'GETUAI_TST', ... ('UAI$_EXPIRATION' ... ,'UAI$_LASTLOGIN_I' ... ,'UAI$_LASTLOGIN_N' ... ,'UAI$_PWD_DATE' ... ,'UAI$_PWD2_DATE' ... ,'UAI$_PWD_LIFETIME' ... )) >>> >>> for key in dict.keys(): ... if (key != 'status'): ... print key, vms_sys.asctim (dict.get(key)) ... UAI$_EXPIRATION 29-FEB-2000 12:34:56.78 UAI$_LASTLOGIN_I 17-NOV-1858 00:00:00.00 <-- no login, yet UAI$_PWD2_DATE 17-NOV-1858 00:00:00.00 UAI$_PWD_DATE 0 00:00:00.00 UAI$_PWD_LIFETIME 12 21:43:56.87 UAI$_LASTLOGIN_N 17-NOV-1858 00:00:00.00 >>> >>> # UIC of username >>> dict = vms_sys.getuai (None,None,'GETUAI_TST', ... ('UAI$_GRP','UAI$_MEM')) >>> w_grp = dict.get('UAI$_GRP') >>> w_mem = dict.get('UAI$_MEM') >>> # oct() puts a '0' in front - [1:] removes this >>> t_uic = '[' + oct(w_grp)[1:] + ',' + oct(w_mem)[1:] + ']' >>> t_uic '[12345,13524]' >>> >>> # calculate date of next password expiration >>> # note that this example uses a different account ("NOPRIV") >>> dict = vms_sys.getuai (None,None,'NOPRIV', ... ('UAI$_PWD_DATE','UAI$_PWD_LIFETIME')) >>> q_expdate = dict.get('UAI$_PWD_DATE') + \ Python for OpenVMS -Reference Manual PAGE 2-402 vms_sys.getuai() routine ... dict.get('UAI$_PWD_LIFETIME') >>> vms_sys.asctim (dict.get('UAI$_PWD_DATE')) '25-SEP-1998 20:10:42.78' >>> vms_sys.asctim (dict.get('UAI$_PWD_LIFETIME')) ' 30 00:00:00.00' >>> vms_sys.asctim (q_expdate) '26-AUG-1998 20:10:42.78' >>> >>> # try access to a non-existent username >>> dict = vms_sys.getuai (None,None,'NO_USER',('UAI$_FILLM',)) >>> l_status = dict.get('status') >>> print l_status 98994 >>> >>> vms_sys.getmsg (l_status)[0] '%RMS-E-RNF, record not found' >>> $!+ $! make a report which user has a FILLM quota is too small $!- $ type USERLIST.DAT DEFAULT SYSTEM NO_SUCHUSR FIELD ZESSIN $ $ type CHK_FILLM.PY import vms_sys # min_fillm = 250 # UAI$_FILLM must be >= 250 # u_file = open ('USERLIST.DAT','r') u_lines = u_file.readlines() u_file.close() # remove trailing NEWLINE for line_number in range (len (u_lines)): u_lines[line_number] = u_lines[line_number][:-1] # # check all users from list for line_number in range (len (u_lines)): username = u_lines[line_number] dict = vms_sys.getuai (None,None,username,('UAI$_FILLM',)) l_status = dict.get('status') if (l_status != 1): # 1 = SS$_NORMAL print 'failed to read UAF record for',\ username, ', status=', l_status else: w_fillm = dict.get('UAI$_FILLM') if (w_fillm < 250): Python for OpenVMS -Reference Manual PAGE 2-403 vms_sys.getuai() routine print 'FILLM =', w_fillm, 'too small for user', \ username # # # $ python CHK_FILLM.PY FILLM = 20 too small for user DEFAULT failed to read UAF record for NO_SUCHUSR , status= 98994 FILLM = 100 too small for user FIELD $! ! $ write sys$output f$message (98994) ! <-------------^ %RMS-E-RNF, record not found $ >>> # username is a string ----------v >>> dict = vms_sys.getuai (None,None,1,('UAI$_FILLM',)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: expected read-only buffer, int found >>> # that means 'string' ------^^^^^^^^^ >>> # even a single item-code must be passed as a tuple ----v >>> dict = vms_sys.getuai (None,None,'NO_USER',('UAI$_FILLM')) Traceback (innermost last): File "", line 1, in ? TypeError: argument 4: itmlst - must be a tuple of strings >>> >>> dict = vms_sys.getuai (None,None,'NO_USER',('UAI$_BAD-ITM',)) Traceback (innermost last): File "", line 1, in ? ValueError: itmlst - unknown item code: UAI$_BAD-ITM >>> >>> # 'item-code' must be string ---------------v >>> dict = vms_sys.getuai (None,None,'NO_USER',(1,)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 4: tuple-element:0 item code must be a string >>> 10-NOV-1999 ZE. ------------------------------------------------------------------------ 2.6.39 GETUTC - Get UTC Time Returns the current time in 128-bit UTC format. Format: utcadr = vms_sys.getutc () Python for OpenVMS -Reference Manual PAGE 2-404 vms_sys.getutc() routine Returns: utcadr 128-bit UTC value - a Python long integer Arguments: vms_sys.getutc() does not take any arguments. Examples: >>> import vms_sys >>> o_utctim = vms_sys.getutc () >>> print o_utctim 21584378040929278433485881178387187456L >>> print vms_sys.ascutc (o_utctim) 9-JAN-1999 19:59:12.88 >>> print vms_sys.asctim () 9-JAN-1999 19:59:58.44 >>> 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 >>> 09-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.40 GET_SECURITY - Get Security Characteristics Retrieves the security characteristics of an object. vms_sys.get_security() does _not_ raise an exception when the SYS$GET_SECURITY routine returns an error. You must check 'status' in the dictionary that is returned. Format: dict = vms_sys.get_security \ ([clsnam], [objnam], [objhan], [flags], \ [itmlst], [contxt] ,[acmode]) Python for OpenVMS -Reference Manual PAGE 2-405 vms_sys.get_security() routine Returns: dict A dictionary that has the following keys: 'status' the condition value returned from SYS$GET_SECURITY. 'contxt' the context value if and only if the 'contxt' argument was specified. It is only put into the dictionary, when SYS$GET_SECURITY returns a success status. 'OSS$_name' Any output item that has been specified in the item-list and that is supported by SYS$GET_SECURITY. It is only put into the dictionary, when SYS$GET_SECURITY returns a success status. Warning! The dictionary can contain binary strings - do not use the print command to output them on the terminal! Arguments: clsnam Name of the object class. E.g.: "FILE" or "QUEUE". Please see the system services reference manual for a complete list. objnam Name of the protected object whose associated security profile is going to be retrieved. See the system services reference manual for details. objhan "object handle" - this is a Python (32-bit) integer. Please see the system services reference manual for how this is passed. @@ Argument not tested. flags Mask specifying processing options. Symbolic names (OSS_M_name) are available in module 'vms_ossdef'. itmlst Item list specifying which information about the object(s) is to be returned. contxt Value used to maintain the processing context when dealing with a single protected object across multiple vms_sys.get_security() or vms_sys.set_security() calls. Don't forget to release the context after use - see the examples section below. acmode According to the documentation, this argument should not be Python for OpenVMS -Reference Manual PAGE 2-406 vms_sys.get_security() routine used. special notes about some item codes: OSS$_ACCESS_NAMES Returns a 'vmsobj__access_names' object. OSS$_ACL_FIND_ENTRY Expects a binary ACE. See the examples section below and the comments about 'ACL + ACE' in the 'programming' section of the 'General Manual'. OSS$_ACL_FIND_NEXT Internally, this is a 'boolean item' - you just specify the item code in the Python item list. OSS$_ACL_FIND_TYPE @@ Unknown. Not tested, yet. OSS$_ACL_GRANT_ACE You must check the status code - see the examples section below. OSS$_ACL_POSITION_BOTTOM + OSS$_ACL_POSITION_TOP Are boolean item codes like OSS$_ACL_FIND_NEXT, above. OSS$_ACL_READ Returns the entire ACL as a Python string. Note that the string contains binary data - do not print this to your terminal! OSS$_ACL_READ_ENTRY Returns a single ACE as a Python string. Note that the string contains binary data - do not print this to your terminal! OSS$_OWNER This is the object's owner UIC - a 32-bit Python integer. OSS$_PROTECTION This is the object's UIC-based protection code - a 16-bit value that is returned in a 32-bit Python integer. No tests have been done with profile related item codes. Be aware that this system service is not very good documented (I have filed a complaint) and it does not fill in the returned length of several items. That is the reason that several 'converter functions' are defined in file VMSDEF_$OSSDEF.DAT Examples: $ copy _NLA0: ACL.DAT $ set ACL ACL.DAT - /ACL= ( (default_protection, s:rwed, o:wd, g:r, w:e), - (alarm= security, options=default, access=write+failure), - (identifier= [1,4], access= read+write), - (identifier= [2,5], access= delete+execute), - (identifier= [3,6], access= control) ) $! $ directory /acl ACL.DAT Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] Python for OpenVMS -Reference Manual PAGE 2-407 vms_sys.get_security() routine ACL.DAT;1 (ALARM=SECURITY,OPTIONS=DEFAULT,ACCESS=WRITE+FAILURE) (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:WD,GROUP:R,WORLD:E) (IDENTIFIER=[G1,SYSTEM],ACCESS=READ+WRITE) (IDENTIFIER=[2,5],ACCESS=EXECUTE+DELETE) (IDENTIFIER=[3,6],ACCESS=CONTROL) Total of 1 file. $! ---------------------------------------- ----- get the entire ACL >>> import vms_ossdef, vms_sys >>> contxt = 0 >>> flags = 0 >>> itmlst = (('OSS$_ACL_READ',),) >>> dict = vms_sys.get_security ('FILE', 'ACL.DAT', None, \ ... flags, itmlst, contxt) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> aclstr = dict.get ('OSS$_ACL_READ') >>> print repr (aclstr) '\020\006\002\001\002\000\000\000SECURITY\030\011\000\000 \000\000\000\000\020\000\000\000\025\000\000\000\036\000\ 000\000\033\000\000\000\014\001\000\000\003\000\000\000\0 04\000\001\000\014\001\000\000\014\000\000\000\005\000\00 2\000\014\001\000\000\020\000\000\000\006\000\003\000' >>> >>> # release the context >>> contxt = dict.get ('contxt') >>> flags = vms_ossdef.OSS_M_RELCTX >>> >>> dict = vms_sys.get_security (None, None, None, flags, \ ... None, contxt) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> contxt = dict.get ('contxt') >>> print contxt 0 <-- context has been released >>> ----- locate a particular ACE and read the one after it >>> import vms_ossdef, vms_sys >>> >>> acetxt = '(IDENTIFIER=[1,4],ACCESS=READ+WRITE)' >>> status, errpos, acestr = vms_sys.parse_acl (acetxt) Python for OpenVMS -Reference Manual PAGE 2-408 vms_sys.get_security() routine >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> contxt = 0 >>> flags = 0 >>> >>> itmlst = ( ('OSS$_ACL_FIND_ENTRY',acestr), \ ... ('OSS$_ACL_FIND_NEXT',), \ ... ('OSS$_ACL_READ_ENTRY',) ) >>> >>> dict = vms_sys.get_security ('FILE', 'ACL.DAT', None, \ ... flags, itmlst, contxt) >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> acestr = dict.get ('OSS$_ACL_READ_ENTRY') >>> print vms_sys.format_acl (acestr, 90, '*', 2) (1, ' (IDENTIFIER=[2,5],ACCESS=EXECUTE+DELETE)') >>> >>> # release the context >>> contxt = dict.get ('contxt') >>> flags = vms_ossdef.OSS_M_RELCTX >>> >>> dict = vms_sys.get_security (None, None, None, flags, \ ... None, contxt) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> contxt = dict.get ('contxt') >>> print contxt 0 <-- context has been released >>> ----- try to find out if an ACE grants or denies access >>> import vms_ossdef, vms_sys >>> >>> contxt = 0 >>> flags = 0 >>> itmlst = ( ('OSS$_ACL_GRANT_ACE',),) >>> >>> dict = vms_sys.get_security ('FILE', 'ACL.DAT', None, \ ... flags, itmlst, contxt) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-W-NOENTRY, access control entry not found >>> >>> contxt = dict.get ('contxt') >>> print contxt 0 <-- no context was established >>> Python for OpenVMS -Reference Manual PAGE 2-409 vms_sys.get_security() routine 19-JUL-1999 ZE. ------------------------------------------------------------------------ 2.6.41 GRANTID - Grant Identifier to Process Adds the specified identifier record to the rights list of the process or the system. Format: setflg, targpid, id, prvatr = vms_sys.grantid \ ([pidadr] [,prcnam] [,id] [,name]) Returns: setflg The system service returns SS$_WASSET or SS$_WASCLR to indicate if the rightslist did or did not contain the identifier before. The Python function does not return the status code - it returns 0 if the identifier did not exist in the rightslist before and returns 1 if it did. Any other code returned from the system service results in a Python exception. targpid Process identification of process to be affected. A value of -1 indicates the system rights list. 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.grantid() raises a Python exception. id Identifier and attributes which have been granted. These are even returned when the programmer specifies 'None' as argument 3. The Python function returns a tuple of 2 integers - not a quadword represented by a Python long integer. The first element contains the binary identifier code. The second element contains the attributes. Bitmask values for these attributes are defined in module 'vms_kgbdef'. prvatr Previous attributes of the identifier if it was previously present in the rights list. Arguments: pidadr Process identification of process to be affected. prcnam Process name of process to be affected. id Identifier and attributes to be granted. Python for OpenVMS -Reference Manual PAGE 2-410 vms_sys.grantid() routine The Python function only accepts a tuple of 2 integers - not a quadword represented by a Python long integer. The first element contains the binary identifier code. The second element contains the attributes. Bitmask values for these attributes are defined in module 'vms_kgbdef'. name Name of the identifier to be granted - this is a string. Examples: $ show process /rights 2-SEP-1998 21:20:58.18 User: ZESSIN Process ID: 0000005B Node: HERE Process name: "ZESSIN_FTA9" Process rights: INTERACTIVE LOCAL System rights: SYS$NODE_HERE $ >>> import vms_sys >>> import vms_kgbdef >>> pid = 91 >>> id = 0x80010011 # ID_1 >>> attr = vms_kgbdef.KGB_M_RESOURCE >>> # show grant by ID (process identification and binary identifier) >>> vms_sys.grantid (pid, None, (id,attr), None) (0, 91, (-2147418095, 1), 0) >>> print vms_kgbdef.KGB_M_RESOURCE 1 >>> $ show process /rights 2-SEP-1998 21:33:41.94 User: ZESSIN Process ID: 0000005B Node: HERE Process name: "ZESSIN_FTA9" Process rights: INTERACTIVE LOCAL ID_1 resource <-- System rights: SYS$NODE_HERE $ >>> # show grant by name (process name and identifier name) >>> vms_sys.grantid (None, 'ZESSIN_FTA9', None, 'ID_2') Python for OpenVMS -Reference Manual PAGE 2-411 vms_sys.grantid() routine (0, 91, (-2147418094, 2), 0) >>> id = -2147418094 # check >>> namlen, nambuf, resid, attrib, id_ctx = vms_sys.idtoasc (id,0) >>> nambuf 'ID_2' >>> $ show process /rights 2-SEP-1998 21:43:26.73 User: ZESSIN Process ID: 0000005B Node: HERE Process name: "ZESSIN_FTA9" Process rights: INTERACTIVE LOCAL ID_1 resource ID_2 dynamic <-- System rights: SYS$NODE_HERE $ >>> # put an identifier into the system rights list >>> # -- requires SYSNAM privilege >>> id = 0x80010011 # ID_1 >>> attr = vms_kgbdef.KGB_M_RESOURCE >>> vms_sys.grantid (-1, None, (id,attr), None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (10260, '%SYSTEM-F-NOSYSNAM, operation requires SYSNAM \ privilege') [...] >>> vms_sys.grantid (-1, None, (id,attr), None) (0, -1, (-2147418095, 1), 0) >>> >>> attr = attr + vms_kgbdef.KGB_M_DYNAMIC >>> vms_sys.grantid (-1, None, (id,attr), None) (1, -1, (-2147418095, 3), 1) | | | | |- old attributes (KGB_M_RESOURCE) | | | |----- current attributes | | |------------------ identifier value | |----------------------- PID, -1 = system rights list |-------------------------- setflg = 1 -- identifier was already in the system rights list >>> $ show process /rights 2-SEP-1998 21:46:06.84 User: ZESSIN Process ID: 0000005B Node: HERE Process name: "ZESSIN_FTA9" Process rights: Python for OpenVMS -Reference Manual PAGE 2-412 vms_sys.grantid() routine INTERACTIVE LOCAL ID_1 resource ID_2 dynamic System rights: SYS$NODE_HERE ID_1 resource, dynamic <-- $ @@ GRANTID - more examples >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.42 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 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 ? Python for OpenVMS -Reference Manual PAGE 2-413 vms_sys.hiber() routine 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 >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.43 IDTOASC - Translate Identifier to Identifier Name Translates the specified identifier value to its identifier name. Format: nambuf, resid, attrib, fnd_ctx = \ vms_sys.idtoasc (id [,contxt]) Returns: nambuf Identifier name text string. resid Identifier value of the identifier name returned in 'nambuf'. attrib Mask of attributes associated with the holder record specified by holder. Bitmask values are defined in module 'vms_kgbdef'. fnd_ctx Context value after the call to IDTOASC. This value must be fed unchanged into the 'contxt' argument on the next call. A value is always returned, even if the 'contxt' argument is omitted. Arguments: id Binary identifier value to be translated. -1 indicates a wildcard search. contxt Context value used when repeatedly calling IDTOASC. See the system services reference manual for more information. Examples: UAF> add /identifier ID_1 /attributes=resource %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=dynamic %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database Python for OpenVMS -Reference Manual PAGE 2-414 vms_sys.idtoasc() routine UAF> grant /identifier ID_1 SYSTEM /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to SYSTEM UAF> grant /identifier ID_1 ZESSIN /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to ZESSIN UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE ZESSIN RESOURCE UAF> >>> import vms_sys >>> def show_uic (uic_value): ... high_word = uic_value / 65536 ... low_word = uic_value - (high_word * 65536) ... # Note: [1:], because octal values will be preceeded by '0' ... uic_string = \ ... '[' + oct(high_word)[1:] + ',' + oct(low_word)[1:] + ']' ... print uic_string ... >>> >>> id = 0x80010011 # identifier ID_1 >>> nambuf, resid, attrib, fnd_ctx = \ ... vms_sys.idtoasc (id, None) >>> nambuf, resid, attrib, fnd_ctx ('ID_1', -2147418095, 1, 0) >>> print hex (-2147418095) 0x80010011 >>> >>> import vms_kgbdef >>> print attrib, vms_kgbdef.KGB_M_RESOURCE 1 1 >>> >>> id = 0x10004 # UIC [1,4] >>> nambuf, resid, attrib, fnd_ctx = \ ... vms_sys.idtoasc (id, None) >>> nambuf, resid, attrib, fnd_ctx ('SYSTEM', 65540, 0, 0) >>> show_uic (resid) [1,4] >>> >>> id = -1 # do a wildcard lookup >>> context = 0 >>> while (1): ... nambuf, resid, attrib, fnd_ctx = \ Python for OpenVMS -Reference Manual PAGE 2-415 vms_sys.idtoasc() routine ... vms_sys.idtoasc (id, context) ... print nambuf ... context = fnd_ctx ... BATCH DECNET DECWINDOWS DEFAULT DIALUP FAL$SERVER FIELD [...] VPM$SERVER ZESSIN Traceback (innermost last): File "", line 2, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> # this loop intentionally aborted by an exception >>> # Note: it is not necessary to release the context with a call >>> # to FINISH_RDB because the loop ran to completion >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.44 INIT_VOL - Initialize Volume Formats a disk or magnetic tape volume. Format: dict = vms_sys.init_vol (devnam, volnam [,itmlst]) Returns: dict A dictionary that has the following keys: 'status' the condition value returned from SYS$INIT_VOL. Arguments: devnam Name of the device on which the volume is physically mounted. volnam Volume identification (label). itmlst Item list specifiying the options for the init_vol operation. Python for OpenVMS -Reference Manual PAGE 2-416 vms_sys.init_vol() routine special notes about some item codes: INIT$_BADBLOCKS_LBN Must be supplied as a tuple of 2-integer tuples. On OpenVMS VAX V6.1 it was not possible to specify more than one (LBN,count) combination. As this item code is unlikely to be used very often this issue has been put aside for the moment (24-JAN-1999). INIT$_BADBLOCKS_SEC Must be supplied as a tuple of 4-integer tuples. Has not been tested. The same limitation as INIT$_BADBLOCKS_LBN might be there. Examples: >>> import vms_sys >>> vms_sys.init_vol ('VDA0:','LBL',(('INIT$_CLUSTERSIZE',7),)) {'status': 1} >>> >>> vms_sys.init_vol ('VDA0:','LBL', ... ( ... ('INIT$_CLUSTERSIZE',1), ... ('INIT$_ERASE') ... ) ... ) >>> >>> vms_sys.init_vol ('VDA0:','LBL', ... ( ... ('INIT$_BADBLOCKS_LBN', ((30,1),(40,2)) ), ... ('INIT$_CLUSTERSIZE' , 1) ... ) ... ) {'status': 20} --------------- >>> vms_sys.init_vol ('VDA0:','LBL',(('INIT$_CLUSTERSIZE',7),)) %INIT-F-NOVOLPRO, operation requires VOLPRO privilege {'status': 276113580} >>> @@ INIT_VOL - more examples, text >>> 17-JAN-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-417 vms_sys.mod_holder() routine 2.6.45 MOD_HOLDER - Modify Holder Record in Rights Database Modifies the specified holder record of the target identifier in the rights database. Format: vms_sys.mod_holder (id, holder, [,set_attrib] [,clr_attrib]) Returns: None Arguments: id Binary value of target identifier to be modified. holder Identifier of holder to be modified. The Python function only accepts a tuple of 2 integers - not a quadword represented by a Python long integer. For OpenVMS V6.1 the first element is the holder's UIC identifier, the second element must be 0. Check the system services reference manual for your version of OpenVMS. set_attrib Bit mask of attributes to be enabled for the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled. Bitmask values are defined in module 'vms_kgbdef'. clr_attrib Bit mask of attributes to be disabled for the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled. Bitmask values are defined in module 'vms_kgbdef'. Examples: UAF> add /identifier ID_1 /attributes=resource %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=(dynamic,resource) %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database UAF> grant /identifier ID_1 SYSTEM /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to SYSTEM UAF> grant /identifier ID_2 SYSTEM /attributes=(dynamic) UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 RESOURCE DYNAMIC Python for OpenVMS -Reference Manual PAGE 2-418 vms_sys.mod_holder() routine Holder Attributes SYSTEM DYNAMIC UAF> >>> import vms_sys >>> import vms_kgbdef >>> id_1 = 0x80010011 # identifier ID_1 >>> id_2 = 0x80010012 # identifier ID_1 >>> uic = 0x10004 # UIC [1,4] (User SYSTEM) >>> vms_sys.mod_holder (id_1, (uic,0), None, vms_kgbdef.KGB_M_RESOURCE) UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM UAF> ! attribute removed !!!!!!!!!! >>> clr_attr = vms_kgbdef.KGB_M_DYNAMIC >>> set_attr = vms_kgbdef.KGB_M_RESOURCE >>> vms_sys.mod_holder (id_1, (uic,0), clr_attr, set_attr) UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 RESOURCE DYNAMIC Holder Attributes SYSTEM DYNAMIC UAF> ! RESOURCE removed, DYNAMIC applied !!! >>> id_x = 0x80012345 # ungranted identifier >>> vms_sys.mod_holder (id_x, (uic,0), clr_attr, set_attr) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> uic_x = 0x30003 # UIC without name >>> vms_sys.mod_holder (id_1, (uic_x,0), clr_attr, set_attr) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> vms_sys.mod_holder (id_1, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - must be a tuple of 2 integers >>> >>> vms_sys.mod_holder (id_1, (0,'X')) Python for OpenVMS -Reference Manual PAGE 2-419 vms_sys.mod_holder() routine Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - tuple-element:1 is not an integer >>> >>> vms_sys.mod_holder (id_1, ('X',0)) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - tuple-element:0 is not an integer >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.46 MOD_IDENT - Modify Identifier in Rights Database Modifies the specified identifier record in the rights database. Format: vms_sys.mod_ident (id [,set_attrib] [,clr_attrib] \ [,new_name] [,new_value]) Returns: None Arguments: id Binary value of identifier to be modified. set_attrib Bit mask of attributes to be enabled for the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled. Bitmask values are defined in module 'vms_kgbdef'. clr_attrib Bit mask of attributes to be disabled for the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled. Bitmask values are defined in module 'vms_kgbdef'. new_name New name to be given to the specified identifier. See the system services reference manual for the allowed characters. new_value New value to be assigned to the specified identifier. When the identifier value is changed, MOD_IDENT also changes the value of the identifier in all of the holder records in which the specified identifier appears. Examples: UAF> add /identifier ID_1 /attributes=resource Python for OpenVMS -Reference Manual PAGE 2-420 vms_sys.mod_ident() routine %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=(dynamic,resource) %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 RESOURCE DYNAMIC UAF> >>> import vms_sys >>> import vms_kgbdef >>> id_1 = 0x80010011 # identifier ID_1 >>> id_2 = 0x80010012 # identifier ID_2 >>> at_dyn = vms_kgbdef.KGB_M_DYNAMIC >>> vms_sys.mod_ident (id_1, at_dyn, vms_kgbdef.KGB_M_RESOURCE) UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 DYNAMIC UAF> ! RESOURCE cleared, DYNAMIC set >>> # try to change the identifier value of ID_1 to that of ID_2 >>> # which already exists >>> vms_sys.mod_ident (id_1, None, None, None, id_2) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8748, '%SYSTEM-F-DUPIDENT, duplicate identifier') >>> >>> # try to change the identifier value of ID_1 to an unused value >>> vms_sys.mod_ident (id_1, None, None, None, 0x80012345) UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80012345 DYNAMIC UAF> >>> # ID_1 has a new value after above operation ! >>> id_1 = 0x80012345 >>> # try to rename identifier %X80012345 (named ID_1) to ID_2 which >>> # does already exist >>> vms_sys.mod_ident (id_1, None, None, 'ID_2') Traceback (innermost last): File "", line 1, in ? vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name') >>> >>> # rename identifier %X80012345 (named ID_1) to ID_1X which Python for OpenVMS -Reference Manual PAGE 2-421 vms_sys.mod_ident() routine >>> # does not exist >>> vms_sys.mod_ident (id_1, None, None, 'ID_1X') UAF> show /identifier /full ID_1X Name Value Attributes ID_1X %X80012345 DYNAMIC UAF> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.47 MOUNT - Mount Volume Mounts a tape or disk volume, or a volume set. Format: vms_sys.mount (itmlst) Returns: None Arguments: itmlst Item list specifiying the options for the mount operation. special notes about some item codes: MNT$_FLAGS Must be supplied as a 2-integer tuple. Bitmasks whose names begin with MNT_M_ go into the first integer. Bitmasks whose names begin with MNT2_M_ go into the second integer. The bitmask values are defined in module 'vms_mntdef'. MNT$_UCS Is currently not available. It requires a descriptor containing a Universal Character Sequence (UCS) defined by ISO 2022 and used when mounting an ISO 9660 CD-ROM. This is described in the 'OpenVMS System Manager's Manual'. MNT$_UNDEFINED_FAT Internal this is a structure of one word followed by 2 bytes. The interface routine currently requires a Python integer. Examples: >>> import vms_sys >>> import vms_mntdef Python for OpenVMS -Reference Manual PAGE 2-422 vms_sys.mount() routine >>> l_flags0 = vms_mntdef.MNT_M_MESSAGE + \ ... vms_mntdef.MNT_M_NOASSIST + \ ... vms_mntdef.MNT_M_NOREBUILD + \ ... vms_mntdef.MNT_M_SYSTEM >>> l_flags1 = vms_mntdef.MNT2_M_SUBSYSTEM >>> q_flags = (l_flags0,l_flags1) >>> itmlst = ( \ ... ('MNT$_DEVNAM', 'DKA0:'), ... ('MNT$_FLAGS', q_flags), ... ('MNT$_LOGNAM', 'DISK0_DEVNAM'), ... ('MNT$_VOLNAM', 'D0') # label ... ) >>> vms_sys.mount(itmlst) {'status': 1} >>> >>> vms_sys.getmsg(1) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> vms_sys.mount(itmlst) {'status': 7471212} >>> vms_sys.getmsg(7471212) ('%MOUNT-F-DEVMOUNT, device is already mounted', (0, 0, 0, 0)) >>> >>> vms_sys.dismou ('DKA0:') >>> itmlst = ( \ ('MNT$_DEVNAM', 'DKA0:'), ('MNT$_FLAGS', q_flags), ('MNT$_LOGNAM', 'DISK0_DEVNAM'), ('MNT$_VOLNAM', 'DX') # wrong label ) >>> vms_sys.mount(itmlst) >>> vms_sys.getmsg(7471372) ('%MOUNT-F-INCVOLLABEL, incorrect volume label', (0, 0, 0, 0)) >>> @@ MOUNT - more examples, text >>> 17-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.48 NUMTIM - Convert Binary Time to Numeric Time Format: timbuf = vms_sys.numtim ([timadr]) Python for OpenVMS -Reference Manual PAGE 2-423 vms_sys.numtim() routine Returns: timbuf a tuple of 7 (16-bit) integers consisting of: (year, month, day, hour, minute, second, hundredth) Arguments: timadr 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_sys >>> q_date = vms_sys.bintim ('29-FEB-2000 12:34:56.78') >>> q_date 44585444967800000L >>> vms_sys.numtim (q_date) (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 ? TypeError: argument 1: timadr - must be long integer >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.49 NUMUTC - Convert UTC Time to Numeric Components Format: timbuf = vms_sys.numutc ([utcadr]) Python for OpenVMS -Reference Manual PAGE 2-424 vms_sys.numutc() routine 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 - a Python long integer. Examples: >>> import vms_sys >>> o_binutc = vms_sys.binutc ('29-FEB-2000 12:34:56.78') >>> print o_binutc 21584378040929278433486240335826187456L >>> vms_sys.numutc (o_binutc) (2000, 2, 29, 12, 34, 56, 78, -1, -1, -1, -1, -1, 60) >>> >>> vms_sys.asctim () ' 9-JAN-1999 20:58:01.24' >>> vms_sys.numutc () (1999, 1, 9, 20, 58, 1, 32, -1, -1, -1, -1, -1, 60) >>> vms_sys.numutc (None) (1999, 1, 9, 20, 58, 1, 42, -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 ? TypeError: argument 1: utcadr - must be long integer >>> 09-JAN-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-425 vms_sys.parse_acl() routine 2.6.50 PARSE_ACL - Parse Access Control List Entry Parses the specified text string and converts it to the binary representation for an access control entry (ACE). Format: status, errpos, aclent = vms_sys.parse_acl (aclstr ,[accnam] ,[nullarg]) Returns: status Condition value from SYS$PARSE_ACL. errpos Number of characters from aclstr processed by $PARSE_ACL. If the service fails, this count points to the failing point in the string. aclent ACE, binary. See the system services reference manual for an explanation of how it is formatted, Arguments: aclstr Formatted ACE that is to be translated to its binary representationm by SYS$PARSE_ACL. accnam Names of the bits in the access mask. Specify 'None' to indicate omission of this argument or a 'vmsobj__access_names' object. nullarg Placeholder argument - any input other than None is an error. Examples: >>> import vms_sys >>> >>> aclstr = '(identifier= [1,4], access= read+write)' >>> >>> status, errpos, aclent = vms_sys.parse_acl (aclstr) >>> print vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> print errpos 39 >>> print len(aclstr) 39 >>> print repr(aclent) '\014\001\000\000\003\000\000\000\004\000\001\000' >>> # note that this is OCTAL representation >>> aclstr = '(identifier= [2,7], access= read+submit)' >>> Python for OpenVMS -Reference Manual PAGE 2-426 vms_sys.parse_acl() routine >>> # default is to use FILE access names >>> status, errpos, aclent = vms_sys.parse_acl (aclstr, None) >>> print vms_sys.getmsg (status) %SYSTEM-F-IVACL, invalid access control list entry syntax >>> print errpos 20 >>> print repr (aclstr[errpos:]) 'access= read+submit)' >>> print repr(aclent) '' >>> >>> import vms_lib >>> >>> # get access names table of QUEUE >>> accnam_queue = vms_lib.get_accnam ('QUEUE') >>> print accnam_queue >>> status, errpos, aclent = vms_sys.parse_acl (aclstr, accnam_queue) >>> print vms_sys.getmsg (status) %SYSTEM-S-NORMAL, normal successful completion >>> print errpos 40 >>> print len(aclstr) 40 >>> print repr(aclent) '\014\001\000\000\003\000\000\000\007\000\002\000' >>> # note that this is OCTAL representation @@ more vms_sys.parse_acl() examples >>> 11-JUL-1999 ZE. ------------------------------------------------------------------------ 2.6.51 PERSONA_ASSUME - Assume Persona Format: None = vms_sys.persona_assume (persona [,flags]) Returns: None Arguments: persona The persona handle which was created by vms_sys.persona_create() flags Bitmask values like IMP_M_ASSUME_SECURITY are in module Python for OpenVMS -Reference Manual PAGE 2-427 vms_sys.persona_assume() routine 'vms_impdef'. Examples: See the 'examples' section of the vms_sys.persona_create() routine. 01-JUL-2001 ZE. ------------------------------------------------------------------------ 2.6.52 PERSONA_CREATE - Create Persona Format: persona = vms_sys.persona_create (usrnam [,flags]) Returns: persona The persona handle. Arguments: usrnam Name of the user to be impersonated. flags Bitmask values like IMP_M_ASSUME_DEFPRIV are in module 'vms_impdef'. Examples: >>> import vms_sys >>> import vms_impdef >>> import vms_lib >>> print vms_lib.getjpi ('JPI$_USERNAME',0) (413, 'ZESSIN ') >>> >>> persona = vms_sys.persona_create ('SYSTEM') >>> print persona 4 >>> >>> vms_sys.persona_assume (persona, vms_impdef.IMP_M_ASSUME_SECURITY) >>> print vms_lib.getjpi ('JPI$_USERNAME',0) (413, 'SYSTEM ') >>> >>> vms_sys.persona_delete (persona) Traceback (most recent call last): File "", line 1, in ? vms_sys.error: [Errno 11282] %SYSTEM-E-INUSE, persona cannot be\ deleted as it is currently in use Python for OpenVMS -Reference Manual PAGE 2-428 vms_sys.persona_create() routine >>> >>> vms_sys.persona_assume (1) >>> print vms_lib.getjpi ('JPI$_USERNAME',0) (413, 'ZESSIN ') >>> >>> vms_sys.persona_delete (persona) >>> ---------------------------------------- >>> persona = vms_sys.persona_create ('SYSTEM') Traceback (most recent call last): File "", line 1, in ? vms_sys.error: [Errno 10284] %SYSTEM-F-NODETACH, operation requires\ DETACH privilege >>> 01-JUL-2001 ZE. ------------------------------------------------------------------------ 2.6.53 PERSONA_DELETE - Create Persona Format: None = vms_sys.persona_delete (persona) Returns: None Arguments: persona The persona handle. Examples: See the 'examples' section of the vms_sys.persona_create() routine. 01-JUL-2001 ZE. ------------------------------------------------------------------------ 2.6.54 PROCESS_SCAN - Process Scan Creates and initializes a process context that is used by vms_sys.getjpi() or vms_sys.getjpiw() to scan for processes on the local system or across the nodes in a VMScluster system. Format: Python for OpenVMS -Reference Manual PAGE 2-429 vms_sys.process_scan() routine pidctx = vms_lib.process_scan (pidctx [,itmlst]) Returns: pidctx Context value supplied by PROCESS_SCAN to be used as the pidadr argument of vms_lib.getjpi() or vms_sys.getjpiw(). Arguments: pidctx Context value supplied by PROCESS_SCAN to be used as the pidadr argument of vms_lib.getjpi() or vms_sys.getjpiw(). itmlst Item list specifying selection criteria to be used by the scan or to control the scan. You must specify a tuple of tuples. Each item can be a 2- or 3-element tuple: item-code A string like 'PSCAN$_ACCOUNT'. item-value Depends on the data type of 'item-code' - it can be a Python string or a Python integer for byte, word or longword values and a Python long integer for quadword values. The interface takes care of passing the data 'by value' or 'by reference' while building the item-list. item-flags If omitted, then item-flags is set to 0. Data type is a Python integer. Symbolic names (like PSCAN_M_OR) are available in the 'vms_pscandef' module. Examples: $! want to see all processes $ set PROCESS /PRIVILEGE= (WORLD) >>> import vms_sys >>> import vms_pscandef >>> import vms_lib >>> # ---------- >>> # define useful procedures >>> # loop over all processes with PSCAN-context >>> # supplied in argument 1 (ctx) >>> def getjpi_loop (ctx): ... try: ... while(1): # let loop terminate by exception Python for OpenVMS -Reference Manual PAGE 2-430 vms_sys.process_scan() routine ... print vms_lib.getjpi ('JPI$_PRCNAM', ctx) [1] ... except: # any exception aborts the loop ... pass ... # -getjpi_loop() >>> >>> # list which processes exist >>> def show_processes(): ... ctx = -1 ... print ' ctx ap grp prcnam' ... try: ... while(1): # let loop terminate by exception ... ctx,pid = vms_lib.getjpi ('JPI$_PID',ctx) ... x,ap = vms_lib.getjpi ('JPI$_AUTHPRI',pid) ... x,gr = vms_lib.getjpi ('JPI$_GRP',pid) ... x,pn = vms_lib.getjpi ('JPI$_PRCNAM',pid) ... print '%6d %2d %6o %s' % (ctx,ap,gr,pn) ... # -while ... except: # any exception aborts the loop ... pass ... # -show_processes() >>> # ---------- >>> show_processes() ctx ap grp prcnam -65535 16 1 SWAPPER -65533 4 10040 ZESSIN_MBA41 -65531 8 1 IPCACP -65530 7 1 ERRFMT -65529 6 1 OPCOM -65528 8 1 AUDIT_SERVER -65527 8 1 JOB_CONTROL -65526 8 1 QUEUE_MANAGER -65525 8 1 SECURITY_SERVER -65523 4 10040 ZESSIN_MBA45 -65522 4 10040 ZESSIN_MBA47 -65521 4 37770 CRON-HERE -65520 6 10040 DECW$SERVER_0 -65519 4 10040 DECW$SESSION -65518 4 10040 DECW$TE_0092 -65516 4 10040 CLASS_SCHEDULER -65515 4 10040 ZESSIN_FTA13 -65514 4 10040 ZESSIN_FTA14 -65513 4 10040 ZESSIN_FTA15 -65494 4 10040 DECW$MWM >>> >>> # even a single item must be a tuple -------+ >>> # | >>> # all processes with UIC group > 1 | Python for OpenVMS -Reference Manual PAGE 2-431 vms_sys.process_scan() routine >>> ctx = vms_sys.process_scan (0, # v ... (('PSCAN$_GRP', 1,vms_pscandef.PSCAN_M_GTR), ) ... ) >>> getjpi_loop (ctx) ZESSIN_MBA41 ZESSIN_MBA45 ZESSIN_MBA47 CRON-HERE DECW$SERVER_0 DECW$SESSION DECW$TE_0092 CLASS_SCHEDULER ZESSIN_FTA13 ZESSIN_FTA14 ZESSIN_FTA15 DECW$MWM >>> >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$_GRP', 1, vms_pscandef.PSCAN_M_GTR), ... ('PSCAN$_PRCNAM', '*_*', vms_pscandef.PSCAN_M_NEQ+ ... vms_pscandef.PSCAN_M_WILDCARD) ... ) ... ) >>> getjpi_loop (ctx) CRON-HERE DECW$SESSION DECW$MWM >>> >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$_GRP', 3, vms_pscandef.PSCAN_M_LSS), ... ('PSCAN$_PRCNAM', '*_*', vms_pscandef.PSCAN_M_WILDCARD) ... ) ... ) >>> getjpi_loop (ctx) AUDIT_SERVER JOB_CONTROL QUEUE_MANAGER SECURITY_SERVER >>> >>> # list all processes that have BYPASS privilege enabled >>> # see GENMAN 'programming', 'privileges' for details >>> import vms_prvdef >>> q_prvmsk = vms_prvdef.PRV_M_BYPASS >>> print q_prvmsk 536870912L >>> >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$_CURPRIV', q_prvmsk, vms_pscandef.PSCAN_M_BIT_ANY), Python for OpenVMS -Reference Manual PAGE 2-432 vms_sys.process_scan() routine ... ) ... ) >>> getjpi_loop (ctx) SWAPPER ERRFMT JOB_CONTROL QUEUE_MANAGER DECW$SESSION CLASS_SCHEDULER ZESSIN_FTA13 >>> --------------------------------- >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$_PRCNAM', 'ZESSIN_*' ,vms_pscandef.PSCAN_M_NEQ+ ... vms_pscandef.PSCAN_M_WILDCARD), ... ('PSCAN$_PRCNAM', 'DECW$*' ,vms_pscandef.PSCAN_M_NEQ+ ... vms_pscandef.PSCAN_M_WILDCARD) ... ) ... ) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (372, '%SYSTEM-F-IVSSRQ, invalid system service request') >>> >>> ctx = vms_sys.process_scan (0, ... ((0, 1,vms_pscandef.PSCAN_M_NEQ), ) ... ) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: itmlst - item:0 item-code must be string >>> >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$_GRP', 'ZESSIN_*' ,vms_pscandef.PSCAN_M_NEQ), ) ... ) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: itmlst - item:0 data must be integer >>> >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$_PRCNAM', 1,vms_pscandef.PSCAN_M_NEQ), ) ... ) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: itmlst - item:0 data must be string >>> Python for OpenVMS -Reference Manual PAGE 2-433 vms_sys.process_scan() routine >>> ctx = vms_sys.process_scan (0, ... (('PSCAN$__BAD', 1,vms_pscandef.PSCAN_M_NEQ), ) ... ) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: itmlst - unknown item code: PSCAN$__BAD >>> 12-JUN-1999 ZE. ------------------------------------------------------------------------ 2.6.55 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 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) Python for OpenVMS -Reference Manual PAGE 2-434 vms_sys.purgws() routine 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 >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.56 READEF - Read Event Flags Returns the current status of all 32 event flags in a local or common event flag cluster and indicates whether the specified event flag is set or clear. Format: setflg, state = vms_sys.readef (efn) Returns: setflg The system service returns SS$_WASSET or SS$_WASCLR to indicate if the specified event flag was previously set (1) or cleared (0). Any other code returned from the system service results in a Python exception. state State of all event flags in the specified cluster. Arguments: efn Number of any event flag in the cluster whose status is to be returned. Number of the event flag to be set. SYS$READEF uses only the low-order byte. Specifying an event flag within a cluster requests that READEF return the status of all event flags in that cluster. Examples: >>> import vms_sys >>> setflg, state = vms_sys.readef (17) >>> setflg, state (0, -536870909) >>> print state & (2**17) 0 >>> # EFN 17 is clear Python for OpenVMS -Reference Manual PAGE 2-435 vms_sys.readef() routine >>> setflg, state = vms_sys.readef (1) >>> setflg, state (1, -536870909) >>> print state & (2**1) 2 >>> # EFN 1 is set (first EFN is EFN 0!) >>> vms_sys.clref (1) 1 >>> # EFN was set >>> vms_sys.clref (1) 0 >>> # EFN was clear >>> vms_sys.setef (17) 0 >>> # EFN was clear >>> vms_sys.setef (17) 1 >>> # EFN was set >>> setflg, state = vms_sys.readef (1) >>> setflg, state (0, -536739839) >>> print state & (2**1) 0 >>> # EFN 1 is now clear (first EFN is EFN 0!) >>> print state & (2**17) 131072 >>> # EFN 17 is now set >>> setflg = vms_sys.clref (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> setflg, state = vms_sys.readef (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> setflg = vms_sys.setef (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> >>> setflg = vms_sys.clref ('X') Python for OpenVMS -Reference Manual PAGE 2-436 vms_sys.readef() routine Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> >>> # 72 is in a common EFC that is not associated >>> setflg = vms_sys.clref (72) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (564, '%SYSTEM-F-UNASEFC, unassociated event flag cluster') >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.57 REM_HOLDER - Remove Holder Record from Rights Database Deletes the specified holder record from the target identifier's list of holders. Format: vms_sys.rem_holder (id, holder) Returns: None Arguments: id Binary value of target identifier to be removed. holder Identifier of holder to be removed. The Python function only accepts a tuple of 2 integers - not a quadword represented by a Python long integer. For OpenVMS V6.1 the first element is the holder's UIC identifier, the second element must be 0. Check the system services reference manual for your version of OpenVMS. Examples: UAF> add /identifier ID_1 /attributes=resource %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=(dynamic,resource) %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database UAF> grant /identifier ID_1 SYSTEM /attributes=resource UAF> grant /identifier ID_1 ZESSIN /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to SYSTEM UAF> grant /identifier ID_2 SYSTEM /attributes=(dynamic) Python for OpenVMS -Reference Manual PAGE 2-437 vms_sys.rem_holder() routine UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE ZESSIN RESOURCE UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 RESOURCE DYNAMIC Holder Attributes SYSTEM DYNAMIC UAF> >>> import vms_sys >>> id_1 = 0x80010011 # identifier ID_1 >>> id_2 = 0x80010012 # identifier ID_1 >>> uic = 0x10004 # UIC [1,4] (user SYSTEM) >>> vms_sys.rem_holder (id_1, (uic,0)) UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes ZESSIN RESOURCE UAF> >>> id_x = 0x80012345 # ungranted identifier >>> vms_sys.rem_holder (id_x, (uic,0)) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> uic_x = 0x30003 # UIC without name >>> vms_sys.rem_holder (id_1, (uic_x,0)) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> vms_sys.rem_holder (id_1, 'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - must be a tuple of 2 integers >>> >>> vms_sys.rem_holder (id_1, (0,'X')) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - tuple-element:1 is not an integer >>> >>> vms_sys.rem_holder (id_1, ('X',0)) Python for OpenVMS -Reference Manual PAGE 2-438 vms_sys.rem_holder() routine Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: holder - tuple-element:0 is not an integer >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.58 REM_IDENT - Remove Identifier from Rights Database Removes the specified identifier record and all its holder records (if any) from the rights database. Format: vms_sys.rem_ident (id) Returns: None Arguments: id Binary value of identifier to be removed. Examples: UAF> add /identifier ID_1 /attributes=resource %UAF-I-RDBADDMSG, identifier ID_1 value %X80010011 added to rights \ database UAF> add /identifier ID_2 /attributes=(dynamic,resource) %UAF-I-RDBADDMSG, identifier ID_2 value %X80010012 added to rights \ database UAF> grant /identifier ID_1 SYSTEM /attributes=resource UAF> grant /identifier ID_1 ZESSIN /attributes=resource %UAF-I-GRANTMSG, identifier ID_1 granted to SYSTEM UAF> grant /identifier ID_2 SYSTEM /attributes=(dynamic) UAF> show /identifier /full ID_1 Name Value Attributes ID_1 %X80010011 RESOURCE Holder Attributes SYSTEM RESOURCE ZESSIN RESOURCE UAF> show /identifier /full ID_2 Name Value Attributes ID_2 %X80010012 RESOURCE DYNAMIC Holder Attributes SYSTEM DYNAMIC UAF> show SYSTEM Username: SYSTEM Owner: SYSTEM MANAGER Account: SYSTEM UIC: [1,4] ([G1,SYSTEM]) Python for OpenVMS -Reference Manual PAGE 2-439 vms_sys.rem_ident() routine [...] SYSLCK SYSNAM SYSPRV TMPMBX UPGRADE VOLPRO WORLD Identifier Value Attributes ID_2 %X80010016 DYNAMIC ID_1 %X80010011 RESOURCE UAF> >>> import vms_sys >>> id_1 = 0x80010011 # identifier ID_1 >>> id_2 = 0x80010012 # identifier ID_2 >>> vms_sys.rem_ident (id_1) UAF> show /identifier /full ID_1 %UAF-E-SHOWERR, unable to complete SHOW command -SYSTEM-F-NOSUCHID, unknown rights identifier UAF> show SYSTEM Username: SYSTEM Owner: SYSTEM MANAGER Account: SYSTEM UIC: [1,4] ([G1,SYSTEM]) [...] SYSLCK SYSNAM SYSPRV TMPMBX UPGRADE VOLPRO WORLD Identifier Value Attributes ID_2 %X80010016 DYNAMIC UAF> >>> # try to remove identifier %X80010011 (named ID_1) which >>> # has already been removed >>> vms_sys.rem_ident (id_1) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier') >>> >>> uic = 0x10004 # user SYSTEM has UIC [1,4] >>> vms_sys.rem_ident (uic) UAF> show SYSTEM Username: SYSTEM Owner: SYSTEM MANAGER Account: SYSTEM UIC: [1,4] ([1,4]) [...] UIC-based identifier name deleted ----!!!!! UAF> ! re-insert the name UAF> add /identifier /value=uic=[1,4] SYSTEM %UAF-I-RDBADDMSGU, identifier SYSTEM value [000001,000004] added \ to rights database UAF> 28-SEP-1998 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-440 vms_sys.resume() routine 2.6.59 RESUME - Resume Process Causes a process previously suspended by the Suspend Process (SYS$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. 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 read-only buffer, 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 () Python for OpenVMS -Reference Manual PAGE 2-441 vms_sys.resume() routine 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 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.60 REVOKID - Revoke Identifier from Process Removes the specified identifier from the rights list of the process or the system. If the identifier is listed as a holder of any other identifier, the appropriate holder records are also deleted. Format: setflg, targpid, id, prvatr = vms_sys.revokid \ ([pidadr] [,prcnam] [,id] [,name]) Returns: setflg The system service returns SS$_WASSET or SS$_WASCLR to indicate if the rightslist did or did not contain the identifier before. The Python function does not return the status code - it returns 0 if the identifier did not exist in the rightslist before and returns 1 if it did. Any other code returned from the system service results in a Python exception. targpid Process identification of process to be affected. A value of -1 indicates the system rights list. 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.revokid() raises a Python exception. id Identifier and attributes to be removed. These are even returned when the programmer specifies 'None' as argument 3. The Python function returns a tuple of 2 integers - not a quadword represented by a Python long integer. The first element contains the binary identifier code. The second element contains the attributes. Bitmask values for these attributes are defined in module 'vms_kgbdef'. prvatr Previous attributes of the identifier if it was previously present in the rights list. Arguments: Python for OpenVMS -Reference Manual PAGE 2-442 vms_sys.revokid() routine pidadr Process identification of process to be affected. prcnam Process name of process to be affected. id Identifier and attributes to be removed. The Python function only accepts a tuple of 2 integers - not a quadword represented by a Python long integer. The first element contains the binary identifier code. The second element contains the attributes. Bitmask values for these attributes are defined in module 'vms_kgbdef'. name Name of the identifier to be removed - this is a string. Examples: $ show process /rights 3-SEP-1998 21:36:41.07 User: ZESSIN Process ID: 00000097 Node: HERE Process name: "ZESSIN_FTA10" Process rights: INTERACTIVE LOCAL System rights: SYS$NODE_HERE $ >>> import vms_sys >>> import vms_kgbdef >>> pid = 151 >>> id_1 = 0x80010011 # ID_1 >>> id_2 = 0x80010012 # ID_2 >>> attr = vms_kgbdef.KGB_M_DYNAMIC + vms_kgbdef.KGB_M_RESOURCE >>> # grant the process an identifier >>> vms_sys.grantid (pid, None, (id_1,attr), None) (0, 151, (-2147418095, 3), 0) | | | | |-- previous identifier attributes | | | |------ attributes mask (DYNAMIC + RESOURCE) | | |------------------- identifier ID_1 | |------------------------- PID |---------------------------- 0= identifier not previously granted >>> $ show process /rights 3-SEP-1998 21:43:49.95 User: ZESSIN Process ID: 00000097 Node: HERE Process name: "ZESSIN_FTA10" Process rights: INTERACTIVE Python for OpenVMS -Reference Manual PAGE 2-443 vms_sys.revokid() routine LOCAL ID_1 resource, dynamic System rights: SYS$NODE_HERE >>> attr = vms_kgbdef.KGB_M_RESOURCE >>> # revoke the identifier from the process >>> vms_sys.revokid (pid, None, (id_1,attr), None) (1, 151, (-2147418095, 1), 3) | | | | |-- previous identifier attributes | | | |------ attributes mask | | |------------------- identifier ID_1 | |------------------------- PID |---------------------------- 1= identifier was previously granted >>> # removing an identifier that is not granted is not an error! >>> vms_sys.revokid (pid, None, (id_1,attr)) (0, 151, (-2147418095, 1), 0) |---------------------------- 0= identifier not previously granted >>> $ show process /rights 3-SEP-1998 21:47:07.39 User: ZESSIN Process ID: 00000097 Node: HERE Process name: "ZESSIN_FTA10" Process rights: INTERACTIVE LOCAL System rights: SYS$NODE_HERE >>> # CMKRNL privilege is missing >>> vms_sys.revokid (pid, None, (id_1,attr), None) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (36, '%SYSTEM-F-NOPRIV, insufficient privilege or \ object protection violation') >>> $ set process/privilege=(CMKRNL,SYSNAM) $ set rights_list /enable /system id_2 $ show process /rights 3-SEP-1998 21:49:19.02 User: ZESSIN Process ID: 00000097 Node: HERE Process name: "ZESSIN_FTA10" Process rights: INTERACTIVE Python for OpenVMS -Reference Manual PAGE 2-444 vms_sys.revokid() routine LOCAL System rights: SYS$NODE_HERE ID_2 resource, dynamic >>> # remove an identifier from the system rights list >>> # -- requires CMKRNL+SYSNAM privilege >>> id_2 = 0x80010012 # ID_2 >>> attr = vms_kgbdef.KGB_M_DYNAMIC + vms_kgbdef.KGB_M_RESOURCE >>> vms_sys.revokid (-1, None, (id_2,attr), None) (1, -1, (-2147418094, 3), 0) | | | | |- old attributes | | | |----- current attributes | | |------------------ identifier value | |----------------------- PID, -1 = system rights list |-------------------------- setflg = 1 -- identifier was already in the system rights list >>> $ show process /rights $HERE> show process /rights 3-SEP-1998 21:54:09.18 User: ZESSIN Process ID: 00000097 Node: HERE Process name: "ZESSIN_FTA10" Process rights: INTERACTIVE LOCAL System rights: SYS$NODE_HERE $ @@ REVOKID - more examples >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.61 SCAN_INTRUSION - Scan Intrusion Database Format: status = vms_sys.scan_intrusion (logfail_status, failed_user, job_type, [source_terminal], [source_node], [source_user], [source_addr], [failed_password], [parent_user], [parent_id], [flags]) Returns: status Python for OpenVMS -Reference Manual PAGE 2-445 vms_sys.scan_intrusion() routine Condition value after return of SYS$SCAN_INTRUSION(). Arguments: logfail_status Reason why the user's login attempt failed - an OpenVMS condition value like SS$_NOSUCHUSER. Note that no module named 'vms_ssdef' exists. failed_user User name associated with the unsuccessful login attempt. 1 - 32 alphanumeric character string. job_type Python integer. Job types like JPI_K_BATCH are available in module 'vms_jpidef'. source_terminal Source terminal where the login attempt is occurring. 1 - 64 alphanumeric character string including '_' and ':'. source_node Name of the node from which the user's login attempt originates. 1 - 1024 characters (can be OSI full names). source_user User name associated with the login attempt. 1 - 32 alphanumeric character string including '$' and '_'. source_addr Source DECnet for OpenVMS address from which the login attempt originates. Character string - no length defined in OpenVMS VAX V6.1 system reference manual. failed_password Password the user entered for the login attempt. 0 - 32 characters. parent_user Parent process(!, not user) name of the failed login - only for failed spawn commands. 1 - 15 character string. parent_id Process identification of the parent process from which the login was attempted. On OpenVMS PID is represented as a Python integer. flags Operational instructions for the service. Bitmasks like CIA_M_NOAUDIT are available in module 'vms_ciadef. Examples: >>> import vms_ciadef >>> import vms_sys >>> >>> logfail_status = 0x2c # SS$_ABORT >>> failed_user = 'PY_BREAKIN' >>> job_type = vms_jpidef.JPI_K_NETWORK >>> source_terminal = 'PYB0:' >>> source_node = 'PYBRK' # leave off '::' >>> source_user = 'PY_INTRUDER' >>> source_addr = 'PY.BREAK.IN' >>> failed_password = 'PY_PWD' Python for OpenVMS -Reference Manual PAGE 2-446 vms_sys.scan_intrusion() routine >>> parent_user = None # this is not a subprocess breakin >>> parent_id = None >>> flags = None >>> >>> status = vms_sys.scan_intrusion \ ... (logfail_status, failed_user, job_type, \ ... source_terminal, source_node, source_user, \ ... source_addr, failed_password, parent_user, \ ... parent_id, flags) >>> >>> print vms_sys.getmsg (status) [0] '%SECSRV-I-SUSPECT, matching Suspect found' >>> $ %%%%%%%%%%% OPCOM 1-JUN-1999 19:04:21.03 %%%%%%%%%%% Message from user AUDIT$SERVER on HERE Security alarm (SECURITY) and security audit (SECURITY) on HERE, system id: 52199 Auditable event: Network login failure Event time: 1-JUN-1999 19:04:20.95 PID: 000000D7 Process name: ZESSIN_FTA11 Username: ZESSIN Terminal name: FTA11:, PYB0: Remote nodename: PYBRK Remote node id: 50592E425245414B2E494E Remote username: PY_INTRUDER Status: %SYSTEM-F-ABORT, abort $ show intrusion Intrusion Type Count Expiration Source NETWORK SUSPECT 1 19:09:20.95 PYBRK::PY_INTRUDER $ @@ more SYS$SCAN_INTRUSION examples 01-JUN-1999 ZE. ------------------------------------------------------------------------ 2.6.62 SCHDWK - Schedule Wakeup Schedules the awakening (restarting) of a process that has placed itself in a state of hibernation with the Hibernate (SYS$HIBER) service. Format: targpid = vms_sys.schdwk ([pidadr], [prcnam], daytim [,reptim]) Returns: Python for OpenVMS -Reference Manual PAGE 2-447 vms_sys.schdwk() routine 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 GENMAN '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 GENMAN 'Programming', 'special OpenVMS datatypes' for details. Examples: >>> import vms_sys >>> # translate ASCII delta time to 'binary quadword' equivalent. >>> q_10secs = vms_sys.bintim ('0 00:00:10.00') >>> q_10secs -100000000L >>> # wait a single 10 second shot >>> vms_sys.asctim () '12-AUG-1998 11:29:38.73' >>> vms_sys.schdwk (0, None, q_10secs) 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, q_10secs, \ ... 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' >>> vms_sys.hiber () Python for OpenVMS -Reference Manual PAGE 2-448 vms_sys.schdwk() routine >>> 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 ? TypeError: argument 3: daytim - must be long integer >>> vms_sys.schdwk (None, None, 0xFFFFFFFFFA0A1F00L, 1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 4: reptim - must be long integer >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.63 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. Python for OpenVMS -Reference Manual PAGE 2-449 vms_sys.setddir() routine 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.4.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 read-only buffer, 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') >>> Python for OpenVMS -Reference Manual PAGE 2-450 vms_sys.setddir() routine 12-JUN-1999 ZE. ------------------------------------------------------------------------ 2.6.64 SETDFPROT - Set Default File Protection Allows you to read and write the default file protection for the process. Please note that Python uses the C RTL for file I/O. Usage of the umask() function can render this setup useless. Format: cur-def-prot = vms_sys.setdfprot ([new-def-prot]) Returns: cur-def-prot Current /old default protection value. This is an unsigned 16-bit integer. Read the system documentation about how the protection bits are encoded. Arguments: new-def-prot New protection value. This must be an unsigned 16-bit integer. Read the system documentation about how the protection bits are encoded. Examples: $ SHOW PROTECTION SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD=NO ACCESS $ $ PYTHON [ banner omitted ] >>> import vms_sys >>> old_prot = vms_sys.setdfprot () >>> print old_prot 64000 >>> >>> old_prot = vms_sys.setdfprot (None) >>> print old_prot 64000 >>> hex (old_prot) '0xfa00' >>> Python for OpenVMS -Reference Manual PAGE 2-451 vms_sys.setdfprot() routine >>> old_prot = vms_sys.setdfprot (0x1234) >>> hex (old_prot) '0xfa00' >>> new_prot = vms_sys.setdfprot (None) >>> hex (new_prot) '0x1234' >>> >>> import vms_lib >>> vms_lib.do_command ('SHOW PROTECTION') SYSTEM=RWD, OWNER=ED, GROUP=RED, WORLD=WED $ >>> vms_sys.setdfprot ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: new-def-prot - must be positive\ 16-bit integer or None >>> 01-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.65 SETEF - Set Event Flag The Set Event Flag service sets an event flag in a local or common event flag cluster. Format: setflg = vms_sys.setef (efn) Returns: setflg The system service returns SS$_WASSET or SS$_WASCLR to indicate if the specified event flag was previously set (1) or cleared (0). Any other code returned from the system service results in a Python exception. Arguments: efn Number of the event flag to be set. SYS$SETEF uses only the low-order byte. Examples: >>> import vms_sys >>> setflg, state = vms_sys.readef (17) >>> setflg, state Python for OpenVMS -Reference Manual PAGE 2-452 vms_sys.setef() routine (0, -536870909) >>> print state & (2**17) 0 >>> # EFN 17 is clear >>> setflg, state = vms_sys.readef (1) >>> setflg, state (1, -536870909) >>> print state & (2**1) 2 >>> # EFN 1 is set (first EFN is EFN 0!) >>> vms_sys.clref (1) 1 >>> # EFN was set >>> vms_sys.clref (1) 0 >>> # EFN was clear >>> vms_sys.setef (17) 0 >>> # EFN was clear >>> vms_sys.setef (17) 1 >>> # EFN was set >>> setflg, state = vms_sys.readef (1) >>> setflg, state (0, -536739839) >>> print state & (2**1) 0 >>> # EFN 1 is now clear (first EFN is EFN 0!) >>> print state & (2**17) 131072 >>> # EFN 17 is now set >>> setflg = vms_sys.clref (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> setflg, state = vms_sys.readef (255) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> setflg = vms_sys.setef (255) Traceback (innermost last): File "", line 1, in ? Python for OpenVMS -Reference Manual PAGE 2-453 vms_sys.setef() routine vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster') >>> >>> setflg = vms_sys.clref ('X') Traceback (innermost last): File "", line 1, in ? TypeError: illegal argument type for built-in operation >>> >>> # 72 is in a common EFC that was not associated >>> setflg = vms_sys.clref (72) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (564, '%SYSTEM-F-UNASEFC, unassociated event flag \ cluster') >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.66 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. @@ SETPRI - 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. Python for OpenVMS -Reference Manual PAGE 2-454 vms_sys.setpri() routine 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) >>> # set back old priority using 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 3 arguments; 2 given >>> vms_sys.setpri (1,2,3) Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: expected read-only buffer, 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') Python for OpenVMS -Reference Manual PAGE 2-455 vms_sys.setpri() routine >>> vms_sys.setpri (__name__,'X',4) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: pidadr - must be integer or None >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.67 SETPRN - Set Process Name Format: vms_sys.setprn ([prcnam]) Returns: 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') >>> # an empty argument results in a process with no name. >>> vms_sys.setprn () >>> vms_lib.getjpi ('JPI$_PRCNAM',0) (160, '') >>> 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) Python for OpenVMS -Reference Manual PAGE 2-456 vms_sys.setprn() routine Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: expected read-only buffer, 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 ? vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name') >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.68 SETPRV - Set Privilege Enables or disables specified privileges for the calling process. Format: prvprv = vms_sys.setprv ([enbflg] [,prvadr] [,prmflg]) Returns: prvprv Previous privilege mask - 64-bit bitmask - a Python long integer. Privilege bitmask values are stored in module vms_prvdef. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. Arguments: enbflg Enable (1) oder disable (0) privileges specified in the mask of the 'prvadr' argument. Default (if None specified) is disable. prvadr Privileges to be enabled or disabled - 64-bit bitmask - a Python long integer. Privilege bitmask values are stored in module vms_prvdef. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. Python for OpenVMS -Reference Manual PAGE 2-457 vms_sys.setprv() routine prmflg Indicator specifying whether the privileges are to be affected permanently (1) or temporarily (0). Temporarily means that the setting stays until the next image rundown. Default (if None specified) is temporarily. Examples: $ SHOW PROCESS /PRIVILEGES 27-NOV-1998 20:48:21.80 User: ZESSIN Process ID: 00000156 Node: HERE Process name: "ZESSIN_FTA14" Authorized privileges: NETMBX OPER SETPRV SYSPRV TMPMBX Process privileges: NETMBX may create network device OPER may perform operator functions SETPRV may set any privilege bit SYSPRV may access objects via system protection TMPMBX may create temporary mailbox Process rights: INTERACTIVE LOCAL NEWS_MANAGER System rights: SYS$NODE_HERE $ $ python >>> import vms_lib >>> import vms_prvdef >>> import vms_sys >>> vms_lib.getjpi ('JPI$_CURPRIV', 0) (342, 269795328L) >>> q_newprv = vms_prvdef.PRV_M_BYPASS >>> q_oldprv = vms_sys.setprv (1,q_newprv) >>> q_oldprv (1, 269795328L) >>> hex (q_oldprv[1]) '0x1014C000L' >>> >>> vms_lib.getjpi ('JPI$_CURPRIV', 0) (342, 806666240L) >>> >>> # the READALL privilege bit is in the second longword >>> q_newprv = vms_prvdef.PRV_M_READALL >>> print hex (q_newprv) Python for OpenVMS -Reference Manual PAGE 2-458 vms_sys.setprv() routine 0x800000000L >>> q_oldprv = vms_sys.setprv (1,q_newprv,1) >>> q_oldprv , hex (q_oldprv[1]) # prmflg ^ specified ((1, 269795328L), '0x1014C000L') >>> $! from another process $ SHOW PROCESS /PRIVILEGES /IDENTIFICATION=00000156 27-NOV-1998 20:53:13.99 User: ZESSIN Process ID: 00000156 Node: HERE Process name: "ZESSIN_FTA14" Authorized privileges: NETMBX OPER SETPRV SYSPRV TMPMBX Process privileges: NETMBX may create network device OPER may perform operator functions READALL may read anything as the owner SETPRV may set any privilege bit SYSPRV may access objects via system protection TMPMBX may create temporary mailbox [...] $ >>> q_newprv = vms_prvdef.PRV_M_SYSLCK >>> q_oldprv = vms_sys.setprv (0,q_newprv,1) >>> q_oldprv , hex (q_oldprv[1]) ((1, 34629533696L), '0x81014C000L') >>> >>> vms_lib.do_command ('show process/privileges') 27-NOV-1998 20:55:27.46 User: ZESSIN Process ID: 00000156 Node: HERE Process name: "ZESSIN_FTA14" Authorized privileges: NETMBX OPER SETPRV SYSPRV TMPMBX Process privileges: NETMBX may create network device OPER may perform operator functions READALL may read anything as the owner SETPRV may set any privilege bit SYSPRV may access objects via system protection TMPMBX may create temporary mailbox [...] $ - READALL privilege is still enabled after Python has ended -------------------- Python for OpenVMS -Reference Manual PAGE 2-459 vms_sys.setprv() routine $ SHOW PROCESS /PRIVILEGES 28-NOV-1998 19:07:59.78 User: NOPRIV Process ID: 0000015B Node: HERE Process name: "NOPRIV" Authorized privileges: NETMBX READALL TMPMBX Process privileges: READALL may read anything as the owner TMPMBX may create temporary mailbox [...] $ $ python >>> import vms_lib >>> import vms_prvdef >>> import vms_sys >>> pid, q_priv = vms_lib.getjpi ('JPI$_CURPRIV', 0) >>> q_priv, hex(q_priv) (34359771136L, '0x800008000L') >>> >>> q_newprv = vms_prvdef.PRV_M_NETMBX >>> status, q_oldprv = vms_sys.setprv (1,q_newprv) >>> status, q_oldprv (1, 34359771136L) >>> >>> pid, q_priv = vms_lib.getjpi ('JPI$_CURPRIV', 0) >>> q_priv, hex(q_priv) (34360819712L, '0x800108000L') >>> >>> # BYPASS is not an authorized privilege >>> q_newprv = vms_prvdef.PRV_M_BYPASS >>> status, q_oldprv = vms_sys.setprv (1,q_newprv) >>> status, q_oldprv >>> vms_sys.getmsg (status) ('%SYSTEM-S-NOTALLPRIV, not all requested privileges authorized',\ (0, 0, 0, 0)) >>> -------------------- >>> vms_sys.setprv ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: enbflg - must be integer or None >>> >>> vms_sys.setprv (1,'X') Python for OpenVMS -Reference Manual PAGE 2-460 vms_sys.setprv() routine Traceback (innermost last): File "", line 1, in ? TypeError: argument 2: prvadr - must be long integer or None >>> >>> vms_sys.setprv (1,0L,'X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 3: prmflg - must be integer or None >>> 14-FEB-1999 ZE. ------------------------------------------------------------------------ 2.6.69 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 Python for OpenVMS -Reference Manual PAGE 2-461 vms_sys.setswm() routine >>> # 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 >>> 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') >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.70 SETUAI - Set User Authorization Information Modifies the user authorization file (UAF) record for a specified user. vms_sys.setuai() does _not_ raise an exception when the SYS$SETUAI routine returns an error. You must check 'status' in the dictionary that is returned. Format: dict = vms_lib.setuai (None, [contxt], usrnam, itmlst \ [,None] [,None] [,None]) Returns: dict A dictionary that has the following keys: 'status' the condition value returned from SYS$SETUAI. 'contxt' the context value if and only if the 'contxt' argument was specified. Python for OpenVMS -Reference Manual PAGE 2-462 vms_sys.setuai() routine Arguments: 'None' Placeholder arguments, that are currently ignored. You MUST specify the first argument, you can leave off the last 3 arguments. contxt Used to maintain authorization file context. On the initial call, it should contain the value -1. You must use 'None' - not 0 - to indicate omission of this argument. After the call to SYS$SETUAI the modified value is returned in the 'dict' object under the key 'contxt'. Feed this value into the 'contxt' argument for the next call to vms_sys.setuai(). Note: the contxt argument is only usefull for repeated access to _the same_ username! SYS$SETUAI and (SYS$GETUAI) do not provide any wildcard access over all usernames in the UAF. The pyvms.uaf_get_usernames() function can be used to get a list of all usernames that are stored in the UAF. usrnam Name of the user whose UAF record is modified. itmlst Item list specifying which information from the specified user's user authorization file (UAF) record is to be modified. You must specify a tuple of tuples. See the examples below. Format: (('UAI$_name', data), ('UAI$_name', data),...) Any input items that have been specified in the item-list and that are supported by SYS$SETUAI. Note that 'data' can itself be a tuple for some items - see below. A 'counted ASCII string' (ASCIC) - which means that the first byte contains the string length - is input as a normal string (one without the count byte at the beginning). The Python interface constructs the length byte from the string length automatically. special notes about some item codes: UAI$_ACCOUNT This must be a 32-character string. The account name can be a maximum of 8 characters in size. The remaining characters must be filled with spaces. UAI$_BATCH_ACCESS_P + UAI$_BATCH_ACCESS_S Input as a 3-integer tuple where each integer is limited to 0 - 255. UAI$_CLITABLES + UAI$_DEFCLI SYS$SETUAI needs an ASCIC string. The Python interface requires a simple string and constructs the ASCIC itself. UAI$_DEF_PRIV Python for OpenVMS -Reference Manual PAGE 2-463 vms_sys.setuai() routine Input as a Python long integer which emulates VMS quadwords. Privilege bitmask values are stored in module vms_prvdef. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. UAI$_DEFDEV, UAI$_DEFDIR SYS$SETUAI needs an ASCIC string. The Python interface requires a simple string and constructs the ASCIC itself. UAI$_DIALUP_ACCESS_P + UAI$_DIALUP_ACCESS_S Input as a 3-integer tuple where each integer is limited to 0 - 255. UAI$_EXPIRATION Input as a Python long integer which emulates VMS quadwords. vms_sys.bintim() can be used to translate an ASCII date and time representation to its binary equivalent. UAI$_ENCRYPT + UAI$_ENCRYPT2 Constants (UAI_C_name) for these (1-byte integer) fields are in module 'vms_uaidef'. UAI$_FLAGS Bitmask values for this (32-bit) field are in module 'vms_uaidef'. UAI$_LASTLOGIN_I + UAI$_LASTLOGIN_N Input as a Python long integer which emulates VMS quadwords. vms_sys.bintim() can be used to translate the ASCII date and time representations to their binary equivalents. UAI$_LGICMD SYS$SETUAI needs an ASCIC string. The Python interface requires a simple string and constructs the ASCIC itself. UAI$_LOCAL_ACCESS_P + UAI$_LOCAL_ACCESS_S Input as a 3-integer tuple where each integer is limited to 0 - 255. UAI$_NETWORK_ACCESS_P + UAI$_NETWORK_ACCESS_P Input as a 3-integer tuple where each integer is limited to 0 - 255. UAI$_OWNER SYS$SETUAI needs an ASCIC string. The Python interface requires a simple string and constructs the ASCIC itself. UAI$_PRCCNT The documentation of OpenVMS V6.1 describes the data type for SYS$GETUAI as a longword - this is wrong, a WORD is required. The description for SETUAI (a WORD is required) is correct). UAI$_PRIMEDAYS Bitmask values for this (8-bit) field (UAI_M_MONDAY through UAI_M_SUNDAY) are defined in module 'vms_uaidef'. The documentation of OpenVMS V6.1 describes the data type as a longword - this is wrong, a BYTE is required. (The requirement for SYS$GETUAI as a longword is wrong, too). UAI$_PRIV Input as a Python long integer which emulates VMS quadwords. Privilege bitmask values are stored in module vms_prvdef. Usage of the privilege bitmasks is explained in GENMAN 'programming, processes, privileges'. UAI$_PWD + UAI$_PWD2 Input as Python long integer which emulates VMS quadwords. UAI$_PWD_DATE + UAI$_PWD2_DATE Python for OpenVMS -Reference Manual PAGE 2-464 vms_sys.setuai() routine Input as a Python long integer which emulates VMS quadwords. vms_sys.bintim() can be used to translate the ASCII date and time representations to their binary equivalents. UAI$_PWD_LIFETIME + UAI$_PWD2_LIFETIME Input as a Python long integer which emulates VMS quadwords. vms_sys.bintim() can be used to translate the ASCII date and time representations to their binary equivalents. UAI$_REMOTE_ACCESS_P + UAI$_REMOTE_ACCESS_S Input as a 3-integer tuple where each integer is limited to 0 - 255. Examples: UAF> add SETUAI_TST /owner= "PYTHON-setuai-TEST" - /uic= [12345,13527] /account= "PYTHON_S" - /cli= "CLI_TEST" /clitables= "DCLTABLES_TEST" - /lgicmd= "LGICMD_TEST" - /flags= (dismail, disuser, restrict) - /privileges= (noALL, TMPMBX) /defprivileges= (noALL, TMPMBX) UAF> modify SETUAI_TST - /device= "DEFDEV_TEST" /directory= [DEFDIRTEST] UAF> modify SETUAI_TST - /interactive /batch /network UAF> modify SETUAI_TST /primedays= (noSATURDAY, noSUNDAY) - /expiration= "29-FEB-2000 12:34:56.78" /pwdminimum= 12 - /pwdlifetime= "12-21:43:56.87" UAF> modify SETUAI_TST /maxjobs= 11 /maxacctjobs= 12 /prclm= 13 - /priority= 14 /queprio= 15 /cputime= "11-22:33:44.55" - /fillm= 111 /shrfillm= 112 /biolm= 113 /diolm= 114 - /astlm= 115 /tqelm= 116 /enqlm= 117 UAF> modify SETUAI_TST /bytlm= 1111 /pbytlm= 1112 /jtquota= 1113 - /wsdefault= 1114 /wsquota= 1115 /wsextent= 1116 - /pgflquota= 1117 /password= XYZ UAF> modify SETUAI_TST /local= - (PRIMARY, 1-3,7,12-15, SECONDARY, 1-8,9,11,17-21,23) ------------------------------------------------------------ UAF> show SETUAI_TST Username: SETUAI_TST Owner: PYTHON-setuai-TEST Account: PYTHON_S UIC: [12345,13527] ([PYTHON_S,SETUAI_TST]) CLI: CLI_TEST Tables: DCLTABLES_TEST Default: DEFDEV_TEST:[DEFDIRTEST] LGICMD: LGICMD_TEST Flags: DefCLI Restricted DisUser DisMail Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun Python for OpenVMS -Reference Manual PAGE 2-465 vms_sys.setuai() routine Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: ##### Full access ###### ##### Full access ###### Batch: ##### Full access ###### ##### Full access ###### Local: -###---#----####-------- -#########-#-----#####-# Dialup: ##### Full access ###### ##### Full access ###### Remote: ##### Full access ###### ##### Full access ###### Expiration: 29-FEB-2000 12:34 Pwdminimum: 12 Login Fails: 0 Pwdlifetime: 12 21:43 Pwdchange: (pre-expired) Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 11 Fillm: 111 Bytlm: 1111 Maxacctjobs: 12 Shrfillm: 112 Pbytlm: 1112 Maxdetach: 0 BIOlm: 113 JTquota: 1113 Prclm: 13 DIOlm: 114 WSdef: 1114 Prio: 14 ASTlm: 115 WSquo: 1115 Queprio: 15 TQElm: 116 WSextent: 1116 CPU: 11 22:33:44 Enqlm: 117 Pgflquo: 1117 Authorized Privileges: TMPMBX Default Privileges: TMPMBX UAF> ------------------------------------------------------------ >>> import vms_sys >>> import vms_uaidef >>> # UAI$_ACCOUNT = 8 characters + 24 trailing ' ' >>> t_account = 'SU_NEW ' >>> # 12345678901234567890123456789012 >>> # UAI$_CPUTIM is expressed in 10ms steps >>> # SYS$BINTIM returns a granularity of 100ns steps >>> q_cputim = vms_sys.bintim ('33 11:44:22.55') >>> l_cputim = int(abs(q_cputim)/100000) >>> import vms_prvdef >>> q_def_priv = vms_prvdef.PRV_M_SYSNAM + \ ... vms_prvdef.PRV_M_ALLSPOOL + \ ... vms_prvdef.PRV_M_DETACH + \ ... vms_prvdef.PRV_M_DIAGNOSE + \ ... vms_prvdef.PRV_M_GROUP + \ ... vms_prvdef.PRV_M_NOACNT + \ ... vms_prvdef.PRV_M_PSWAPM # >>> >>> q_priv = vms_prvdef.PRV_M_CMEXEC + \ ... vms_prvdef.PRV_M_GRPNAM + \ ... vms_prvdef.PRV_M_ALLSPOOL + \ ... vms_prvdef.PRV_M_GROUP + \ ... vms_prvdef.PRV_M_PRMCEB + \ ... vms_prvdef.PRV_M_SETPRI + \ ... vms_prvdef.PRV_M_SETPRV + \ ... vms_prvdef.PRV_M_TMPMBX # Python for OpenVMS -Reference Manual PAGE 2-466 vms_sys.setuai() routine >>> >>> q_expdat = vms_sys.bintim ('28-FEB-1999 21:43:45.78') >>> l_flags = vms_uaidef.UAI_M_CAPTIVE + \ ... vms_uaidef.UAI_M_DISMAIL + \ ... vms_uaidef.UAI_M_RESTRICTED >>> # bits that are set indicate the secondary days! >>> b_primedays = vms_uaidef.UAI_M_MONDAY + \ ... vms_uaidef.UAI_M_TUESDAY + \ ... vms_uaidef.UAI_M_FRIDAY >>> q_pwd_date = vms_sys.bintim ('1-JAN-1998 01:01:01.01') >>> q_pwd2_date = vms_sys.bintim ('2-JAN-1998 02:02:02.02') >>> q_pwdlife = vms_sys.bintim ('9 19:29:39.49') >>> # build new UIC from group and member >>> w_grp = 015432 # 0nn is OCTAL notation >>> w_mem = 017253 >>> l_uic = (w_grp * 65536) + w_mem >>> dict = vms_sys.setuai (None,None,'SETUAI_TST', ... (('UAI$_ACCOUNT' ,t_account ) ... ,('UAI$_ASTLM' ,315 ) ... ,('UAI$_BIOLM' ,313 ) ... ,('UAI$_BYTLM' ,3111 ) ... ,('UAI$_CLITABLES' ,'SU_NEWCLITAB') ... ,('UAI$_CPUTIM' ,l_cputim ) ... ,('UAI$_DEFCLI' ,'SU_NEWCLI' ) ... ,('UAI$_DEFDEV' ,'SU_NEWDEV:' ) ... ,('UAI$_DEFDIR' ,'[SU_NEWDIR' ) ... ,('UAI$_DEF_PRIV' ,q_def_priv ) ... ,('UAI$_DFWSCNT' ,3114 ) ... ,('UAI$_DIOLM' ,314 ) ... ,('UAI$_ENQLM' ,317 ) ... ,('UAI$_EXPIRATION' ,q_expdat ) ... ,('UAI$_FILLM' ,311 ) ... ,('UAI$_FLAGS' ,l_flags ) ... ,('UAI$_JTQUOTA' ,3113 ) ... ,('UAI$_LGICMD' ,'SU_NEWLGICMD') ... ,('UAI$_LOGFAILS' ,77 ) ... ,('UAI$_MAXACCTJOBS' ,32 ) ... ,('UAI$_MAXDETACH' ,39 ) ... ,('UAI$_MAXJOBS' ,31 ) ... ,('UAI$_OWNER' ,'SU_NEW_OWNER') ... ,('UAI$_PBYTLM' ,3112 ) ... ,('UAI$_PGFLQUOTA' ,3117 ) ... ,('UAI$_PRCCNT' ,33 ) ... ,('UAI$_PRI' ,31 ) ... ,('UAI$_PRIMEDAYS' ,b_primedays ) ... ,('UAI$_PRIV' ,q_priv ) ... ,('UAI$_PWD_DATE' ,q_pwd_date ) ... ,('UAI$_PWD2_DATE' ,q_pwd2_date ) ... ,('UAI$_PWD_LENGTH' ,32 ) Python for OpenVMS -Reference Manual PAGE 2-467 vms_sys.setuai() routine ... ,('UAI$_PWD_LIFETIME' ,q_pwdlife ) ... ,('UAI$_QUEPRI' ,35 ) ... ,('UAI$_SALT' ,111 ) ... ,('UAI$_SHRFILLM' ,312 ) ... ,('UAI$_TQCNT' ,316 ) ... ,('UAI$_UIC' ,l_uic ) ... ,('UAI$_USER_DATA' ,'USER-DATA' ) ... ,('UAI$_WSEXTENT' ,3116 ) ... ,('UAI$_WSQUOTA' ,3115 ) ... )) >>> dict.get('status') 1 >>> UAF> SHOW SETUAI_TST Username: SETUAI_TST Owner: SU_NEW_OWNER Account: SU_NEW UIC: [15432,17253] ([15432,17253]) CLI: SU_NEWCLI Tables: SU_NEWCLITAB Default: SU_NEWDEV:[SU_NEWDIR LGICMD: SU_NEWLGICMD Flags: Restricted DisNewMail Captive Primary days: Wed Thu Sat Sun Secondary days: Mon Tue Fri Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: ##### Full access ###### ##### Full access ###### Batch: ##### Full access ###### ##### Full access ###### Local: -###---#----####-------- -#########-#-----#####-# Dialup: ##### Full access ###### ##### Full access ###### Remote: ##### Full access ###### ##### Full access ###### Expiration: 28-FEB-1999 21:43 Pwdminimum: 32 Login Fails: 77 Pwdlifetime: 9 19:29 Pwdchange: 1-JAN-1998 01:01 2-JAN-1998 02:02 Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 31 Fillm: 311 Bytlm: 3111 Maxacctjobs: 32 Shrfillm: 312 Pbytlm: 3112 Maxdetach: 39 BIOlm: 313 JTquota: 3113 Prclm: 33 DIOlm: 314 WSdef: 3114 Prio: 31 ASTlm: 315 WSquo: 3115 Queprio: 35 TQElm: 316 WSextent: 3116 CPU: 33 11:44:22 Enqlm: 317 Pgflquo: 3117 Authorized Privileges: ALLSPOOL ALTPRI CMEXEC GROUP GRPNAM PRMCEB SETPRV TMPMBX Default Privileges: ACNT ALLSPOOL DETACH DIAGNOSE GROUP PSWAPM SYSNAM ---------------------------------------- Warning! Identifiers have not been changed! UAF> SHOW/IDENTIFIER PYTHON_S Name Value Attributes PYTHON_S [012345,177777] UAF> SHOW/IDENTIFIER SETUAI_TST Name Value Attributes Python for OpenVMS -Reference Manual PAGE 2-468 vms_sys.setuai() routine SETUAI_TST [012345,013527] UAF> You need vms_sys.mod_ident() to change them. ---------------------------------------- The contents from UAI$_USER_DATA is not shown by AUTHORIZE: >>> dict = vms_sys.getuai (None,None,'SETUAI_TST', \ ... ('UAI$_USER_DATA',)) >>> # ^-- one-item tuple >>> dict.get ('status') 1 >>> dict.get ('UAI$_USER_DATA') 'USER-DATA' >>> ------------------------------------------------------------ >>> import vms_sys >>> q_li_i = vms_sys.bintim ('1-MAR-1996 01:02:03.45') >>> q_li_n = vms_sys.bintim ('2-APR-1997 10:20:30.54') >>> dict = vms_sys.setuai (None,None,'SETUAI_TST', ... (('UAI$_LASTLOGIN_I', q_li_i) ... ,('UAI$_LASTLOGIN_N', q_li_n) ... ,('UAI$_BATCH_ACCESS_P', (85, 85, 85)) ... ,('UAI$_BATCH_ACCESS_S', (170, 170, 170)) ... ,('UAI$_DIALUP_ACCESS_P', (68, 68, 68)) ... ,('UAI$_DIALUP_ACCESS_S', (136, 136, 136)) ... ,('UAI$_LOCAL_ACCESS_P', (34, 34, 34)) ... ,('UAI$_LOCAL_ACCESS_S', (153, 153, 153)) ... ,('UAI$_NETWORK_ACCESS_P', (1, 1, 1)) ... ,('UAI$_NETWORK_ACCESS_S', (8, 8, 8)) ... ,('UAI$_REMOTE_ACCESS_P', (254, 254, 254)) ... ,('UAI$_REMOTE_ACCESS_S', (128, 128, 128)) ... )) >>> dict.get('status') 1 >>> UAF> SHOW SETUAI_TST Username: SETUAI_TST Owner: SU_NEW_OWNER Account: SU_NEW UIC: [15432,17253] ([15432,17253]) CLI: SU_NEWCLI Tables: SU_NEWCLITAB Default: SU_NEWDEV:[SU_NEWDIR LGICMD: SU_NEWLGICMD Flags: Restricted DisNewMail Captive Primary days: Wed Thu Sat Sun Secondary days: Mon Tue Fri Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: -#######-#######-####### ###-#######-#######-#### Python for OpenVMS -Reference Manual PAGE 2-469 vms_sys.setuai() routine Batch: -#-#-#-#-#-#-#-#-#-#-#-# #-#-#-#-#-#-#-#-#-#-#-#- Local: #-###-###-###-###-###-## -##--##--##--##--##--##- Dialup: ##-###-###-###-###-###-# ###-###-###-###-###-###- Remote: #-------#-------#------- #######-#######-#######- Expiration: 28-FEB-1999 21:43 Pwdminimum: 32 Login Fails: 77 Pwdlifetime: 9 19:29 Pwdchange: \ 1-JAN-1998 01:01 2-JAN-1998 02:02 Last Login: 1-MAR-1996 01:02 (interactive), \ 2-APR-1997 10:20 (non-interactive) Maxjobs: 31 Fillm: 311 Bytlm: 3111 [...] >>> 10-NOV-1999 ZE. ------------------------------------------------------------------------ 2.6.71 SET_RESOUCE_DOMAIN - Set Resource Domain Controls the association between a calling process and resource domains. Format: status, rsdm_id = vms_sys.set_resource_domain (func, rsdm_id, domain_number, [nullarg], [access], [acmode]) Returns: status condition value that is returned by SYS$SET_RESOURCE_DOMAIN(). rsdm_id Resource domain identification. It is always returned, but valid only when using RSDM__JOIN_DOMAIN. Arguments: func Function code specifying which action SYS$SET_RESOURCE_DOMAIN should perform. Codes like RSDM__JOIN_DOMAIN are available in module 'vms_rsdmdef'. rsdm_id Resource domain identification. It must always be specified, but is only required when using RSDM__LEAVE. domain_number Domain number that identifies the resource domain - Python integer. nullarg Placeholder argument - specify None. access Access type - bitmasks like RSDM_M_READ are available in module 'vms_rsdmdef'. acmode Python for OpenVMS -Reference Manual PAGE 2-470 vms_sys.set_resouce_domain() routine Not usable - specify None. Examples: >>> import vms_sys >>> import vms_rsdmdef >>> status, rsdm_id = vms_sys.set_resource_domain ( \ ... vms_rsdmdef.RSDM__JOIN_DOMAIN, \ ... 0, 5, None, vms_rsdmdef.RSDM_M_LOCK) >>> print (status, rsdm_id) (1, 131074) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> import vms_lckdef >>> l_lkmode = vms_lckdef.LCK_K_NLMODE >>> # Note: LKSB will be created automatically -v >>> dict = vms_sys.enqw (None, l_lkmode, None, None, ... 'PY_RESNAM', None, None, ... None, None, None, rsdm_id) >>> for key in dict.keys(): ... print key, '=', dict.get(key) ... #-for ... lksb = status = 1 <-- from SYS$ENQW() >>> >>> # check status inside LKSB >>> r_lksb = dict.get ('lksb') >>> w_status = r_lksb.W_STATUS >>> print vms_sys.getmsg (w_status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> status, rsdm_xx = vms_sys.set_resource_domain ( \ ... vms_rsdmdef.RSDM__LEAVE, \ ... rsdm_id, 5, None, None) >>> print (status, rsdm_xx) (3834, 131074) >>> print vms_sys.getmsg (status) [0] %SYSTEM-E-RSDM_ACTIVE, resource domain active >>> 18-JUL-1999 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-471 vms_sys.set_security() routine 2.6.72 SET_SECURITY - Set Security Characteristics Sets the security characteristics of an object. vms_sys.set_security() does _not_ raise an exception when the SYS$SET_SECURITY routine returns an error. You must check 'status' in the dictionary that is returned. Format: dict = vms_sys.set_security \ ([clsnam], [objnam], [objhan], [flags], \ [itmlst], [contxt] ,[acmode]) Returns: dict A dictionary that has the following keys: 'status' the condition value returned from SYS$SET_SECURITY. 'contxt' the context value if and only if the 'contxt' argument was specified. It is only put into the dictionary, when SYS$SET_SECURITY returns a success status. Arguments: clsnam Name of the object class. E.g.: "FILE" or "QUEUE". Please see the system services reference manual for a complete list. objnam Name of the protected object whose associated security profile is going to be changed. See the system services reference manual for details. objhan "object handle" - this is a Python (32-bit) integer. Please see the system services reference manual for how this is passed. @@ Argument not tested. flags Mask specifying processing options. Symbolic names (OSS_M_name) are available in module 'vms_ossdef'. itmlst Item list specifying which information about the object(s) is to be modified. contxt Value used to maintain the processing context when dealing with a single protected object across multiple vms_sys.get_security() or vms_sys.set_security() calls. Python for OpenVMS -Reference Manual PAGE 2-472 vms_sys.set_security() routine Don't forget to release the context after use - see the examples section below. acmode According to the documentation, this argument should not be used. No tests have been done with profile related item codes. Be aware that this system service is not very good documented (I have filed a complaint) and it does not fill in the returned length of several items. That is the reason that several 'converter functions' are defined in file VMSDEF_$OSSDEF.DAT Examples: $ copy _NLA0: ACL.DAT $! $ directory /acl ACL.DAT Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] ACL.DAT;1 Total of 1 file. $! ---------------------------------------- ----- set a simple ACE >>> import vms_sys >>> acetxt = '(IDENTIFIER=[1,4],ACCESS=EXECUTE+DELETE)' >>> status, errpos, acestr = vms_sys.parse_acl (acetxt) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> # do not use a simple print! >>> print repr (acestr) '\014\001\000\000\014\000\000\000\004\000\001\000' >>> >>> flags = 0 >>> itmlst = (('OSS$_ACL_ADD_ENTRY',acestr),) >>> dict = vms_sys.set_security ('FILE', 'ACL.DAT', None, \ ... flags, itmlst, None) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> $ directory /ACL ACL.DAT Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] Python for OpenVMS -Reference Manual PAGE 2-473 vms_sys.set_security() routine ACL.DAT;1 (IDENTIFIER=[G1,SYSTEM],ACCESS=EXECUTE+DELETE) Total of 1 file. $ ----- change owner UIC of file $ set FILE /OWNER= [2,5] ACL.DAT $ directory /OWNER ACL.DAT Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] ACL.DAT;1 [2,5] Total of 1 file. $ >>> import vms_sys >>> >>> flags = 0 >>> uic = 0x30006 # [3,6] >>> itmlst = ( ('OSS$_OWNER',uic),) >>> >>> dict = vms_sys.set_security ('FILE', 'ACL.DAT', None, \ ... flags, itmlst, None) >>> >>> status = dict.get ('status') >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> $ directory /OWNER ACL.DAT Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS] ACL.DAT;1 [3,6] Total of 1 file. $ 19-JUL-1999 ZE. ------------------------------------------------------------------------ 2.6.73 SHOW_INTRUSION - Show Intrusion Information Format: status, intruder, breakin_block, context = \ vms_sys.show_intrusion (user_criteria, [flags], [context]) Returns: Python for OpenVMS -Reference Manual PAGE 2-474 vms_sys.show_intrusion() routine status Condition value after return of SYS$SHOW_INTRUSION(). intruder User specification of the matched intruder or suspect record in the intrusion database. breakin_block Block to receive various information in the intrusion database about a record matching the user criteria. This is a tuple that consists of the following items: type Type of the matched record. Bitmasks (like CIA_M_TERMINAL) are available from the module 'vms_ciadef'. flags Boolean: 1 = Intruder, 0 = Suspect. count Number of login failures or break-in attempts made by the specified intruder or suspect. time Date and time when the record will expire. This is a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. context Updated context information to keep between related calls to the SYS$SHOW_INTRUSION service. The context automatically becomes invalid after some time - see the 'OpenVMS System Services Reference Manual' for details. At least on OpenVMS VAX V6.1 this argument must always be specified. Omitting it or using 'None' results in the SS$_ACCVIO status being returned. Arguments: user_criteria Description of intruder or suspect. flags Type of records in the intrusion database about which information is to be returned. Bitmasks (like CIA_M_INTRUDERS) are available from module 'vms_ciadef'. context Context information to keep between related calls to the SYS$SHOW_INTRUSION service. The context automatically becomes invalid after some time - see the 'OpenVMS System Services Reference Manual' for details. Examples: $ show intrusion Intrusion Type Count Expiration Source NETWORK INTRUDER 6 14:58:26.80 HERE::SYSTEM Python for OpenVMS -Reference Manual PAGE 2-475 vms_sys.show_intrusion() routine NETWORK SUSPECT 1 14:57:50.33 HERE::ZESSIN $ >>> import vms_ciadef >>> import vms_sys >>> >>> # decode type field in the breakin_block >>> def decode_cia (bb_type): ... if (bb_type & vms_ciadef.CIA_M_INTRUDER): ... print 'CIA_M_INTRUDER' ... if (bb_type & vms_ciadef.CIA_M_SUSPECT): ... print 'CIA_M_SUSPECT' ... if (bb_type & vms_ciadef.CIA_M_NETWORK): ... print 'CIA_M_NETWORK' ... if (bb_type & vms_ciadef.CIA_M_TERM_USER): ... print 'CIA_M_TERM_USER' ... if (bb_type & vms_ciadef.CIA_M_TERMINAL): ... print 'CIA_M_TERMINAL' ... if (bb_type & vms_ciadef.CIA_M_USERNAME): ... print 'CIA_M_USERNAME' ... # decode_cia (bb_type) ... >>> >>> status, intruder, breakin_block, context = \ ... vms_sys.show_intrusion ('*',None, 0) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print intruder HERE::SYSTEM >>> bb_type, bb_flags, bb_count, bb_time = breakin_block >>> print bb_type, bb_flags, bb_count, bb_time 5 0 6 44351387068000000L >>> print vms_sys.asctim (bb_time) 3-JUN-1999 14:58:26.80 >>> >>> decode_cia (bb_type) CIA_M_INTRUDER CIA_M_NETWORK >>> >>> status, intruder, breakin_block, context = \ ... vms_sys.show_intrusion ('*', None, context) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NORMAL, normal successful completion >>> >>> print intruder HERE::ZESSIN >>> bb_type, bb_flags, bb_count, bb_time = breakin_block >>> print bb_type, bb_flags, bb_count, bb_time 6 0 1 44351386703300000L >>> print vms_sys.asctim (bb_time) Python for OpenVMS -Reference Manual PAGE 2-476 vms_sys.show_intrusion() routine 3-JUN-1999 14:57:50.33 >>> >>> decode_cia (bb_type) CIA_M_SUSPECT CIA_M_NETWORK >>> >>> >>> status, intruder, breakin_block, context = \ ... vms_sys.show_intrusion ('*', None, context) >>> print vms_sys.getmsg (status) [0] %SYSTEM-S-NOMOREITEMS, no more items to be returned >>> >>> bb_type, bb_flags, bb_count, bb_time = breakin_block >>> print bb_type, bb_flags, bb_count, bb_time 0 0 0 0L >>> @@ more SYS$SHOW_INTRUSION examples 03-JUN-1999 ZE. ------------------------------------------------------------------------ 2.6.74 SNDJBCW - Send to Job Controller The 'vms_sjcdef' module contains bitmasks and constants that are defined in '$SJCDEF'. Access to the item codes ("SJC$_name") is possible via the 'pyvms' module. Format: dict = vms_sys.sndjbcw ([efn], func, [nullarg], [itmlst], \ [iosb], [astadr], [astprm]) Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$SNDJBCW. Note that this code only tells whether the system service started successfully. The final status code is in the 'iosb'. 'iosb' A 'vmsobj_iosb' object that provides storage for the OpenVMS IOSB (I/O status block). See the description of 'status' above and the 'iosb' argument below. 'SJC$_name' Any output item that has been specified in the item-list and that is supported by SYS$SNDJBCW. It is only put into the dictionary, when SYS$SNDJBCW Python for OpenVMS -Reference Manual PAGE 2-477 vms_sys.sndjbcw() routine returns a success status. Arguments: efn Number of the event flag to be set when SYS$SNDJBCW returns the requested information. If 'None' instead of a number is passed, then EFN 0 is used. func Function code ("SJC$_name"). nullarg Placeholder argument whose value is ignored by the interface routine. You should pass the 'None' object. itmlst Item list that gives information for the function that was selected in the 'func' argument. iosb I/O status block. An IOSB should ALWAYS be specified, because this is the only place that contains the status code AFTER the system service completed. 'status', as returned only gives information whether the system service has been started successfully. The Python interface routine expects a vmsobj_iosb object. If the programmer specifies 'None' for the iosb argument, then the interface routine automatically generates a vmsobj_iosb object, passes the OpenVMS IOSB to SYS$SNDJBCW and returns the object in 'dict'! astadr This argument is ignored. astprm This argument is ignored. special notes about some item codes: SJC$_FILE_IDENTIFICATION This item is stored in the (28-byte) buffer of the OpenVMS item list by a 'converter function'. The data must supplied as a 3-item tuple in the following format: device The device name is passed as a string with a maximum length of 15 characters. This is internally stored as an ASCIC - the first byte is the length. fid The file identification is passed as a 3-item tuple where each item must be a 16-bit integer. Internally this is stored as an array of 3 words. The first item is the file-number. the second item is the sequence numer. The third item is the relative volume number. did The directory file identification is passed as a 3-item tuple where each item must be a 16-bit integer. Python for OpenVMS -Reference Manual PAGE 2-478 vms_sys.sndjbcw() routine Internally this is stored the same way as the 'fid' that is described above. An example of how to use the SJC$_FILE_IDENTIFICATION item code is shown in the examples section. Examples: -- submit a batch job using file-specification $ type SNDJBCW_EXAMPLE.COM $ mail /subject= "Hello from batch job started by vms_sys.sndjbcw()" - NLA0: 'F$GETJPI(0,"USERNAME")' $ exit $ $python >>> import vms_sys >>> itmlst = ( \ ... ("SJC$_QUEUE", "HERE_BATCH"), # input items ... ("SJC$_FILE_SPECIFICATION", "SNDJBCW_EXAMPLE.COM"), ... ("SJC$_JOB_NAME", "SNDJBCW-DEMO"), ... ("SJC$_PARAMETER_1", "Param-1"), ... ("SJC$_ENTRY_NUMBER_OUTPUT"), # output ... ("SJC$_JOB_STATUS_OUTPUT"), # items ... ("SJC$_HOLD"), # boolean ... ("SJC$_NOTIFY") # items ... ) >>> >>> # Note: iosb will be created automatically ------v >>> dict = vms_sys.sndjbcw (None, "SJC$_ENTER_FILE", None, itmlst) >>> >>> for key in dict.keys(): ... print key, '=', dict.get (key) ... # ... SJC$_JOB_STATUS_OUTPUT = Job SNDJBCW-DEMO (queue HERE_BATCH,\ entry 44) holding iosb = SJC$_ENTRY_NUMBER_OUTPUT = 44 status = 1 >>> >>> # 'status' only tells if SYS$SNDJBCW was started successfully >>> status = dict.get ('status') >>> vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> # the final status code of SYS$SNDJBCW is in the first longword >>> # of the iosb (I/O status block) >>> iosb = dict.get ('iosb') >>> status_final = iosb.l0 Python for OpenVMS -Reference Manual PAGE 2-479 vms_sys.sndjbcw() routine >>> print status_final 262145 >>> vms_sys.getmsg (status_final) ('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> $ show ENTRY /FULL 44 Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 44 SNDJBCW-DEMO ZESSIN Holding On idle batch queue HERE_BATCH Submitted 23-MAR-1999 14:05 /NOTIFY /PARAM=("Param-1") /PRIORITY=100 File: _$99$DKA100:[PYTHON.PYTHON-1_5_1.VMS]SNDJBCW_EXAMPLE.COM;2 $ -------------------- -- submit a batch job using file-identification $ directory /file_id tstfid /notrailing Directory DKA100:[PYTHON.PYTHON-1_5_1.VMS] TSTFID.COM;1 (4852,12,0) $ $ python >>> import vms_sys >>> >>> device = '$99$DKA100:' >>> fid = (4852,12,0) >>> did = (0,0,0) >>> >>> itmlst = ( \ ... ("SJC$_FILE_IDENTIFICATION", (device,fid,did)), ... ("SJC$_QUEUE", "HERE_BATCH"), ... ("SJC$_HOLD"), # boolean item code, no data ... ) >>> >>> dict = vms_sys.sndjbcw (None, "SJC$_ENTER_FILE", None, itmlst) >>> >>> for key in dict.keys(): ... print key, '=', dict.get (key) ... # ... iosb = status = 1 >>> >>> # 'status' only tells if SYS$SNDJBCW was started successfully >>> status = dict.get ('status') >>> vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> Python for OpenVMS -Reference Manual PAGE 2-480 vms_sys.sndjbcw() routine >>> # the final status code of SYS$SNDJBCW is in the first longword >>> # of the iosb (I/O status block) >>> iosb = dict.get ('iosb') >>> status_final = iosb.l0 >>> print status_final 262145 >>> vms_sys.getmsg (status_final) ('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> $ show entry /full Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 24 TSTFID ZESSIN Holding On idle batch queue HERE_BATCH Submitted 31-MAR-1999 23:29 /PRIORITY=100 File: _$99$DKA100:[PYTHON.PYTHON-1_5_1.VMS]TSTFID.COM;1 $ -------------------- -- initialize a batch queue >>> import vms_sys >>> itmlst = ( \ ... ("SJC$_QUEUE", "PY_BATCH"), ... ("SJC$_BATCH"), ... ("SJC$_JOB_LIMIT", 5), ... ("SJC$_QUEUE_DESCRIPTION", "PYTHON-test-queue"), ... ("SJC$_RETAIN_ERROR_JOBS"), ... ("SJC$_SCSNODE_NAME", "HERE"), ... ("SJC$_WSQUOTA", 5000) ... ) >>> >>> # Create an iosb object and pass it to the interface routine - >>> # the same object will be returned in 'dict'. >>> import pyvms >>> iosb = pyvms.vmsobj_iosb() >>> >>> dict = vms_sys.sndjbcw (None, "SJC$_CREATE_QUEUE", iosb, itmlst) >>> >>> for key in dict.keys(): ... print key, '=', dict.get (key) ... # ... iosb = status = 1 >>> status = dict.get ('status') >>> vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> iosb = dict.get ('iosb') >>> status_final = iosb.l0 Python for OpenVMS -Reference Manual PAGE 2-481 vms_sys.sndjbcw() routine 262145 >>> vms_sys.getmsg (status_final) ('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> $ show QUEUE /FULL PY_BATCH Batch queue PY_BATCH, stopped, on HERE:: /BASE_PRIORITY=4 /JOB_LIMIT=5 /OWNER=[G1,SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:S) /RETAIN=ERROR /WSQUOTA=5000 $ -------------------- -- delete a job >>> import vms_sys >>> >>> entry = 23 >>> >>> itmlst = ( \ ... ("SJC$_ENTRY_NUMBER", entry), ... ) >>> >>> dict = vms_sys.sndjbcw (None, "SJC$_DELETE_JOB", None, itmlst) >>> >>> for key in dict.keys(): ... print key, "=", dict.get (key) ... # ... iosb = status = 1 >>> status = dict.get ('status') >>> vms_sys.getmsg (status) ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> iosb = dict.get ('iosb') >>> status_final = iosb.l0 >>> print status_final 262145 >>> vms_sys.getmsg (status_final) ('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> -------------------- -- errors >>> itmlst = ('SJC$_ERR',) >>> dict = vms_sys.sndjbcw (None, "SJC$_CREATE_QUEUE", None, itmlst) Traceback (innermost last): File "", line 1, in ? ValueError: itmlst - unknown item code: SJC$_ERR Python for OpenVMS -Reference Manual PAGE 2-482 vms_sys.sndjbcw() routine >>> >>> itmlst = ('SJC$_BATCH',) >>> # >> dict = vms_sys.sndjbcw (None, "SJC$_CREATE_QUEUE", None, \ ... itmlst, 'X') >>> # or None expected -^ Traceback (innermost last): File "", line 1, in ? TypeError: argument 5: iosb - must be vmsobj_iosb or None >>> >>> itmlst = ('SJC$_BATCH',) >>> dict = vms_sys.sndjbcw (None, "BAD_FUNC", None, itmlst) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: invalid function code: BAD_FUNC >>> >>> # SJC$_BATCH is an item code, not a function code >>> itmlst = ('SJC$_BATCH',) # vvvvvvvvvv >>> dict = vms_sys.sndjbcw (None, "SJC$_BATCH", None, itmlst) Traceback (innermost last): File "", line 1, in ? ValueError: argument 2: not a valid function code: SJC$_BATCH >>> @@ more SNDJBCW examples >>> 10-NOV-1999 ZE. ------------------------------------------------------------------------ 2.6.75 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). Python for OpenVMS -Reference Manual PAGE 2-483 vms_sys.subsystem() routine 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 >>> vms_sys.subsystem ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: enbflg - must be integer or None >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.76 SUSPND - Suspend Process Allows a process to suspend itself or another process. Execution can be resumed with the vms_sys.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. Python for OpenVMS -Reference Manual PAGE 2-484 vms_sys.suspnd() routine 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 >>> 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. Python for OpenVMS -Reference Manual PAGE 2-485 vms_sys.suspnd() routine >>> 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') >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.77 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 GENMAN 'Programming', 'special OpenVMS datatypes' for details. utcadr 128-bit UTC value - a Python long integer. Arguments: timadr 64-bit system time - a Python long integer. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. utcadr 128-bit UTC value - a Python long integer. cvtflg conversion flag indicating the direction of the conversion. If omitted, then the value 0 is used. Examples: >>> import vms_sys >>> o_utctim = vms_sys.getutc () Python for OpenVMS -Reference Manual PAGE 2-486 vms_sys.timcon() routine >>> print vms_sys.ascutc (o_utctim) 9-JAN-1999 20:24:31.25 >>> o_utctim 21584378040929278433485881193570887456L >>> >>> q_bintim = vms_sys.timcon (o_utctim,0) >>> print vms_sys.asctim (q_bintim) 9-JAN-1999 20:24:31.25 >>> q_bintim 44226302712500000L >>> >>> q_bintim = vms_sys.gettim () >>> print vms_sys.asctim (q_bintim) 9-JAN-1999 20:25:00.90 >>> q_bintim 44226303009000000L >>> >>> o_utctim = vms_sys.timcon (q_bintim,1) >>> print vms_sys.ascutc (o_utctim) 9-JAN-1999 20:25:00.90 >>> o_utctim 21584378040929278433485881193867387456L >>> >>> q_bintim = vms_sys.gettim () >>> print vms_sys.asctim (q_bintim) 9-JAN-1999 20:25:32.76 >>> q_bintim 44226303327600000L >>> o_utctim = vms_sys.timcon (q_bintim,99) >>> print vms_sys.ascutc (o_utctim) 9-JAN-1999 20:25:32.76 >>> o_utctim 21584378040929278433485881194185987456L >>> >>> q_bintim = vms_sys.timcon (None,0) >>> print vms_sys.asctim (q_bintim) 9-JAN-1999 20:25:51.49 >>> >>> q_bintim = vms_sys.timcon ("",0) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: argtim - must be long integer >>> >>> o_utctim = vms_sys.timcon (None,1) >>> print vms_sys.ascutc (o_utctim) 9-JAN-1999 20:26:14.62 >>> Python for OpenVMS -Reference Manual PAGE 2-487 vms_sys.timcon() routine >>> o_utctim = vms_sys.timcon ("",1) Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: argtim - must be long integer >>> 09-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.78 TRNLNM - Translate Logical Name Returns information about a logical name. vms_sys.trnlnm() does _not_ raise an exception when the SYS$TRNLNM routine returns an error. You must check 'status' in the dictionary that is returned. Format: dict = vms_sys.trnlnm ([attr] ,tabnam ,lognam \ ,[acmode] ,[itmlst]) Returns: dict A dictionary that has the following keys: 'status' The condition value returned from SYS$TRNLNM. 'LNM$_name' Any output items that have been specified in the item-list and that are supported by SYS$TRNLNM. It is only put into the dictionary, when SYS$TRNLNM returns a success status. Arguments: attr Attributes controlling the search for the logical name. See the system services reference manual for details. Bitmask values (LNM_M_name) are available in module 'vms_lnmdef'. tabnam Name of the table or name of a list of tables in which to search for the logical name. lognam Logical name about which information is to be returned. acmode Access mode to used in the translation. If 'None' is specified the outermost name is returned. Python for OpenVMS -Reference Manual PAGE 2-488 vms_sys.trnlnm() routine itmlst Item list describing the information to be returned. Examples: >>> import vms_sys >>> import vms_lnmdef >>> def show_attr (l_attributes): ... from vms_lnmdef import * ... if (l_attributes & LNM_M_NO_ALIAS): ... print 'LNM_M_NO_ALIAS' ... if (l_attributes & LNM_M_CONFINE): ... print 'LNM_M_CONFINE' ... if (l_attributes & LNM_M_CRELOG): ... print 'LNM_M_CRELOG' ... if (l_attributes & LNM_M_TABLE): ... print 'LNM_M_TABLE' ... if (l_attributes & LNM_M_CONCEALED): ... print 'LNM_M_CONCEALED' ... if (l_attributes & LNM_M_TERMINAL): ... print 'LNM_M_TERMINAL' ... if (l_attributes & LNM_M_EXISTS): ... print 'LNM_M_EXISTS' ... if (l_attributes & LNM_M_SHAREABLE): ... print 'LNM_M_SHAREABLE' ... if (l_attributes & LNM_M_CREATE_IF): ... print 'LNM_M_CREATE_IF' ... # - show_attr() ... >>> ---------- >>> dict = vms_sys.trnlnm (0, 'LNM$JOB', 'SYS$LOGIN', None, ... (('LNM$_TABLE',None) , ... ('LNM$_STRING',None) , ... ('LNM$_ATTRIBUTES',None), ... ('LNM$_ACMODE',None) ... ) ... ) >>> >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_TABLE LNM$JOB_814D5680 LNM$_ATTRIBUTES 66560 # see below LNM$_ACMODE 1 # 1 = PSL$C_EXEC status 1 LNM$_STRING USER_HERE:[ZESSIN] >>> >>> l_attributes = dict.get('LNM$_ATTRIBUTES') >>> show_attr (l_attributes) Python for OpenVMS -Reference Manual PAGE 2-489 vms_sys.trnlnm() routine LNM_M_EXISTS LNM_M_SHAREABLE >>> $ show logical /full SYS$LOGIN "SYS$LOGIN" [exec] = "USER_HERE:[ZESSIN]" (LNM$JOB_814D5680) $ ---------- $ DEFINE LNM1 V1,V2,V3,V4,V5 >>> dict = vms_sys.trnlnm (0, 'LNM$PROCESS', 'LNM1', None, ... (('LNM$_MAX_INDEX',None), ... ) ... ) >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_MAX_INDEX 4 status 1 >>> >>> max_index = dict.get('LNM$_MAX_INDEX') >>> for idx in range (max_index+1): ... dict = vms_sys.trnlnm (0, 'LNM$PROCESS', 'LNM1', None, ... (('LNM$_INDEX',idx) , # input-item ! ... ('LNM$_STRING',None) # output-item ... ) ... ) ... status = dict.get('status') ... if (status == 1): # 1 = SS$_NORMAL ... print idx, dict.get('LNM$_STRING') ... else: ... vms_sys.getmsg (status) ... 0 V1 1 V2 2 V3 3 V4 4 V5 >>> ---------- $ SHOW LOGICAL /TABLE=LNM$SYSTEM_DIRECTORY LNM$FILE_DEV* (LNM$SYSTEM_DIRECTORY) "LNM$FILE_DEV" [super] = "LNM$PROCESS" = "LNM$JOB" = "LNM$GROUP" = "LNM$SYSTEM" = "DECW$LOGICAL_NAMES" Python for OpenVMS -Reference Manual PAGE 2-490 vms_sys.trnlnm() routine "LNM$FILE_DEV" [exec] = "LNM$SYSTEM" $ >>> # by default the outermost (regarding processor-mode) >>> # logical name is translated >>> dict = vms_sys.trnlnm (0, 'LNM$SYSTEM_DIRECTORY', ... 'LNM$FILE_DEV', None, ... (('LNM$_TABLE',None) , ... ('LNM$_STRING',None) , ... ('LNM$_ATTRIBUTES',None), ... ('LNM$_ACMODE',None) , ... ('LNM$_MAX_INDEX',None) ... ) ... ) >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_TABLE LNM$SYSTEM_DIRECTORY LNM$_MAX_INDEX 4 # 5 equivalence names (0 to 4) LNM$_ATTRIBUTES 66560 # see below LNM$_ACMODE 2 # 2 = PSL$C_SUPER status 1 LNM$_STRING LNM$PROCESS # at index 0 >>> >>> l_attributes = dict.get('LNM$_ATTRIBUTES') >>> show_attr (l_attributes) LNM_M_EXISTS LNM_M_SHAREABLE >>> ----- >>> # specify an explicit access mode >>> PSL_C_EXEC = 1 >>> dict = vms_sys.trnlnm (0, 'LNM$SYSTEM_DIRECTORY', ... 'LNM$FILE_DEV', PSL_C_EXEC, ... (('LNM$_TABLE',None) , ... ('LNM$_STRING',None) , ... ('LNM$_ATTRIBUTES',None), ... ('LNM$_ACMODE',None) , ... ('LNM$_MAX_INDEX',None) ... ) ... ) >>> for k in dict.keys(): ... print k, dict.get(k) ... LNM$_TABLE LNM$SYSTEM_DIRECTORY LNM$_MAX_INDEX 0 # only one equivalence name LNM$_ATTRIBUTES 66560 # see below LNM$_ACMODE 1 # 1 = PSL$C_EXEC status 1 LNM$_STRING LNM$SYSTEM >>> Python for OpenVMS -Reference Manual PAGE 2-491 vms_sys.trnlnm() routine -------------------- >>> dict = vms_sys.trnlnm (0, 'LNM$PROCESS', ... 'BAD_LNM', None, ... (('LNM$_STRING',None), ... ) ... ) >>> for k in dict.keys(): ... print k, dict.get(k) ... status 444 >>> >>> status = dict.get('status') >>> vms_sys.getmsg (status) ('%SYSTEM-F-NOLOGNAM, no logical name match', (0, 0, 0, 0)) >>> @@ more examples for TRNLNM 29-NOV-1998 ZE. ------------------------------------------------------------------------ 2.6.79 VERIFY_PROXY - Verify a Proxy Format: local_user = vms_sys.verify_proxy \ (rem_node, rem_user [,proposed_user] [,flags]) Returns: local_user Local user the caller must use for a proxy login. Arguments: rem_node Remote node name of the proxy to be verified. rem_user Remote username. proposed_user Local user the caller suggests be used for the proxy login. flags Functional specification and type of local_user (NOdefault). The bit masks are not available from a separate module ($PRXDEF). Examples: >>> import vms_sys >>> PRX_M_DEFAULT = 256 Python for OpenVMS -Reference Manual PAGE 2-492 vms_sys.verify_proxy() routine >>> vms_sys.add_proxy ('REMNOD', 'REMUSR1', 'NOPRIV', PRX_M_DEFAULT) >>> vms_sys.add_proxy ('REMNOD', 'REMUSR1', 'SYSTEM') >>> vms_sys.add_proxy ('REMNOD', 'REMUSR2', 'NOPRIV') >>> vms_sys.add_proxy ('REMNOD', 'REMUSR3', 'SYSTEM') UAF> show /proxy r*::* Default proxies are flagged with (D) REMNOD::REMUSR3 SYSTEM REMNOD::REMUSR1 NOPRIV (D) SYSTEM REMNOD::REMUSR2 NOPRIV UAF> >>> import vms_sys >>> vms_sys.verify_proxy ('REMNOD', 'REMUSR1', 'SYSTEM', 0) 'SYSTEM' >>> >>> vms_sys.verify_proxy ('REMNOD', 'REMUSR1', None, 0) 'NOPRIV' >>> >>> vms_sys.verify_proxy ('REMNOD', 'REMUSR1', 'NO_USR', 0) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (116311634, '%SECSRV-E-NOSUCHUSER, no user matches\ your specification') >>> >>> vms_sys.verify_proxy ('REMNOD', 'NO_REM_USR', None, 0) Traceback (innermost last): File "", line 1, in ? vms_sys.error: (116311666, '%SECSRV-E-NOSUCHPROXY, no proxy record\ matches your specification') >>> 21-JAN-1999 ZE. ------------------------------------------------------------------------ 2.6.80 WAITFR - Wait for Single Event Flag Tests a specific event flag and returns immediately if the flag is set. Otherwise, the process is placed in a wait state until the event flag is set. Format: Python for OpenVMS -Reference Manual PAGE 2-493 vms_sys.waitfr() routine vms_sys.waitfr (efn) Returns: None Arguments: efn Number of the event flag for which to wait. Examples: >>> import vms_sys @@ WAITFR not yet (15-SEP-1998) tested >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.81 WAKE - Wake Process from Hibernation Activates a process that has placed itself in a state of hibernation with the Hibernate (SYS$HIBER) service. Format: targpid = vms_sys.wake ([pidadr] [,prcnam]) Returns: 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 Python for OpenVMS -Reference Manual PAGE 2-494 vms_sys.wake() routine >>> 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 read-only buffer, int found >>> vms_sys.wake ('X') Traceback (innermost last): File "", line 1, in ? TypeError: argument 1: pidadr - must be integer or None >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.82 WFLAND - Wait for Logical AND of Event Flags Allows a process to specify a set of event flags for which it wants to wait. Format: vms_sys.wfland (efn, mask) Returns: None Arguments: efn Python for OpenVMS -Reference Manual PAGE 2-495 vms_sys.wfland() routine Number of any event flag within the event flag cluster to be used. mask Event flags for which the process is to wait. Examples: >>> import vms_sys @@ WFLAND not yet (15-SEP-1998) tested >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 2.6.83 WFLOR - Wait for Logical OR of Event Flags Allows a process to specify a set of event flags for which it wants to wait. Format: vms_sys.wflor (efn, mask) Returns: None Arguments: efn Number of any event flag within the event flag cluster to be used. mask Event flags for which the process is to wait. Examples: >>> import vms_sys @@ WFLOR not yet (15-SEP-1998) tested >>> 28-SEP-1998 ZE. ------------------------------------------------------------------------ 01-JUL-2001 ZE. (VMS_SYS.HTML) Python for OpenVMS -Reference Manual PAGE 2-496 vms__struct module 2.7 vms__struct module The 'vms__struct' module is an OpenVMS specific variant of the 'struct' module in Python's standard library. Most of the code, however has been independently developed. ------------------------------------------------------------------------ It has three functions: - CALCSIZE Calculate the buffer size from a format string. Certain format characters might require the data, too. - PACK Compose a list of Python objects into a (binary) string using a format string. - UNPACK Decompose a Python string or 'vmsobj__membuf' object to a list of Python objects. The format string is described after the functions. ------------------------------------------------------------------------ 2.7.1 CALCSIZE - Calculate buffer size from format string Calculate the buffer size from a format string. Certain format characters might require the data, too. Format: size = vms__struct.calcsize (fmt, [data]) Returns: size Length of the buffer as calculated from the format string 'fmt'. Arguments: fmt The format string. It is described below. data Some format characters require data present, because length information is embedded. @@ currently not implemented Examples: >>> import vms__struct Python for OpenVMS -Reference Manual PAGE 2-497 vms__struct.calcsize() routine >>> fmt = 'BB' >>> size = vms__struct.calcsize (fmt) >>> print size 2 >>> >>> fmt = 'W bb L 3C' >>> size = vms__struct.calcsize (fmt) >>> print size 11 >>> ---------------------------------------- >>> print vms__struct.calcsize ('*BAD*') Traceback (innermost last): File "", line 1, in ? vms__struct.error: invalid format character '*' at position: 0 >>> 01-OCT-2000 ZE. ------------------------------------------------------------------------ 2.7.2 PACK - Compose list of Python objects into string Compose a list of Python objects into a (binary) string or 'vmsobj__membuf' object using a format string. Format: data = vms__struct.pack (fmt, data_in, buftyp) Returns: data A Python string or a 'vmsobj__membuf' object (default, unless 'buftyp' specified "string") that is composed from 'data_in' using the format string 'fmt'. Arguments: fmt The format string. It is described below. data_in Python input data. The data must be supplied as a Python tuple or a list, even when only one item is to be converted. Items using a multiplier, however, must be a tuple. e.g. data for the format "W 3b" must be [w,(b1,b2,b3)] or (w,(b1,b2,b3)) buftyp Python type in which the data should be returned. Specify Python for OpenVMS -Reference Manual PAGE 2-498 vms__struct.pack() routine "string" for a Python string or "membuf" (default, if none specified for a 'vmsobj__membuf' object. Examples: >>> import vms__struct Using the buftyp parameter: >>> data_in = (1,2) >>> fmt = 'BB' >>> data = vms__struct.pack (fmt, data_in, "string") >>> print type (data) >>> print repr (data) '\001\002' >>> >>> data = vms__struct.pack (fmt, data_in, "membuf") >>> print type (data) >>> >>> data = vms__struct.pack (fmt, data_in) >>> print type (data) >>> print repr (data.buffer) '\001\002' >>> Currently, PACK() does not treat signed and unsigned differently: >>> data_in = (254,254,-2,-2) >>> fmt='BbBb' >>> data = vms__struct.pack (fmt, data_in, "string") >>> print repr (data) '\376\376\376\376' >>> Combining different format characters: >>> fmt = 'W bb L 3C' >>> data_in = (3, 1, 2, 32769, 'ABC') >>> data = vms__struct.pack (fmt, data_in, "string") >>> print repr (data) '\003\000\001\002\001\200\000\000ABC' WWWWWWWW bbb bbb LLLLLLLLLLLLLLLCCC Note that Alpha and VAX are little-endian architectures. The least significant byte (e.g. '003' of the 'W') is at the left side, because this is the lowest memory address. It is possible to reverse the output string: >>> import string Python for OpenVMS -Reference Manual PAGE 2-499 vms__struct.pack() routine >>> data_l = list (data) >>> data_l.reverse () >>> data = string.join (data_l,'') >>> print repr (data) 'CBA\000\000\200\001\002\001\000\003' CCC LLLLLLLLLLLLLLL bbb bbb wwwwwww Multipliers on integers make this more complicated. >>> fmt = 'W 2b 3L 2C' >>> data_in = (3, (1,2), (32769,32770,32771), 'AB') >>> data = vms__struct.pack (fmt, data_in, "string") >>> print repr (data) '\003\000\001\002\001\200\000\000\002\200\000\000\003\200\000\000AB' wwwwwww b1 b2 l1------------^ l2------------^ l3------------^2C creating any number of zero-filled bytes is easier when using the filler ('_') format character. >>> fmt = 'b5_b' >>> data_in = (1,2) >>> data = vms__struct.pack (fmt, data_in, "string") >>> print repr (data) '\001\000\000\000\000\000\002' bbb 5_ ---------------^ bbb A single item must be a tuple or list. >>> fmt = 'b' >>> data_in = (1) >>> data = vms__struct.pack (fmt, data_in, "string") Traceback (innermost last): File "", line 1, in ? vms__struct.error: argument 2: data_in - must be a sequence (list/tuple) >>> >>> data_in = (1,) >>> data = vms__struct.pack (fmt, data_in, "string") >>> print repr (data) '\001' >>> Python long ints cannot be used for BWL. This is a limit in internal routines. >>> fmt = 'b' >>> data_in = (1L,) >>> data = vms__struct.pack (fmt, data_in, "string") Traceback (innermost last): File "", line 1, in ? TypeError: vms__cvt_py2bin(): data of item must be integer >>> There a limits for the multiplier of several format characters. Python for OpenVMS -Reference Manual PAGE 2-500 vms__struct.pack() routine >>> fmt = '32768W' >>> data_in = [1]*32768 >>> data = vms__struct.pack (fmt, data_in, "string") Traceback (innermost last): File "", line 1, in ? SystemError: vms__cvt_py2bin(): datatype bigger than buffer length >>> Well, the error message is not correct in this situation. >>> fmt = '32767W' >>> data_list = [1]*32767 Multipliers of integers must be delivered via a tuple and 'data_in' itself must be a list or tuple. >>> data_in = (tuple (data_list),) >>> data = vms__struct.pack (fmt, data_in, "string") >>> print len (data) 65534 >>> So, a multiplier of an integer value can never describe an output of more than 65535 bytes. It is, however, possible to use several multipliers: >>> fmt = '32767W 32767W' ---------------------------------------- >>> fmt = 'W 2b 3L 2C' >>> data_in = (3, (1,2), (32769,32770,32771, 'ABC')) >>> data = vms__struct.pack (fmt, data_in, "string") Traceback (innermost last): File "", line 1, in ? SystemError: vms__cvt_py2bin(): Python tuple(4)/data-array(3) sizes do not match --- the input string must not be longer that the fmt string says >>> data_in = (3, (1,2), (32769,32770,32771), 'ABC') >>> data = vms__struct.pack (fmt, data_in, "string") Traceback (innermost last): File "", line 1, in ? vms__struct.error: input string/bufer to long for specified length:%d@@@ >>> >>> print vms__struct.pack ('*BAD*') Traceback (innermost last): File "", line 1, in ? vms__struct.error: invalid format character '*' at position: 0 >>> 01-OCT-2000 ZE. ------------------------------------------------------------------------ Python for OpenVMS -Reference Manual PAGE 2-501 vms__struct.unpack() routine 2.7.3 UNPACK - DeCompose a string or a 'vmsobj__membuf' object into a list of Python objects Format: l1 = vms__struct.unpack (fmt, data, offset) Returns: l1 .. Arguments: fmt The format string. It is described below. data Python input data. ... offset .. Examples: >>> import vms__struct ... >>> 28-MAR-2001 ZE. ------------------------------------------------------------------------ 2.7.4 format string description ' ' The space character is only used to improve readability, it is ignored between items. A single item (e.g. '12C'), cannot contain any spaces. 0..9 Numbers between 0 and 9 form a multiplier that specifies how often a format character is to be repeated. Not every format character allows a multiplier (other than 1) '_' The underscore character serves as a filler. When used in a PACK call, a single zero-filled byte is placed in the buffer. When used in a UNPACK call, that particular byte in the buffer is skipped. A multiplier (e.g. "5_") is allowed. C A single (1 byte) character is taken or returned as a Python Python for OpenVMS -Reference Manual PAGE 2-502 vms__struct format string string. A multiplier (e.g. "12C") is allowed. More formats are available through the introducer character 'c' There are 10 format characters for integer types ('BbWwLlQqOo'): an upper-case character indicates a signed value, a lower-case character indicates an unsigned value. B a single signed byte Range: -128..127 Python type: Python (32-bit signed) int Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python integers. The maximum value for the multiplier is 65535 due to limits in internal routines. @@@ >>> fmt='b' >>> data=2L >>> out=vms__struct.pack (fmt,[data]) Traceback (innermost last): File "", line 1, in ? TypeError: vms__cvt_py2bin(): data of item must be integer >>> @@?? allow a long as input? b a single unsigned byte Range: 0..255 Python type: Python (32-bit signed) int Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python integers. The maximum value for the multiplier is 65535 due to limits in internal routines. W a single signed word (2 bytes) Range: -32768..32767 Python type: Python (32-bit signed) int Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python integers. The maximum value for the multiplier is 32767 due to limits in internal routines. w a single unsigned word (2 bytes) Range: 0..65535 Python type: Python (32-bit signed) int Excessive bits are ignored during PACK(). Python for OpenVMS -Reference Manual PAGE 2-503 vms__struct format string Use of a multiplier takes or returns a tuple of Python integers. The maximum value for the multiplier is 32767 due to limits in internal routines. L a single signed longword (4 bytes) Range: -2147483648..2147483647 Python type: Python (32-bit signed) int Use of a multiplier takes or returns a tuple of Python (long) integers. The maximum value for the multiplier is 16383 due to limits in internal routines. l a single unsigned longword (4 bytes) Range: 0..4294967296 Python type: Python long int (!) @@ currently not available during PACK(), because Python does not have an unsigned 32-bit type Use of a multiplier takes or returns a tuple of Python (long) integers. The maximum value for the multiplier is 16383 due to limits in internal routines. Q a single signed quadword (8 bytes) Range: -9223372036854775808.. 9223372036854775807 Python type: Python long int (!) Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python long integers. The maximum value for the multiplier is 8191 due to limits in internal routines. q a single unsigned quadword (8 bytes) Range: 0..18446744073709551616 Python type: Python long int (!) Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python long integers. The maximum value for the multiplier is 8191 due to limits in internal routines. O a single signed octaword (16 bytes) Range: -170141183460469231731687303715884105728 .. 170141183460469231731687303715884105727 Python type: Python long int (!) Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python long integers. The maximum value for the multiplier is 4095 due to limits in internal routines. o a single unsigned octaword (16 bytes) Range: 0..340282366920938463463374607431768211456 Python type: Python long int (!) Python for OpenVMS -Reference Manual PAGE 2-504 vms__struct format string Excessive bits are ignored during PACK(). Use of a multiplier takes or returns a tuple of Python long integers. The maximum value for the multiplier is 4095 due to limits in internal routines. ------------------------------------------------------------------------ Introducers are used for groups of similar data types. Currently, there are two characters used: c Specifices other character formats. f Specifies floating point formats. ----- Format characters after introducer 'c' (character formats). B An ASCIC string. The first byte in memory defines the string size. The string object that is passed to @@pack() or returned from @@unpack does not include this length. ----- Format characters after introducer 'f' (floating point formats). F F_Floating (VAX). D D_Floating (VAX). Currently not implemented. G G_Floating (VAX). Currently not implemented. S S_Floating (IEEE). Currently not implemented. T T_Floating (IEEE). Currently not implemented. X X_Floating (IEEE). Currently not implemented. 22-JAN-2001 ZE. ------------------------------------------------------------------------ 02-OCT-2000 ZE. (VMS__STRUCT.HTML) Python for OpenVMS -Reference Manual PAGE 2-505 vms__struct format string 2.8 'VMSDEF'-related modules 2.8.1 maintaining VMSDEF modules VMSDEF modules consist of several files: VMSDEF_$fac.DAT The source file that can contain item codes, bitmasks and constants. It is converted by the procedure 'VMSDEF2MAR.COM' (described in the 'tools' section of the 'GENeral MANual') to the file 'VMSDEF_$fac.MAR' by using the following command: $ @PYTHON_VMS:VMSDEF2MAR VMSDEF_$fac.DAT Due to a deficy in VMSDEF2MAR.COM at least one item code, even if it is a dummy one, MUST be present. VMSDEF_$fac.MAR This is a file that is run through the macro assembler by using the following command: $ @PYTHON_VMS:BLDRUN VMS_MACRO VMSDEF_$fac.MAR The resulting object file (VMSDEF_$fac.OBJ) is put into the object library in [.VMS.O_architecture]VMS_MACRO.OLB. ('architecture' is either 'ALPHA' or 'VAX'). VMSDEF_DIRECTORY.MAR After a new VMSDEF module has been created, the list of modules must be updated. The file VMSDEF_DIRECTORY.MAR is created by running the procedure 'VMSDEF_BLDDIR2MAR.COM' (described in the 'tools' section of the 'GENeral MANual') This file is then run through the macro assembler by using the following command: $ @PYTHON_VMS:BLDRUN VMS_MACRO VMSDEF_DIRECTORY.MAR The resulting object file is, too, put in VMS_MACRO.OLB. VMS_facDEF.C It is often usefull that the programmer has access to the bitmasks and constants of a VMSDEF module (the interface routines take care of the item codes). This files (VMS_*DEF.C) create Python modules (e. g. 'vms_jpidef') that can be imported: >>> import vms_jpidef >>> print vms_jpidef.JPI_K_BATCH 2 >>> print vms_jpidef.JPI_M_PASSWORD_EXPIRED 4 >>> While one can directly use numbers, a reference through the symbolic name in the module makes the programs much more readable. Python for OpenVMS -Reference Manual PAGE 2-506 maintaining VMSDEF modules ------------------------------------------------------------------------ 28-FEB-2000 ZE. 2.8.2 vms_brkdef module The 'vms_brkdef' module contains bitmasks and comstants that are defined in '$BRKDEF'. These definitions are used by: - vms_sys.brkthruw() Related files: - VMSDEF_$BRKDEF.DAT - VMSDEF_$BRKDEF.MAR (See 'maintaining VMSDEF modules' for details) @@ Ignore the 'BRK$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. ------------------------------------------------------------------------ 13-AUG-1999 ZE. 2.8.3 vms_ciadef module The 'vms_ciadef' module contains bitmasks that are defined in '$CIADEF'. These definitions are used by a number of routines: - vms_sys.delete_intrusion() - vms_sys.scan_intrusion() - vms_sys.show_intrusion() Related files: - VMSDEF_$CIADEF.DAT - VMSDEF_$CIADEF.MAR (See 'maintaining VMSDEF modules' for details) @@ Ignore the 'CIA$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. ------------------------------------------------------------------------ 01-JUN-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-507 vms_dcdef module 2.8.4 vms_dcdef module The 'vms_dcdef' module contains constants that are defined in '$DCDEF' which define device classes and types. These definitions are used by the vms_sys.device_scan() routine. Access to details of the constants is currently _NOT_ possible from the 'pyvms' module. @@ The reason is that constants and bitmasks must be tied to an item code in the current implementation, but $DCDEF does not define any item codes! WARNING! Importing this module makes more then 500 constants available. Related files: - VMSDEF_$DCDEF.DAT - VMSDEF_$DCDEF.MAR (See 'maintaining VMSDEF modules' for details) @@ Ignore the 'DC$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.5 vms_dmtdef module The 'vms_dmtdef' module contains bitmasks that are defined in '$DMTDEF'. These bitmasks are used by the vms_sys.dismou() routine. Related files: - VMSDEF_$DMTDEF.DAT - VMSDEF_$DMTDEF.MAR (See 'maintaining VMSDEF modules' for details) @@ Ignore the 'DMT$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.6 vms_dvidef module The 'vms_dvidef' module contains item codes, bitmasks and constants that are defined in '$DVIDEF'. These definitions can be used with, e. g. the vms_lib.getdvi() routine. Access to details of the item codes is possible from the 'pyvms' Python for OpenVMS -Reference Manual PAGE 2-508 vms_dvidef module module. Related files: - VMSDEF_$DVIDEF.DAT - VMSDEF_$DVIDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.7 vms_dvsdef module There is no real 'vms_dvsdef' module that can be imported, because '$DVSDEF' contains only item codes but no bitmasks or constants. These codes are used by the vms_sys.device_scan() routine. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$DVSDEF.DAT - VMSDEF_$DVSDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.8 vms_fabdef module The 'vms_fabdef' module contains bitmasks and constants that are defined in '$FABDEF'. The data definition are to be used together with a 'vmsobj_fab' object. There are no real item codes in this module. Related files: - VMSDEF_$FABDEF.DAT - VMSDEF_$FABDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.9 vms_fscndef module The 'vms_fscndef' module contains item codes and bitmasks that are defined in '$FSCNDEF'. These are used by the vms_sys.filescan() routine. Python for OpenVMS -Reference Manual PAGE 2-509 vms_fscndef module Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$FSCNDEF.DAT - VMSDEF_$FSCNDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.10 vms_initdef module The 'vms_initdef' module contains item codes and constants that are defined in '$INITDEF'. These definitions are used by the vms_sys.init_vol() routine. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$INITDEF.DAT - VMSDEF_$INITDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 28-FEB-1999 ZE. 2.8.11 vms_jpidef module The 'vms_jpidef' module contains item codes, bitmasks and constants that are defined in '$JPIDEF'. These definitions are used by the vms_lib.getjpi(), vms_sys.getjpiw() and other routines. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$JPIDEF.DAT - VMSDEF_$JPIDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 01-JUN-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-510 vms_kgbdef module 2.8.12 vms_kgbdef module The 'vms_kgbdef' module contains constants and bit masks that are defined in '$KGBDEF'. A number of system services use these definitions: - vms_sys.add_holder() - vms_sys.add_ident() - vms_sys.find_held() - vms_sys.find_holder() - vms_sys.grantid() - vms_sys.idtoasc() - vms_sys.mod_holder() - vms_sys.mod_ident() - vms_sys.revokid() Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$KGBDEF.DAT - VMSDEF_$KGBDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 24-OCT-2000 ZE. 2.8.13 vms_lbrdef module The 'vms_lbrdef' module contains bitmasks that are defined in '$LBRDEF'. Related files: - VMSDEF_$LBRDEF.DAT - VMSDEF_$LBRDEF.MAR (See 'maintaining VMSDEF modules' for details) @@ Ignore the 'LBR$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. ------------------------------------------------------------------------ 01-MAY-2001 ZE. 2.8.14 vms_lckdef module The 'vms_lckdef' module contains bitmasks and constants that are defined in '$LCKDEF'. A number of system services use these definitions: Python for OpenVMS -Reference Manual PAGE 2-511 vms_lckdef module - vms_sys.enqw() - vms_sys.deq() Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$LCKDEF.DAT - VMSDEF_$LCKDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 30-MAY-1999 ZE. 2.8.15 vms_lnmdef module The 'vms_lnmdef' module contains item codes, bitmasks and constants that are defined in '$LNMDEF'. A number of system services use these definitions: - vms_lib.set_logical() - vms_sys.crelnm() - vms_sys.crelnt() - vms_sys.trnlnm() Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$LNMDEF.DAT - VMSDEF_$LNMDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 01-MAR-1999 ZE. 2.8.16 vms_maildef module The 'vms_maildef' module contains item codes, bitmasks and constants that are defined in '$MAILDEF'. These are used by the OpenVMS MAIL (vms_mail) utility routines. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$MAILDEF.DAT - VMSDEF_$MAILDEF.MAR (See 'maintaining VMSDEF modules' for details) Python for OpenVMS -Reference Manual PAGE 2-512 vms_maildef module ------------------------------------------------------------------------ 23-MAY-1999 ZE. 2.8.17 vms_mntdef module The 'vms_mntdef' module contains item codes, bitmasks and constants that are defined in '$MNTDEF'. These are used by the vms_sys.mount() system service. Comments about some item codes are there, too. Related files: - VMSDEF_$MNTDEF.DAT - VMSDEF_$MNTDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 01-MAR-1999 ZE. 2.8.18 vms_namdef module The 'vms_namdef' module contains bitmasks and constants that are defined in '$NAMDEF'. The data definition can be used together with a 'vmsobj_nam' object. There are no real item codes in this module. Related files: - VMSDEF_$NAMDEF.DAT - VMSDEF_$NAMDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 01-MAR-1999 ZE. 2.8.19 vms_ossdef module The 'vms_ossdef' module contains bitmasks and item codes that are defined in '$OSSDEF'. These definitions are used by: - vms_sys.get_security() - vms_sys.set_security() (OSS is for "Object Security Service") Related files: - VMSDEF_$OSSDEF.DAT - VMSDEF_$OSSDEF.MAR (See 'maintaining VMSDEF modules' for details) Python for OpenVMS -Reference Manual PAGE 2-513 vms_ossdef module ------------------------------------------------------------------------ 03-JUL-1999 ZE. 2.8.20 vms_prcdef module The 'vms_prcdef' module contains item codes and bitmasks that are defined in '$PRCDEF'. These definitions are used by the vms_sys.creprc() routine. The bitmasks can also be used with the returned result of the JPI$_CREPRC_FLAGS item code after a call to vms_lib.getjpi() or vms_sys.getjpiw(). Related files: - VMSDEF_$PRCDEF.DAT - VMSDEF_$PRCDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.21 vms_prvdef module The 'vms_prvdef' module contains bitmasks that are defined in '$PRVDEF' which defines the process privilege bits. The privilege masks are 64-bit wide. They are represented as Python long integers. Handling of these masks is explained in GENMAN 'programming, processes, privileges'. These definitions are usefull for the JPI$_AUTHPRIV, JPI$_CURPRIV, JPI$_IMAGPRIV and JPI$_PROCPRIV item codes that are used in a call to vms_lib.getjpi() or vms_sys.getjpiw(), the UAI$_DEF_PRIV and UAI$_PRIV item codes that are used in a call to vms_sys.getuai() or vms_sys.setuai(), the vms_sys.creprc() or the vms_sys.process_scan() routines. @@ Ignore the 'PRV$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. - VMSDEF_$PRVDEF.DAT - VMSDEF_$PRVDEF.MAR. (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-514 vms_pscandef module 2.8.22 vms_pscandef module The 'vms_pscandef' module contains item codes, bitmasks and constants that are defined in '$PSCANDEF'. These are used to set up an item list for the vms_sys.process_scan() routine. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$PSCANDEF.DAT - VMSDEF_$PSCANDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.23 vms_quidef module The 'vms_quidef' module contains item codes, bitmasks and constants that are defined in '$QUIDEF'. These are used by the vms_lib.getqui() and vms_sys.getquiw() routines. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$QUIDEF.DAT - VMSDEF_$QUIDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 12-MAY-1999 ZE. 2.8.24 vms_rabdef module The 'vms_rabdef' module contains bitmasks and constants that are defined in '$RABDEF'. The data definition can be used together with a 'vmsobj_rab' object. There are no real item codes in this module. Related files: - VMSDEF_$RABDEF.DAT - VMSDEF_$RABDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-515 vms_rsdmdef module 2.8.25 vms_rsdmdef module The 'vms_rsdmdef' module contains bitmasks that are defined in '$RSDMDEF'. These definitions are used by a number of routines: - vms_sys.set_resource_domain() Related files: - VMSDEF_$RSDMDEF.DAT - VMSDEF_$RSDMDEF.MAR (See 'maintaining VMSDEF modules' for details) @@ Ignore the 'RSDM$_*' item codes in this module. They are a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. ------------------------------------------------------------------------ 21-AUG-1999 ZE. 2.8.26 vms_sjcdef module The 'vms_sjcdef' module contains item codes, bitmasks and constants that are defined in '$SJCDEF'. The data definitions are used by the 'vms_sys.sndjbcw()' routine. Related files: - VMSDEF_$SJCDEF.DAT - VMSDEF_$SJCDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 17-MAR-1999 ZE. 2.8.27 vms_smgdef module The 'vms_smgdef' module contains item codes, bitmasks and constants that are defined in '$SMGDEF'. The data definitions are used by the 'vms_smg.()' routines. Related files: - VMSDEF_$SMGDEF.DAT - VMSDEF_$SMGDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 28-FEB-2000 ZE. Python for OpenVMS -Reference Manual PAGE 2-516 vms_statedef module 2.8.28 vms_statedef module The 'vms_statedef' module contains constants that are defined in '$STATEDEF' which defines the process states. These definitions are usefull for the JPI$_STATE item code that is used in a call to vms_lib.getjpi() or vms_sys.getjpiw(). @@ Ignore the 'STATE$_NULL' item code in this module. It is a work-around to a deficy in the VMSDEF2MAR.COM procedure which currently cannot cope with a VMSDEF module that has no item codes. Related files: - VMSDEF_$STATEDEF.DAT - VMSDEF_$STATEDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.29 vms_syidef module The 'vms_syidef' module contains item codes, bitmasks and constants that are defined in '$SYIDEF'. These definitions are used by the vms_lib.getsyi() routine. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$SYIDEF.DAT - VMSDEF_$SYIDEF.MAR. (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.30 vms_trmdef module The 'vms_trmdef' module contains item codes, bitmasks and constants that are defined in '$TRMDEF'. These are used by the 'vmsobj_xabtrm' object. Comments about some item codes are there, too. Related files: - VMSDEF_$TRMDEF.DAT - VMSDEF_$TRMDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 15-FEB-1999 ZE. Python for OpenVMS -Reference Manual PAGE 2-517 vms_uaidef module 2.8.31 vms_uaidef module The 'vms_uaidef' module contains item codes, bitmasks and constants that are defined in '$UAIDEF'. These are used in calls to the vms_sys.getuai() and vms_sys.setuai() routines. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$UAIDEF.DAT - VMSDEF_$UAIDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.32 vms_xaballdef module The 'vms_xaballdef' module contains bitmasks and constants that are defined in '$XABALLDEF' - the ALLocation XAB (eXtended Attribute Block). The data definition can be used together with a 'vmsobj_xaball' object. There are no real item codes in this module. The structure is called a XABALL, however the facility name for bitmasks and constants is 'XAB' - e. g. 'XAB_C_ANY'. Related files: - VMSDEF_$XABALLDEF.DAT - VMSDEF_$XABALLDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.33 vms_xabdatdef module There is no 'vms_xabdatdef' module, because a 'vmsobj_xabdat' object does not have any attributes that make use of bitmasks or constants. ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.34 vms_xabfhcdef module The 'vms_xabfhcdef' module contains bitmasks that are defined in '$XABFHCDEF' - the File Header Characteristic XAB (eXtended Attribute Block). The data definition can be used together with a Python for OpenVMS -Reference Manual PAGE 2-518 vms_xabfhcdef module 'vmsobj_xabfhc' object. There are no real item codes in this module. The structure is called a XABFHC, however the facility name for the bitmasks is 'XAB' - e. g. 'XAB_M_FTN'. Related files: - VMSDEF_$XABFHCDEF.DAT - VMSDEF_$XABFHCDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.35 vms_xabitmdef module The 'vms_xabitmdef' module contains item codes, bitmasks and constants that are defined in '$XABITMDEF' - the ITeM list XAB (eXtended Attribute Block). The data definition can be used together with a 'vmsobj_xabitm' object. The structure is called a XABITM, however the facility name for bitmasks and constants is 'XAB' - e. g. 'XAB_M_CAP_FILALL'. This module contains 64-bit bitmasks. See GENMAN, 'Programming', 'special OpenVMS datatypes' for details. Access to details of the item codes is possible from the 'pyvms' module. Related files: - VMSDEF_$XABITMDEF.DAT - VMSDEF_$XABITMDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.36 vms_xabkeydef module The 'vms_xabkeydef' module contains bitmasks and constants that are defined in '$XABKEYDEF' - the KEY definition XAB (eXtended Attribute Block). The data definition can be used together with a 'vmsobj_xabkey' object. There are no real item codes in this module. The structure is called a XABKEY, however the facility name for bitmasks and constants is 'XAB' - e. g. 'XAB_M_IDX_NCMPR'. Related files: - VMSDEF_$XABKEYDEF.DAT Python for OpenVMS -Reference Manual PAGE 2-519 vms_xabkeydef module - VMSDEF_$XABKEYDEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 02-MAR-1999 ZE. 2.8.37 vms_xabprodef module The 'vms_xabprodef' module contains bitmasks and constants that are defined in '$XABPRODEF' - the PROtection XAB (eXtended Attribute Block). The data definition can be used together with a 'vmsobj_xabpro' object. There are no real item codes in this module. The structure is called a XABPRO, however the facility name for bitmasks and constants is 'XAB' - e. g. 'XAB_M_PROPAGATE'. Related files: - VMSDEF_$XABPRODEF.DAT - VMSDEF_$XABPRODEF.MAR (See 'maintaining VMSDEF modules' for details) ------------------------------------------------------------------------ 08-MAR-1999 ZE. CHAPTER 3 VMS Objects This section explains the use of 'VMS objects'. 'VMS objects' serve as an access means to complex data structures like FABs or RABs. The goal is to make as much functionality available as possible, but keeping the Python interpreter stable. For example, it is not possible to directly store an address in a data structure. ------------------------------------------------------------------------ The components of a structure are accessible through the get- and set-attribute interfaces of the object. Beginning with version 1.5.2-V006 it is possible to view the attributes with Python's "dir()" function. The dictionary that is internally used for this functionality, however, does not contain the data values - they are just "None" - and it is always recreated. The reason for this special restriction is that the list of names should just be used as a reminder - more detailled information MUST be taken from the OpenVMS documentation. >>> import pyvms >>> >>> fab = pyvms.vmsobj_fab() >>> dir (fab) ['B_ACMODES', 'B_BID', 'B_BKS', 'B_BLN', 'B_DNS', 'B_FAC', 'B_FNS', ... ', 'M_WCK', 'NAM', 'W_BLS', 'W_DEQ', 'W_GBC', 'W_IFI', 'W_MRS', 'XAB'] >>> >>> dict = fab.__dict__ >>> print dict {'M_RU': None, 'M_TMP': None, 'L_FOP': None, 'M_TRN': None, ... 'CTX': None, 'M_SHRPUT': None} >>> >>> >>> membuf = pyvms.vmsobj__membuf(5) >>> dir (membuf) ['buffer', 'size', 'zero'] >>> Python for OpenVMS -Reference Manual PAGE 3-2 VMS Objects - introduction Integer data types (Byte, Word, Long) can be accessed directly: >>> # set FAB$L_ALQ >>> fab.L_ALQ = 100 >>> print fab.L_ALQ 100 >>> >>> # set FAB$B_BKS >>> fab.B_BKS = 12 >>> print fab.B_BKS 12 >>> Single bits can be directly set/cleared and queried by specifying the name as the attribute: >>> # set FAB$M_GET >>> fab.M_GET = 1 >>> print fab.M_GET 2 >>> print fab.B_FAC # FAB$M_GET is in FAB$B_FAC 2 >>> >>> # set FAB$M_BIO >>> fab.M_BIO = 1 >>> print fab.M_BIO 32 >>> print fab.B_FAC # 2+32 = 34 34 >>> >>> fab.M_GET = 0 # clear bit >>> print fab.B_FAC 32 >>> Any non-zero value sets the specified bit. >>> fab.M_GET = 9 >>> print fab.M_GET 2 >>> Other, more complex datatypes will be described together with the object. Notice that beginning with version 2.0-V001 the original bit mask value is returned - a non-zero value is no longer converted to 1. ------------------------------------------------------------------------ 16-OCT-2000 ZE. Python for OpenVMS -Reference Manual PAGE 3-3 vmsobj_fab object 3.0.1 vmsobj_fab object The vmsobj_fab object provides high-level access to an OpenVMS FAB (File Access Block) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_FAB.C) nor will it explain the use of each field in a FAB. The 'vms_fabdef' module contains bit masks and constants that apply to an OpenVMS FAB. ------------------------------------------------------------------------ Attributes: Most BWL,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: B_ACMODES This is a structure of 4 2-bit fields named. The following bit offsets are in module 'vms_fabdef': FAB$V_LNM_MODE, FAB$V_CHAN_MODE, FAB$V_FILE_MODE, FAB$V_CALLERS_MODE. CTX The user context (CTX) field can be used to pass information to a completion routine. This field is never used by RMS. Internally, the FAB$L_CTX field of the OpenVMS FAB contains the address of the vmsobj_fab object. It cannot be overwritten. The vmsobj_fab object provides a "CTX" attribute which allows the programmer to associate a Python object with it. If no object was ever assigned to the "CTX" attribute, then a read access will return the 'None' object. You can assign the 'None' object to "CTX", but this will not put a 0 value into "L_CTX" unlike some other attributes - see the examples below. >>> fab = pyvms.vmsobj_fab () >>> type (fab) >>> >>> print fab.CTX None >>> >>> print fab.L_CTX # the in-memory address of 'fab' 2190784 >>> id (fab) 2190784 >>> >>> str = "CONTEXT-1" Python for OpenVMS -Reference Manual PAGE 3-4 vmsobj_fab object >>> fab.CTX = str >>> ctx_o = fab.CTX >>> >>> print ctx_o CONTEXT-1 >>> id (str) 2192128 >>> id (ctx_o) 2192128 >>> >>> fab.CTX = None >>> print fab.CTX None >>> print fab.L_CTX # as said, no change! 2190784 >>> >>> fab.CTX = 2 # other type are possible >>> ctx_o = fab.CTX >>> print type(ctx_o), ctx_o 2 >>> >>> fab.L_CTX = 1 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_fab attribute >>> DNA Read/write access for the 'default file specification string'. Input is a Python string object (limited to a maximum of 255 characters) or the 'None' object, returns the same string object (or None). The readonly attribute "L_DNA" returns the memory address of the string. The readonly attribute "B_DNS" returns the size of the string. >>> fab = pyvms.vmsobj_fab () >>> type (fab) >>> >>> t_dna = 'A.DAT' >>> fab.DNA = t_dna >>> str = fab.DNA >>> type (t_dna), id (t_dna) (, 2183816) >>> type (str), id (str) (, 2183816) >>> >>> fab.L_DNA 2183836 Python for OpenVMS -Reference Manual PAGE 3-5 vmsobj_fab object >>> fab.B_DNS 5 >>> >>> fab.DNA = None >>> fab.L_DNA 0 >>> fab.B_DNS 0 >>> >>> long_str = 's' * 256 >>> fab.DNA = long_str Traceback (innermost last): File "", line 1, in ? ValueError: string length limited to 255 characters >>> >>> fab.DNA = 0 Traceback (innermost last): File "", line 1, in ? TypeError: attribute must be string or None >>> >>> fab.L_DNA = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_fab attribute >>> FNA Read/write access for the 'file specification string'. Input is a Python string object (limited to a maximum of 255 characters) or the 'None' object, returns the same string object (or None). The readonly attribute "L_FNA" returns the memory address of the string. The readonly attribute "B_FNS" returns the size of the string. See the examples of the "DNA" attribute. NAM Read/write access for a vmsobj_nam object. The readonly attribute "L_NAM" returns the memory address of the OpenVMS NAM. >>> fab = pyvms.vmsobj_fab () >>> type (fab) >>> >>> print fab.NAM None >>> print fab.L_NAM 0 >>> >>> nam = pyvms.vmsobj_nam () >>> type (nam) Python for OpenVMS -Reference Manual PAGE 3-6 vmsobj_fab object >>> >>> >>> fab.NAM = nam >>> fab.NAM >>> hex (fab.L_NAM) '0x1ab0b0' >>> >>> >>> fab.NAM = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_nam object or None >>> >>> fab.L_NAM = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_fab attribute >>> XAB Read/write access for a vmsobj_xabXXX object. The readonly attribute "L_XAB" returns the memory address of the OpenVMS XAB that was connected to the FAB. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> fab = pyvms.vmsobj_fab () >>> type (fab) >>> >>> print fab.XAB None >>> print fab.L_XAB 0 >>> >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> >>> fab.XAB = xaball >>> fab.XAB >>> hex (fab.L_XAB) '0x21a330' >>> >>> >>> # remove XAB from FAB >>> fab.XAB = None >>> print fab.XAB Python for OpenVMS -Reference Manual PAGE 3-7 vmsobj_fab object None >>> print fab.L_XAB 0 >>> >>> fab.XAB = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> fab.L_XAB = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_fab attribute >>> ------------------------------------------------------------------------ Methods: mask_info It returns a tuple that contains information about the specified bit mask. Example: >>> import pyvms >>> fab = pyvms.vmsobj_fab() >>> fab.mask_info ('M_POS') ('L_FOP', 4, 5, 256) >>> fab.mask_info ('L_FOP') Traceback (most recent call last): File "", line 1, in ? ValueError: attribute 'L_FOP' is not a bit mask >>> The following information is returned: cell_name Name of the cell within the vmsobj_fab object where the bit is located. offset Byte-offset within the OpenVMS FAB. type Data type. 5 = ITMTYP_K_LONG. value 256 means that bit number 7 (counting from 0 upwards) is set. ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a Python for OpenVMS -Reference Manual PAGE 3-8 vmsobj_fab object vmsobj_fab object within Python. To date (10-FEB-1999) the following interface routines also pass a vmsobj_fab to their user-confirm routines: - vms_lib.delete_file() - vms_lib.rename_file() Examples: >>> import pyvms >>> # create a vmsobj_fab object >>> >>> fab = pyvms.vmsobj_fab () >>> type (fab) >>> fab >>> >>> # invalid attribute access >>> fab.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_fab attribute >>> fab.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 16-OCT-2000 ZE. 3.0.2 vmsobj_iosb object The vmsobj_iosb object is used to provide writeable(!) storage to OpenVMS system routines (like SYS$GETJPIW) that use an IOSB (I/O status block). This is necessary, because a regular Python object must not have its value changed. A programmer can create multiple, independend vmsobj_iosb objects and use them in parallel. ------------------------------------------------------------------------ Attributes: b0, b1, ... b7 Python for OpenVMS -Reference Manual PAGE 3-9 vmsobj_iosb object Read/write access to each byte within the IOSB. 'b0' is the first byte at the lowest address in memory. Data type is a Python integer. w0, w1, w2, w3 Read/write access to each word (16-bit value) within the IOSB. 'w0' is the first word at the lowest address in memory. Data type is a Python integer. l0, l1 Read/write access to each longword (32-bit value) within the IOSB. 'l0' is the first longword at the lowest address in memory. Data type is a Python integer. q Read/write access to the whole IOSB as a quadword (64-bit value). Data type is a Python long integer. b Read/write access to the whole IOSB as an 8-item tuple of bytes. Data type of each item is a Python integer. w Read/write access to the whole IOSB as a 4-item tuple of words. Data type of each item is a Python integer. l Read/write access to the whole IOSB as a 2-item tuple of longwords. Data type of each item is a Python integer. ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_iosb object within Python. Note that interface routines (e.g. vms_sys.getjpiw) can implicitly create a vmsobj_iosb object! The routine that allocates a new OpenVMS IOSB does automatically zero its contents. Examples: >>> import pyvms >>> # create a zero-filled iosb >>> >>> iosb = pyvms.vmsobj_iosb () >>> type (iosb) >>> iosb >>> >>> iosb.b0 0 >>> iosb.w1 0 >>> iosb.l1 0 >>> iosb.q Python for OpenVMS -Reference Manual PAGE 3-10 vmsobj_iosb object 0L >>> iosb.b (0, 0, 0, 0, 0, 0, 0, 0) >>> iosb.l (0, 0) >>> >>> iosb.b0 = 1 >>> iosb.w1 = 0x34 >>> iosb.l1 = 0xabcdef >>> >>> hex (iosb.b0) '0x1' >>> hex (iosb.b1) '0x0' >>> hex (iosb.b2) '0x34' >>> hex (iosb.b3) '0x0' >>> hex (iosb.b4) '0xef' >>> hex (iosb.b5) '0xcd' >>> hex (iosb.b6) '0xab' >>> hex (iosb.b7) '0x0' >>> hex (iosb.w0) '0x1' >>> hex (iosb.w1) '0x34' >>> hex (iosb.w2) '0xcdef' >>> hex (iosb.w3) '0xab' >>> hex (iosb.l0) '0x340001' >>> hex (iosb.l1) '0xabcdef' >>> hex (iosb.q ) '0xABCDEF00340001L' >>> >>> iosb.b (1, 0, 52, 0, 239, 205, 171, 0) >>> iosb.w (1, 52, 52719, 171) >>> iosb.l (3407873, 11259375) >>> iosb.q 48358647401807873L >>> Python for OpenVMS -Reference Manual PAGE 3-11 vmsobj_iosb object >>> iosb.b0 = 'X' Traceback (innermost last): File "", line 1, in ? TypeError: vms__cvt_py2bin(): data of item must be integer >>> >>> iosb.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_iosb attribute >>> >>> iosb.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 10-FEB-1999 ZE. 3.0.3 vmsobj_lksb object The vmsobj_lksb object is used to provide writeable(!) storage to OpenVMS system routines (like SYS$ENQW) that use an LKSB (LocK Status Block). This is necessary, because a regular Python object must not have its value changed. A programmer can create multiple, independend vmsobj_lksb objects and use them in parallel. ------------------------------------------------------------------------ Attributes: W_STATUS Read/write access to the first word (16-bit value) within the LKSB. This is also known as the 'condition value' field. Data type is a Python integer. W_RESERVED Readonly access to the second word within the LKSB. This field is reserved. Data type is a Python integer. L_LOCKID Read/write access to the second longword (32-bit value) within the LKSB. This is the identification of the lock. Data type is a Python integer. The first longword is divided into the W_STATUS and W_RESERVED fields. O_LVB Read/write access to the second quadword (64-bit value) within the LKSB. This is the lock value block. Data type is a Python long integer. The first quadword is divided into the W_STATUS, W_RESERVED and L_LOCKID fields. Python for OpenVMS -Reference Manual PAGE 3-12 vmsobj_lksb object ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_lksb object within Python. Note that interface routines (e.g. vms_sys.enqw) can implicitly create a vmsobj_lksb object! The routine that allocates a new OpenVMS LKSB does automatically zero its contents. @@@ Examples: >>> import pyvms >>> # create a zero-filled lksb >>> >>> lksb = pyvms.vmsobj_lksb () >>> type (lksb) >>> lksb >>> >>> lksb.b0 0 >>> lksb.w1 0 >>> lksb.l1 0 >>> lksb.q 0L >>> >>> lksb.b0 = 1 >>> lksb.w1 = 0x34 >>> lksb.l1 = 0xabcdef >>> >>> hex (lksb.w3) '0xab' >>> hex (lksb.l0) '0x340001' >>> hex (lksb.l1) '0xabcdef' >>> hex (lksb.q ) '0xABCDEF00340001L' >>> >>> lksb.b (1, 0, 52, 0, 239, 205, 171, 0) >>> lksb.w (1, 52, 52719, 171) >>> lksb.l (3407873, 11259375) Python for OpenVMS -Reference Manual PAGE 3-13 vmsobj_lksb object >>> lksb.q 48358647401807873L >>> >>> lksb.b0 = 'X' Traceback (innermost last): File "", line 1, in ? TypeError: vms__cvt_py2bin(): data of item must be integer >>> >>> lksb.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_lksb attribute >>> >>> lksb.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 29-MAY-1999 ZE. 3.0.4 vmsobj_nam object The vmsobj_nam object provides high-level access to an OpenVMS NAM (NAMe Block) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_NAM.C) nor will it explain the use of each field in a NAM. The 'vms_namdef' module contains bitmasks and constants that apply to an OpenVMS NAM. ------------------------------------------------------------------------ Attributes: Most BWL,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: DEV Readonly access to the device name from the "ESA" or "RSA" buffers. "B_DEV" returns the length and "L_DEV" returns the memory address of the string. W_DID The directory identification is read / written as a 3-item 16-bit integer tuple. Additional attributes to access part of the DID are available: "W_DID_NUM", "W_DID_SEQ", "W_DID_RVN", Python for OpenVMS -Reference Manual PAGE 3-14 vmsobj_nam object "B_DID_RVN", "B_DID_NMX". DIR Readonly access to the directory name from the "ESA" or "RSA" buffers. "B_DIR" returns the length and "L_DIR" returns the memory address of the string. DVI Readonly access to the device identification field in the OpenVMS NAM. Internally, this is an ASCIC field, but the interface routine returns a simple Python string without the length byte. ESA Read/write access to the expanded string area. The buffer space is hidden behind a 'vmsobj__membuf' object. On a read access the field NAM$B_ESL determines the returned string length, because this field is written by RMS. The field NAM$B_ESS is set, when a vmsobj__membuf object is assigned to the "ESA" attribute. "L_ESA" returns the memory address of the string buffer. "B_ESS" returns the buffer size and "B_ESL" returns the resulting string size as set by RMS. W_FID The file identification is read / written as a 3-item 16-bit integer tuple. Additional attributes to access part of the FID are available: "W_FID_NUM", "W_FID_SEQ", "W_FID_RVN", "B_FID_RVN", "B_FID_NMX". NAME Readonly access to the file name from "ESA" or "RSA" buffers. "B_NAME" returns the length and "L_NAME" returns the memory address of the string. NODE Readonly access to the node name from the "ESA" or "RSA" buffers. "B_NODE" returns the length and "L_NODE" returns the memory address of the string. RLF Related file processing is done with a second 'vmsobj_nam' object connected to this attribute. "L_RLF" returns the memory address of the next OpenVMS NAM. RSA Read/write access to the resultant string area. The buffer space is hidden behind a 'vmsobj__membuf' object. On a read access the field NAM$B_RSL determines the returned string length, because this field is written by RMS. The field NAM$B_RSS is set, when a 'vmsobj__membuf' object is Python for OpenVMS -Reference Manual PAGE 3-15 vmsobj_nam object assigned to the "RSA" attribute. "L_RSA" returns the memory address of the string buffer. "B_RSS" returns the buffer size and "B_RSL" returns the resulting string size as set by RMS. TYPE Readonly access to the file type from the "ESA" or "RSA" buffers. "B_TYPE" returns the length and "L_TYPE" returns the memory address of the string. VER Readonly access to the file version from the "ESA" or "RSA" buffers. "B_VER" returns the length and "L_VER" returns the memory address of the string. ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_nam object within Python. Examples: >>> import pyvms >>> # create a vmsobj_nam object >>> >>> nam = pyvms.vmsobj_nam () >>> type (nam) >>> nam >>> >>> # invalid attribute access >>> nam.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_nam attribute >>> nam.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 11-FEB-1999 ZE. Python for OpenVMS -Reference Manual PAGE 3-16 vmsobj_rab object 3.0.5 vmsobj_rab object The vmsobj_rab object provides high-level access to an OpenVMS RAB (Record Access Block) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_RAB.C) nor will it explain the use of each field in a RAB. The 'vms_rabdef' module contains bitmasks and constants that apply to an OpenVMS RAB. WARNING! Not all details of handling the I/O buffers have been worked out, yet. It is presently possible to crash Python with an OpenVMS access violation while using some interface routines. 10-JAN-2000: some missing reference count increments have been detected and fixed. -------- ------------------------------------------------------------------------ Attributes: Most BWL,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: CTX The user context (CTX) field can be used to pass information to a completion routine. This field is never used by RMS. Internally, the RAB$L_CTX field of the OpenVMS RAB contains the address of the 'vmsobj_rab' object. This cannot be overwritten. The 'vmsobj_rab' object provides a "CTX" attribute which allows the programme to associate a Python object with it. If no object was ever assigned to the "CTX" attribute, then a read access will return the 'None' object. You can assign the 'None' object to "CTX", but this will not put a 0 value into "L_CTX" unlike some other attributes - see the examples below. >>> rab = pyvms.vmsobj_rab () >>> type (rab) >>> >>> print rab.CTX None >>> >>> print rab.L_CTX # the in-memory address of 'rab' Python for OpenVMS -Reference Manual PAGE 3-17 vmsobj_rab object 2190784 >>> id (rab) 2190784 >>> >>> str = "CONTEXT-1" >>> rab.CTX = str >>> ctx_o = rab.CTX >>> >>> print ctx_o CONTEXT-1 >>> id (str) 2192144 >>> id (ctx_o) 2192144 >>> >>> rab.CTX = None >>> print rab.CTX None >>> print rab.L_CTX # as said, no change! 2190784 >>> >>> rab.CTX = 2 # other type are possible >>> ctx_o = rab.CTX >>> print type(ctx_o), ctx_o 2 >>> >>> rab.L_CTX = 1 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_rab attribute >>> FAB Read/write access for a 'vmsobj_fab' object. The readonly attribute "L_FAB" returns the memory address of the OpenVMS FAB. >>> rab = pyvms.vmsobj_rab () >>> type (rab) >>> >>> fab = pyvms.vmsobj_fab () >>> type (fab) >>> rab.FAB = fab >>> f2 = rab.FAB >>> fab Python for OpenVMS -Reference Manual PAGE 3-18 vmsobj_rab object >>> f2 >>> >>> rab.L_FAB 1759736 >>> hex(rab.L_FAB) '0x1ad9f8' >>> >>> >>> # remove FAB from RAB >>> rab.FAB = None >>> print rab.FAB None >>> print rab.L_FAB 0 >>> >>> rab.L_FAB = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_rab attribute >>> >>> rab.FAB = 'X' Traceback (innermost last): File "", line 1, in ? TypeError: FAB attribute - must be vmsobj_fab object or None >>> >>> # remove FAB from RAB >>> rab.FAB = None >>> rab.L_FAB 0 >>> KBF key buffer It accepts and returns a string object (or None) and will store the address and the string length directly in the OpenVMS RAB. The readonly attributes "L_KBF" and "B_KSZ" return the memory address and length of the real buffer. Note that the key buffer (KBF) and the prompt buffer (PBF) share the same RAB addresses. >>> rab.KBF = 'key' >>> rab.KBF 'key' >>> rab.L_KBF 1988708 >>> rab.B_KSZ 3 >>> rab.PBF Python for OpenVMS -Reference Manual PAGE 3-19 vmsobj_rab object 'key' >>> rab.PBF = None >>> print rab.KBF None >>> rab.L_KBF 0 >>> rab.B_KSZ 0 >>> >>> rab.B_KSZ = 1 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_rab attribute >>> PBF prompt buffer It accepts and returns a string object (or None) and will store the address and the string length directly in the OpenVMS RAB. The readonly attributes "L_PBF" and "B_PSZ" return the memory address and length of the real buffer. Note that the prompt buffer (PBF) and the key buffer (KBF) share the same RAB addresses. See the examples of the "KBF" attribute. RBF record buffer RMS functions can write to the RBF - this prohibits use of a string object, because Python strings are immutable objects! The buffer space is hidden behind a 'vmsobj__membuf' object. There are several ways to 'attach' the vmsobj__membuf object to the "RBF" attribute: * Create the 'vmsobj__membuf' object via a function in the 'pyvms' module and assign it to "RBF": >>> # one way - specify its length >>> membuf = pyvms.vmsobj__membuf (5) >>> rab.RBF = membuf >>> membuf >>> rab.RBF >>> Python for OpenVMS -Reference Manual PAGE 3-20 vmsobj_rab object * Assign a Python string to the "RBF" attribute. The interface routine will automatically create a 'vmsobj__membuf' object and copy the data from the string into the buffer: >>> rab.RBF = 'data' >>> rab.RBF >>> membuf = rab.RBF >>> membuf >>> membuf.buffer 'data' >>> Finally, the 'None' object can be assigned to the "RBF" attribute. This will 'disconnect' the vmsobj__membuf object from the RAB. If there are no more references to the object, the buffer and its describing object will automatically be deallocated. The readonly attributes "L_RBF" and "W_RSZ" return the memory address and length from the OpenVMS RAB. W_RFA Is represented as a 3-item tuple of 16-bit integers. UBF user buffer @@ The buffer space is hidden behind a 'vmsobj__membuf' object. "..." The readonly attributes "L_UBF" and "W_USZ" return the memory address and length from the OpenVMS RAB. XAB RAB$L_XAB only accepts a XABTRM and a XABRU (on OpenVMS VAX V6.1 and perhaps later versions of OpenVMS Alpha). The XABRU (used for RMS journaling) has not been implemented. The readonly attribute "L_XAB" returns the memory address of the OpenVMS XAB. ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a 'vmsobj_rab' object within Python. Examples: Python for OpenVMS -Reference Manual PAGE 3-21 vmsobj_rab object >>> import pyvms >>> # create a vmsobj_rab object >>> >>> rab = pyvms.vmsobj_rab () >>> type (rab) >>> rab >>> >>> # invalid attribute access >>> rab.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_rab attribute >>> rab.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 12-JUN-2000 ZE. 3.0.6 vmsobj_xaball object The vmsobj_xaball object provides high-level access to an OpenVMS XABALL (ALLocation XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABALL.C) nor will it explain the use of each field in a XABALL. The 'vms_xaballdef' module contains constants and bitmasks that apply to an OpenVMS XABALL. ------------------------------------------------------------------------ Attributes: Most BWL,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: W_RFI The Related File Identifier is read / written as a 3-item tuple of 16-bit integers. Individual access to each 16-bit value is possible via the attributes "W_RFI0", "W_RFI2" and "W_RFI4". Python for OpenVMS -Reference Manual PAGE 3-22 vmsobj_xaball object NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABALL. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> print xaball.NXT None >>> print xaball.L_NXT 0 >>> >>> # this example uses a XABDAT >>> xabdat = pyvms.vmsobj_xabdat () >>> type (xabdat) >>> >>> >>> xaball.NXT = xabdat >>> xabdat >>> xaball.NXT >>> hex (xaball.L_NXT) '0x1ea898' >>> >>> >>> xaball.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xaball.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xaball attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xaball object within Python. Examples: >>> import pyvms Python for OpenVMS -Reference Manual PAGE 3-23 vmsobj_xaball object >>> # create a vmsobj_xaball object >>> >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> xaball >>> >>> # invalid attribute access >>> xaball.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xaball attribute >>> xaball.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 13-FEB-1999 ZE. 3.0.7 vmsobj_xabdat object The vmsobj_xabdat object provides high-level access to an OpenVMS XABDAT (DAte and Time XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABDAT.C) nor will it explain the use of each field in a XABDAT. A 'vmsobj_xabdat' object does not have any bitmasks or constants which means there is no 'vms_xabdatdef' module. ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Attributes with a 'Q' (quadword - 64-bit datatype) are returned as a signed 'Python long integer'. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Exceptions are noted below: NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the Python for OpenVMS -Reference Manual PAGE 3-24 vmsobj_xabdat object OpenVMS XAB that was connected to the XABDAT. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xabdat = pyvms.vmsobj_xabdat () >>> type (xabdat) >>> >>> print xabdat.NXT None >>> print xabdat.L_NXT 0 >>> >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> >>> xabdat.NXT = xaball >>> xaball >>> xabdat.NXT >>> hex (xabdat.L_NXT) '0x21a368' >>> >>> >>> xabdat.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabdat.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabdat attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabdat object within Python. Examples: >>> import pyvms >>> # create a vmsobj_xabdat object >>> >>> xabdat = pyvms.vmsobj_xabdat () Python for OpenVMS -Reference Manual PAGE 3-25 vmsobj_xabdat object >>> type (xabdat) >>> xabdat >>> >>> # invalid attribute access >>> xabdat.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabdat attribute >>> xabdat.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> ------------------------------------------------------------------------ Use: >>> import pyvms >>> >>> fab = pyvms.vmsobj_fab() >>> fab.FNA = 'cc_python.com' >>> >>> xabdat = pyvms.vmsobj_xabdat() >>> fab.XAB = xabdat >>> import vms_sys >>> >>> status = vms_sys.open (fab) >>> print status 65537 >>> vms_sys.getmsg (status) ('%RMS-S-NORMAL, normal successful completion', (0, 0, 0, 0)) >>> >>> vms_sys.asctim (xabdat.Q_CDT) '14-MAR-1999 20:01:59.92' >>> vms_sys.asctim (xabdat.Q_RDT) '14-MAR-1999 20:02:00.29' >>> .. @@ ------------------------------------------------------------------------ 23-MAR-1999 ZE. 3.0.8 vmsobj_xabfhc object The vmsobj_xabfhc object provides high-level access to an OpenVMS XABFHC (File cHaracteristiC XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will Python for OpenVMS -Reference Manual PAGE 3-26 vmsobj_xabfhc object neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABFHC.C) nor will it explain the use of each field in a XABFHC. The 'vms_xabfhcdef' module contains constants and bitmasks that apply to an OpenVMS XABFHC. ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABFHC. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xabfhc = pyvms.vmsobj_xabfhc () >>> type (xabfhc) >>> >>> print xabfhc.NXT None >>> print xabfhc.L_NXT 0 >>> >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> >>> xabfhc.NXT = xaball >>> xaball >>> xabfhc.NXT >>> hex (xabfhc.L_NXT) '0x21db98' >>> >>> >>> xabfhc.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabfhc.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabfhc attribute Python for OpenVMS -Reference Manual PAGE 3-27 vmsobj_xabfhc object >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabfhc object within Python. Examples: >>> import pyvms >>> # create a vmsobj_xabfhc object >>> >>> xabfhc = pyvms.vmsobj_xabfhc () >>> type (xabfhc) >>> xabfhc >>> >>> # invalid attribute access >>> xabfhc.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabfhc attribute >>> xabfhc.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 14-FEB-1999 ZE. 3.0.9 vmsobj_xabitm object The vmsobj_xabitm object provides high-level access to an OpenVMS XABITM (ITeM list XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABITM.C) nor will it explain the use of each field in a XABITM. The 'vms_xabitmdef' module contains item codes, constants and bitmasks that apply to an OpenVMS XABITM. Python for OpenVMS -Reference Manual PAGE 3-28 vmsobj_xabitm object ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: ITEMLIST Read/write access for an OpenVMS item list. When an item list (see example below) is assigned to the "ITEMLIST", an in-memory OpenVMS itemlist is build and its address is stored in "L_ITEMLIST", which can only be read(!) from the Python interface. If an invalid item list is passed and the interface detects an errors, then a Python exception is raised and an existing old item list is left intact. If 'None' is assigned, then the in-memory OpenVMS itemlist is freed from memory and a 0 value is stored in "L_ITEMLIST". It is possible to 'query' the item list, even if no RMS call has been invoked. The interface routine will just return the output items with their current data in a dictionary - see example below. The following items (as defined in OpenVMS VAX V6.1) are not available: * XAB$_STORED_SEMANTICS * XAB$_ACCESS_SEMANTICS * XAB$_RUJVOLNAM * XAB$_TID >>> xabitm = pyvms.vmsobj_xabitm () >>> >>> item_list = \ ... ( ... ('XAB$_NET_BLOCK_COUNT',4), # in + output ... ('XAB$_NET_BUFFER_SIZE') # output ... ) >>> >>> xabitm.ITEMLIST = item_list >>> >>> dict = xabitm.ITEMLIST >>> for key in dict.keys(): ... print key, dict.get(key) ... XAB$_NET_BLOCK_COUNT 4 XAB$_NET_BUFFER_SIZE 0 <-- default value for output item >>> >>> print hex(xabitm.L_ITEMLIST) 0x2227b0 >>> Python for OpenVMS -Reference Manual PAGE 3-29 vmsobj_xabitm object >>> >>> item_list = \ ... ( ... ('XAB$_NET_BLOCK_COUNT','BAD'), ... ('XAB$_NET_BUFFER_SIZE',) ... ) >>> >>> xabitm.ITEMLIST = item_list Traceback (innermost last): File "", line 1, in ? TypeError: vms__cvt_py2bin(): data of item must be integer >>> >>> print hex(xabitm.L_ITEMLIST) 0x2227b0 >>> # -> same item-list >>> xabitm.ITEMLIST = None >>> print hex(xabitm.L_ITEMLIST) 0x0 >>> # -> item list removed from XABITM >>> >>> xabitm.ITEMLIST = 0 Traceback (innermost last): File "", line 1, in ? TypeError: itemlist must be a tuple of strings, \ tuples (string,data) or None >>> >>> xabitm.L_ITEMLIST = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabitm attribute >>> NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABITM. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xabitm = pyvms.vmsobj_xabitm () >>> type (xabitm) >>> >>> print xabitm.NXT None >>> print xabitm.L_NXT 0 >>> Python for OpenVMS -Reference Manual PAGE 3-30 vmsobj_xabitm object >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> >>> xabitm.NXT = xaball >>> xaball >>> xabitm.NXT >>> hex (xabitm.L_NXT) '0x2210c8' >>> >>> >>> xabitm.NXT = None >>> xabitm.L_NXT 0 >>> >>> xabitm.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabitm.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabitm attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabitm object within Python. Examples: >>> import pyvms >>> # create a vmsobj_xabitm object >>> >>> xabitm = pyvms.vmsobj_xabitm () >>> type (xabitm) >>> xabitm >>> >>> # invalid attribute access >>> xabitm.no_attr = 0 Python for OpenVMS -Reference Manual PAGE 3-31 vmsobj_xabitm object Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabitm attribute >>> xabitm.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> ------------------------------------------------------------------------ Use: $ create /directory [.DIRTST.YES] $ copy _NLA0: [.DIRTST]NO.DIR;1 $ python >>> import pyvms >>> import vms_lib, vms_sys >>> import vms_xabitmdef >>> >>> def is_dir (filespec): ... # ... fab = pyvms.vmsobj_fab () ... fab.FNA = filespec ... # ... xabitm = pyvms.vmsobj_xabitm () ... # ... # Note trailing comma, because this is a tuple of tuples ! ... item_list = ('XAB$_UCHAR_DIRECTORY',0), ... xabitm.ITEMLIST = item_list ... # ... xabitm.B_MODE = vms_xabitmdef.XAB_K_SENSEMODE ... # ... fab.XAB = xabitm ... # ... status = vms_sys.open (fab) ... # print status ... # print vms_sys.getmsg (status) ... # ... # Get sensed information from itemlist. ... dict = xabitm.ITEMLIST ... # ... status = vms_sys.close (fab) ... # print status ... # print vms_sys.getmsg (status) ... # ... return dict.get ('XAB$_UCHAR_DIRECTORY') ... >>> >>> context = 0 >>> status = 1 >>> while (status & 1): ... status, status_value, context, resultant_filespec = \ Python for OpenVMS -Reference Manual PAGE 3-32 vmsobj_xabitm object ... vms_lib.find_file ('[.DIRTST]*.DIR;*', context, \ ... None, None, 0) # 0 = allow wildcards ... if (status & 1): ... print resultant_filespec ... print ' is', ... if (not is_dir (resultant_filespec)): ... print 'not', ... print 'a directory' ... else: ... print vms_sys.getmsg (status) ... break # reached end ... DKA100:[PYTHON.PYTHON-1_5_1.VMS.DIRTST]NO.DIR;1 is not a directory DKA100:[PYTHON.PYTHON-1_5_1.VMS.DIRTST]YES.DIR;1 is a directory ('%RMS-E-NMF, no more files found', (0, 0, 0, 0)) >>> .. @@ ------------------------------------------------------------------------ 26-MAR-1999 ZE. 3.0.10 vmsobj_xabkey object The vmsobj_xabkey object provides high-level access to an OpenVMS XABKEY (KEY XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABKEY.C) nor will it explain the use of each field in a XABKEY. The 'vms_xabkeydef' module contains constants and bitmasks that apply to an OpenVMS XABKEY. ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: Attributes dealing with collating sequences are not available. "L_COLNAM", "L_COLSIZ" and "L_COLTBL" are readonly. KNM Read/write access for the KeyNaMe attribute - maximum string length is 15 characters. The string is internally copied to a separate area that builds a counted ASCII (ASCIC) string. The readonly attribute "L_KNM" returns the memory address of the OpenVMS ASCIC that describes this string. Python for OpenVMS -Reference Manual PAGE 3-33 vmsobj_xabkey object >>> xabkey = pyvms.vmsobj_xabkey () >>> type (xabkey) >>> >>> keyname = 'Key-1' >>> xabkey.KNM = keyname >>> >>> xabkey.L_KNM 1991364 >>> xab_knm = xabkey.KNM >>> keyname, xab_knm ('Key-1', 'Key-1') >>> print id (keyname), id (xab_knm) 2233912 2233704 >>> # -> different ids indicate different string objects >>> xabkey.KNM = None >>> xab_knm = xabkey.KNM >>> xab_knm '' >>> # -> a string is always returned >>> xabkey.L_KNM 0 >>> >>> xabkey.KNM = 0 Traceback (innermost last): File "", line 1, in ? TypeError: attribute must be string or None >>> >>> xabkey.L_KNM = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabkey attribute >>> NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABKEY. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xabkey = pyvms.vmsobj_xabkey () >>> type (xabkey) >>> Python for OpenVMS -Reference Manual PAGE 3-34 vmsobj_xabkey object >>> print xabkey.NXT None >>> print xabkey.L_NXT 0 >>> >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> xabkey.NXT = xaball >>> xaball >>> xabkey.NXT >>> hex (xabkey.L_NXT) '0x221568' >>> >>> xabkey.NXT = None >>> print xabkey.NXT None >>> xabkey.L_NXT 0 >>> >>> xabkey.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabkey.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabkey attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabkey object within Python. Examples: >>> import pyvms >>> # create a vmsobj_xabkey object Python for OpenVMS -Reference Manual PAGE 3-35 vmsobj_xabkey object >>> >>> xabkey = pyvms.vmsobj_xabkey () >>> type (xabkey) >>> xabkey >>> >>> # invalid attribute access >>> xabkey.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabkey attribute >>> xabkey.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 25-FEB-1999 ZE. 3.0.11 vmsobj_xabpro object The vmsobj_xabpro object provides high-level access to an OpenVMS XABPRO (PROtection XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABPRO.C) nor will it explain the use of each field in a XABPRO. The 'vms_xabprodef' module contains constants and bitmasks that apply to an OpenVMS XABPRO. ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: ACLBUF Read/write access to the ACL BUFfer. The programmer MUST provide a buffer! Input can be a Python string or a vmsobj___membuf object. As strings are immutable, their data is internally copied to a vmsobj___membuf object. However, you must NOT provide a buffer that is bigger than 512 bytes or the read operation will fail with an SS$_BADATTR@@ Python for OpenVMS -Reference Manual PAGE 3-36 vmsobj_xabpro object error in FAB$L_STV. The ACP-QIO interface (ATR$C_READACL) that RMS uses is limited to this amount. The XQP will read as much data as will fit into the buffer, however only complete ACEs will be stored, so "xabpro.W_ACLLEN" will very likely be smaller than "xabpro.W_ACLSIZ" after reading ACEs. This is shown in the examples section of vms_sys.format_acl(). If you want to fetch an ACL that is bigger than 512 bytes, you should instead make a call to vms_sys.get_security(). See the example 'get the entire ACL' A read operation from this attribute gives a new Python string. Note that ACLs contain binary information - use something like 'print repr(aclstr)' to display its contents. L_ACLBUF Read-only access to the memory address of the ACL BUFfer. W_ACLLEN Read-only access to the ACL length. After an assignment operation to the "ACLBUF" attribute this value is the same as "W_ACLSIZ", however "W_ACLLEN" is overwritten by a RMS Open or Display function. W_ACLSIZ Read-only access to the buffer size. This is valid for an assignment operation to the "ACLBUF" attribute. L_ACLCTX Read/write access to the ACL context field that is used for ACE (Access Control list Entry) processing. This field is set to 0 for an assignment operation to the "ACLBUF" attribute! MTACC Read/write access to "XAB$B_MTACC" using single character I/O. NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABPRO. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xabpro = pyvms.vmsobj_xabpro () >>> type (xabpro) >>> >>> print xabpro.NXT None >>> print xabpro.L_NXT 0 >>> >>> # this example uses a XABALL Python for OpenVMS -Reference Manual PAGE 3-37 vmsobj_xabpro object >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> xabpro.NXT = xaball >>> xaball >>> xabpro.NXT >>> hex (xabpro.L_NXT) '0x221568' >>> >>> xabpro.NXT = None >>> print xabpro.NXT None >>> xabpro.L_NXT 0 >>> >>> xabpro.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabpro.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabpro attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabpro object within Python. Examples: >>> import pyvms >>> # create a vmsobj_xabpro object >>> >>> xabpro = pyvms.vmsobj_xabpro () >>> type (xabpro) >>> xabpro Python for OpenVMS -Reference Manual PAGE 3-38 vmsobj_xabpro object >>> >>> # invalid attribute access >>> xabpro.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabpro attribute >>> xabpro.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 12-JUN-2000 ZE. 3.0.12 vmsobj_xabrdt object The vmsobj_xabrdt object provides high-level access to an OpenVMS XABRDT (Revision Date+Time XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABRDT.C) nor will it explain the use of each field in a XABRDT. A 'vmsobj_xabrdt' object does not have any bitmasks or constants which means there is no 'vms_xabrdtdef' module. ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Attributes with a 'Q' (quadword - 64-bit datatype) are returned as a signed 'Python long integer'. See GENMAN 'Programming', 'special OpenVMS datatypes' for details. Exceptions are noted below: NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABRDT. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. >>> xabrdt = pyvms.vmsobj_xabrdt () >>> type (xabrdt) Python for OpenVMS -Reference Manual PAGE 3-39 vmsobj_xabrdt object >>> >>> print xabrdt.NXT None >>> print xabrdt.L_NXT 0 >>> >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> xabrdt.NXT = xaball >>> xaball >>> xabrdt.NXT >>> hex (xabrdt.L_NXT) '0x221568' >>> >>> xabrdt.NXT = None >>> print xabrdt.NXT None >>> xabrdt.L_NXT 0 >>> >>> xabrdt.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabrdt.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabrdt attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabrdt object within Python. Examples: >>> import pyvms Python for OpenVMS -Reference Manual PAGE 3-40 vmsobj_xabrdt object >>> # create a vmsobj_xabrdt object >>> >>> xabrdt = pyvms.vmsobj_xabrdt () >>> type (xabrdt) >>> xabrdt >>> >>> # invalid attribute access >>> xabrdt.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabrdt attribute >>> xabrdt.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 08-MAR-1999 ZE. 3.0.13 vmsobj_xabsum object The vmsobj_xabsum object provides high-level access to an OpenVMS XABSUM (SUMmary XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The Python for OpenVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABSUM.C) nor will it explain the use of each field in a XABSUM. A 'vmsobj_xabsum' object does not have any bitmasks or constants which means there is no 'vms_xabsumdef' module. ------------------------------------------------------------------------ Attributes: Most BWLQ,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below: NXT Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABSUM. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs. Python for OpenVMS -Reference Manual PAGE 3-41 vmsobj_xabsum object >>> xabsum = pyvms.vmsobj_xabsum () >>> type (xabsum) >>> >>> print xabsum.NXT None >>> print xabsum.L_NXT 0 >>> >>> # this example uses a XABALL >>> xaball = pyvms.vmsobj_xaball () >>> type (xaball) >>> >>> xabsum.NXT = xaball >>> xaball >>> xabsum.NXT >>> hex (xabsum.L_NXT) '0x221568' >>> >>> xabsum.NXT = None >>> print xabsum.NXT None >>> xabsum.L_NXT 0 >>> >>> xabsum.NXT = 0 Traceback (innermost last): File "", line 1, in ? TypeError: must be a vmsobj_xabXXX object or None >>> >>> xabsum.L_NXT = 2 Traceback (innermost last): File "", line 1, in ? AttributeError: read-only vmsobj_xabsum attribute >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabsum object within Python. Examples: Python for OpenVMS -Reference Manual PAGE 3-42 vmsobj_xabsum object >>> import pyvms >>> # create a vmsobj_xabsum object >>> >>> xabsum = pyvms.vmsobj_xabsum () >>> type (xabsum) >>> xabsum >>> >>> # invalid attribute access >>> xabsum.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj_xabsum attribute >>> xabsum.no_attr Traceback (innermost last): File "", line 1, in ? AttributeError: no_attr >>> .. @@ ------------------------------------------------------------------------ 08-MAR-1999 ZE. 3.0.14 vmsobj__access_names object The vmsobj__access_names object provides high-level access to an OpenVMS 'access name table'. The current (28-JUN-1999) implementation only stores the address of a table. It must be passed to the internal object creation routine - there is no way to create and maintain it from the Python interpreter. The following routines create an object: - vms_lib.get_accnam() - vms_lib.get_accnam_by_context() - vms_sys.get_security() The following routines accept this object: Python for OpenVMS -Reference Manual PAGE 3-43 vmsobj__access_names object - vms_sys.format_acl() - vms_sys.parse_acl() Some simple sequence methods are implemented: >>> import vms_lib >>> >>> accnam = vms_lib.get_accnam () >>> >>> print len(accnam) 32 >>> # Python changes this internally to 31 >>> print accnam [-1] None >>> print accnam [0] READ >>> # Python changes this internally to 0 >>> print accnam [-32] READ >>> >>> print accnam [2] EXECUTE >>> accnam [2] = 'E_X_E_C_U_T_E' >>> print accnam [2] E_X_E_C_U_T_E >>> >>> long_string = '*' * 65536 >>> accnam [2] = long_string Traceback (innermost last): File "", line 1, in ? ValueError: string length limited to 65535 characters >>> >>> accnam [2] = 1 Traceback (innermost last): File "", line 1, in ? TypeError: must be a string or None >>> >>> print accnam [3] DELETE >>> accnam [3] = None >>> print accnam [3] None >>> print accnam [4] CONTROL >>> del (accnam [4]) >>> print accnam [4] None >>> >>> print accnam [30] None Python for OpenVMS -Reference Manual PAGE 3-44 vmsobj__access_names object >>> print accnam [31] None >>> print accnam [32] Traceback (innermost last): File "", line 1, in ? IndexError: index out of range >>> 'None' means that the descriptor is empty - DSC$W_LENGTH is 0. >>> accnam = vms_lib.get_accnam () >>> print accnam [0:3] ['READ', 'WRITE', 'EXECUTE'] >>> >>> print accnam [2:6] ['EXECUTE', 'DELETE', 'CONTROL', None] >>> >>> # some methods are still missing: >>> accnam [1:3] = ['X','Y','Z'] Traceback (innermost last): File "", line 1, in ? ValueError: accnam_ass_slice: remaining code not implemented >>> .. @@ ------------------------------------------------------------------------ 11-AUG-1999 ZE. 3.0.15 vmsobj__floating_f object The vmsobj__floating_f object provides storage and conversion routines to / from a VAX F_Floating point numbers. as_python_float Tries to convert the bit pattern to a Python float. This can fail if the bit pattern is invalid for a VAX F_Floating. as_python_long Returns the bit pattern to a Python long integer. from_python_float Tries to convert the Python float to a VAX F_Floating value. If that succeeds, the bit pattern is stored in the object. This can fail if the Python float is out of the range of a VAX F_Floating. from_python_long Python for OpenVMS -Reference Manual PAGE 3-45 vmsobj__floating_f object Stores the bit pattern in the object. The patterns are not validated - you might store an invalid one in the object that cannot converted to a(ny) different floating point format. @@ documentation not yet fully available ... @@ ------------------------------------------------------------------------ 16-APR-2001 ZE. 3.0.16 vmsobj__membuf object The vmsobj__membuf object is used to provide writeable(!) storage to other vmsobj objects (e. g. a RAB). This is necessary, because Python string objects are immutable (their contents must not be changed). ------------------------------------------------------------------------ Attributes: buffer Returns the contents of the buffer as a Python string object. WARNING! The buffer can contain control characters (including 0). You should use the 'repr()' builtin to inspect the contents of the buffer. Otherwise control characters in the buffer might render your terminal inoperable. It is (currently) not possible to store new data into the buffer with the setattr mechanism (you cannot do 'membuf.buffer = data'). size Returns the size of the buffer in bytes. It is not possible (and will not be) to resize the buffer by assigning a new value to the 'size' attribute. The reason is that the buffer address and its length is very likely used by/ stored inside another object (e. g. vmsobj_rab). ------------------------------------------------------------------------ Methods: zero Immediately overwrites the contents of the buffer with 0. Any arguments to zero() are ignored. >>> # create a new object with pre-defined content >>> membuf = pyvms.vmsobj__membuf ('abc123') >>> # show contents >>> print repr(membuf.buffer) 'abc123' >>> # overwrite contents >>> membuf.zero() Python for OpenVMS -Reference Manual PAGE 3-46 vmsobj__membuf object >>> # show updated contents >>> print repr(membuf.buffer) '\000\000\000\000\000\000' >>> >>> # any arguments are simply ignored >>> membuf.zero('XYZ', 123) >>> >>> print membuf.zero.__doc__ None = vmsobj__membuf.zero() Overwrite contents of buffer with NULs. >>> ------------------------------------------------------------------------ Creation: For now the 'pyvms' module contains a function to explicitly create a vmsobj__membuf object within Python. Note that other objects - e. g. vmsobj_rab - can implicitly create a vmsobj__membuf object! See the description of its "RBF" and "UBF" attributes. Examples: >>> import pyvms >>> # create a zero-filled buffer >>> >>> membuf = pyvms.vmsobj__membuf (5) >>> type (membuf) >>> membuf >>> membuf.size 5 >>> print repr(membuf.buffer) '\000\000\000\000\000' >>> >>> # create a string-filled buffer >>> >>> membuf = pyvms.vmsobj__membuf ('data') >>> type (membuf) >>> membuf >>> membuf.size 4 >>> print repr(membuf.buffer) 'data' >>> Python for OpenVMS -Reference Manual PAGE 3-47 vmsobj__membuf object >>> # invalid attribute access >>> membuf.bad_attr Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing vmsobj__membuf attribute >>> >>> membuf.size = 9 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing or readonly vmsobj__membuf attribute >>> membuf.buffer = 'x' Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing or readonly vmsobj__membuf attribute >>> membuf.no_attr = 0 Traceback (innermost last): File "", line 1, in ? AttributeError: non-existing or readonly vmsobj__membuf attribute >>> .. @@ ------------------------------------------------------------------------ 12-JUN-2000 ZE. 3.0.17 vmsobj__ownership_names object The vmsobj__ownership_names object provides high-level ownership to an OpenVMS 'ownership name table'. The following routine accepts this object: - vms_lib.format_sogw_prot() Some simple sequence methods are implemented: >>> import pyvms >>> >>> ownnam = pyvms.vmsobj__ownership_names () >>> >>> print len(ownnam) 4 >>> # Python changes this internally to 3 >>> print ownnam [-1] WORLD >>> print ownnam [0] SYSTEM >>> # Python changes this internally to 0 >>> print ownnam [-4] SYSTEM >>> Python for OpenVMS -Reference Manual PAGE 3-48 vmsobj__ownership_names object >>> print ownnam [2] GROUP >>> ownnam [2] = 'G_R_O_U_P' >>> print ownnam [2] G_R_O_U_P >>> >>> long_string = '*' * 65536 >>> ownnam [2] = long_string Traceback (innermost last): File "", line 1, in ? ValueError: string length limited to 65535 characters >>> >>> ownnam [2] = 1 Traceback (innermost last): File "", line 1, in ? TypeError: must be a string or None >>> >>> print ownnam [3] WORLD >>> ownnam [3] = None >>> print ownnam [3] None >>> print ownnam [2] G_R_O_U_P >>> del (ownnam [2]) >>> print ownnam [2] None >>> >>> print ownnam [10] Traceback (innermost last): File "", line 1, in ? IndexError: index out of range >>> 'None' means that the descriptor is empty - DSC$W_LENGTH is 0. >>> ownnam = pyvms.vmsobj__ownership_names () >>> print ownnam [0:2] ['SYSTEM', 'OWNER'] >>> >>> print ownnam [1:6] ['OWNER', 'GROUP', 'WORLD'] >>> >>> # some methods are still missing: >>> ownnam [1:3] = ['X','Y','Z'] Traceback (innermost last): Python for OpenVMS -Reference Manual PAGE 3-49 vmsobj__ownership_names object File "", line 1, in ? ValueError: ownnam_ass_slice: remaining code not implemented >>> .. @@ ------------------------------------------------------------------------ 12-AUG-1999 ZE. Index PAGE INDEX-1 INDEX files VMSDEF_$RABDEF.MAR, 2-514 PYVMS_READLINE.C, 2-123 VMSDEF_$RSDMDEF.DAT, 2-515 VMSDEF_$BRKDEF.DAT, 2-506 VMSDEF_$RSDMDEF.MAR, 2-515 VMSDEF_$BRKDEF.MAR, 2-506 VMSDEF_$SJCDEF.DAT, 2-515 VMSDEF_$CIADEF.DAT, 2-506 VMSDEF_$SJCDEF.MAR, 2-515 VMSDEF_$CIADEF.MAR, 2-506 VMSDEF_$SMGDEF.DAT, 2-515 VMSDEF_$DCDEF.DAT, 2-507 VMSDEF_$SMGDEF.MAR, 2-515 VMSDEF_$DCDEF.MAR, 2-507 VMSDEF_$STATEDEF.DAT, 2-516 VMSDEF_$DMTDEF.DAT, 2-507 VMSDEF_$STATEDEF.MAR, 2-516 VMSDEF_$DMTDEF.MAR, 2-507 VMSDEF_$SYIDEF.DAT, 2-516 VMSDEF_$DVIDEF.DAT, 2-508 VMSDEF_$SYIDEF.MAR, 2-516 VMSDEF_$DVIDEF.MAR, 2-508 VMSDEF_$TRMDEF.DAT, 2-516 VMSDEF_$DVSDEF.DAT, 2-508 VMSDEF_$TRMDEF.MAR, 2-516 VMSDEF_$DVSDEF.MAR, 2-508 VMSDEF_$UAIDEF.DAT, 2-517 VMSDEF_$FABDEF.DAT, 2-508 VMSDEF_$UAIDEF.MAR, 2-517 VMSDEF_$FABDEF.MAR, 2-508 VMSDEF_$XABALLDEF.DAT, 2-517 VMSDEF_$FSCNDEF.DAT, 2-509 VMSDEF_$XABALLDEF.MAR, 2-517 VMSDEF_$FSCNDEF.MAR, 2-509 VMSDEF_$XABFHCDEF.DAT, 2-518 VMSDEF_$INITDEF.DAT, 2-509 VMSDEF_$XABFHCDEF.MAR, 2-518 VMSDEF_$INITDEF.MAR, 2-509 VMSDEF_$XABITMDEF.DAT, 2-518 VMSDEF_$JPIDEF.DAT, 2-509 VMSDEF_$XABITMDEF.MAR, 2-518 VMSDEF_$JPIDEF.MAR, 2-509 VMSDEF_$XABKEYDEF.DAT, 2-518 VMSDEF_$KGBDEF.DAT, 2-510 VMSDEF_$XABKEYDEF.MAR, 2-518 VMSDEF_$KGBDEF.MAR, 2-510 VMSDEF_$XABPRODEF.DAT, 2-519 VMSDEF_$LBRDEF.DAT, 2-510 VMSDEF_$XABPRODEF.MAR, 2-519 VMSDEF_$LBRDEF.MAR, 2-510 VMSDEF_$LCKDEF.DAT, 2-511 logical names VMSDEF_$LCKDEF.MAR, 2-511 creation, 2-112, 2-336 VMSDEF_$LNMDEF.DAT, 2-511 deletion, 2-55, 2-351 VMSDEF_$LNMDEF.MAR, 2-511 retrieval, 2-487 VMSDEF_$MAILDEF.DAT, 2-511 SYS$CURRENCY, 2-37 VMSDEF_$MAILDEF.MAR, 2-511 SYS$DIGIT_SEP, 2-59 VMSDEF_$MNTDEF.DAT, 2-512 SYS$LANGUAGE, 2-95 VMSDEF_$MNTDEF.MAR, 2-512 SYS$LP_LINES, 2-98 VMSDEF_$NAMDEF.DAT, 2-512 SYS$RADIX_POINT, 2-104 VMSDEF_$NAMDEF.MAR, 2-512 VMSDEF_$OSSDEF.DAT, 2-512 privileges VMSDEF_$OSSDEF.MAR, 2-512 BYPASS, 2-431 VMSDEF_$PRCDEF.DAT, 2-513 CMKRNL, 2-443 VMSDEF_$PRCDEF.MAR, 2-513 PSWAPM, 2-460 VMSDEF_$PRVDEF.DAT, 2-513 SYSNAM, 2-336, 2-340, 2-351, VMSDEF_$PRVDEF.MAR, 2-513 2-443 VMSDEF_$PSCANDEF.DAT, 2-514 VMSDEF_$PSCANDEF.MAR, 2-514 symbols VMSDEF_$QUIDEF.DAT, 2-514 creation, 2-115 VMSDEF_$QUIDEF.MAR, 2-514 deletion, 2-58 VMSDEF_$RABDEF.DAT, 2-514 retrieval, 2-93