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


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



  Copyright, 1996 - 1999 by Uwe Zessin

  ------------------------------------------------------------------------
  PYVMS - Reference Manual

  August 1999

  This manual contains documentation about 'Python on OpenVMS'.


  Software Version:
          PYVMS V1.5.2-V005


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


  0.1  The original Python Copyright

  (copied from MISC/COPYRIGHT.)


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

                          All Rights Reserved

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

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

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

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


  0.2  The PYVMS Copyright


  Copyright 1996-1999, by Uwe Zessin

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

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


                                     CONTENTS

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


  CHAPTER 1       Introduction

          1.1     Welcome  . . . . . . . . . . . . . . . . . . . . . 1-1


  CHAPTER 2       Modules

          2.1     pyvms module . . . . . . . . . . . . . . . . . . . 2-1
          2.1.1     UAF_GET_USERNAMES - Get list of usernames from 
                    authorization file . . . . . . . . . . . . . . . 2-5
          2.1.2     CRTL_FROM_VMS - call decc$from_vms() routine . . 2-8
          2.1.3     CRTL_OPEN - call C RTL open() routine  . . . .  2-11
          2.1.4     CRTL_TO_VMS - call decc$to_vms() routine . . .  2-14
          2.2     vms_lbr module . . . . . . . . . . . . . . . . .  2-18
          2.2.1     OUTPUT_HELP - Output Help Messages . . . . . .  2-18
          2.3     vms_lib module . . . . . . . . . . . . . . . . .  2-24
          2.3.1     ADD_TIMES - Add Two Quadword Times . . . . . .  2-25
          2.3.2     ASN_WTH_MBX - Assign Channel with Mailbox  . .  2-27
          2.3.3     ATTACH - Attach Terminal to Process  . . . . .  2-29
          2.3.4     CONVERT_DATE_STRING - Convert Date String to 
                    Quadword . . . . . . . . . . . . . . . . . . .  2-30
          2.3.5     CREATE_DIR - Create a Directory  . . . . . . .  2-32
          2.3.6     CURRENCY - Get System Currency Symbol  . . . .  2-33
          2.3.7     CVTF_FROM_INTERNAL_TIME - Convert Internal Time 
                    to External Time . . . . . . . . . . . . . . .  2-33
          2.3.8     CVTF_TO_INTERNAL_TIME - Convert External Time 
                    to Internal Time . . . . . . . . . . . . . . .  2-35
          2.3.9     CVT_FROM_INTERNAL_TIME - Convert Internal Time 
                    to External Time . . . . . . . . . . . . . . .  2-37
          2.3.10    CVT_TO_INTERNAL_TIME - Convert External Time to 
                    Internal Time  . . . . . . . . . . . . . . . .  2-40
          2.3.11    CVT_VECTIM - Convert 7-Word Vector to Internal 
                    Time . . . . . . . . . . . . . . . . . . . . .  2-42
          2.3.12    DATE_TIME - Date and Time Returned as a String  2-43
          2.3.13    DAY - Day Number Returned as a Longword Integer 2-44
          2.3.14    DAY_OF_WEEK - Show Numeric Day of Week . . . .  2-45
          2.3.15    DELETE_FILE - Delete One or More Files . . . .  2-46
          2.3.16    DELETE_LOGICAL - Delete Logical Name . . . . .  2-50
          2.3.17    DELETE_SYMBOL - Delete CLI Symbol  . . . . . .  2-53
          2.3.18    DIGIT_SEP - Get Digit Separator Symbol . . . .  2-54
          2.3.19    DO_COMMAND - Execute Command . . . . . . . . .  2-55
          2.3.20    FID_TO_NAME - Convert Device and File ID to 
                    File Specification . . . . . . . . . . . . . .  2-56
          2.3.21    FIND_FILE - Find File  . . . . . . . . . . . .  2-58
          2.3.22    FIND_FILE_END - End of Find File . . . . . . .  2-62
          2.3.23    FIND_IMAGE_SYMBOL - Find Universal Symbol in 
                    Shareable Image File . . . . . . . . . . . . .  2-62
          2.3.24    FORMAT_DATE_TIME - Format Date and/or Time . .  2-63

  PYVMS - Python on OpenVMS -Reference Manual                     PAGE 5
  table of contents


          2.3.25    FORMAT_SOGW_PROT - Translate a protection mask 
                    into a formatted . . . . . . . . . . . . . . .  2-65
          2.3.26    FREE_DATE_TIME_CONTEXT - Free the Context Area 
                    Used When  . . . . . . . . . . . . . . . . . .  2-66
          2.3.27    FREE_EF - Free Event Flag  . . . . . . . . . .  2-67
          2.3.28    GETDVI - Get Device/Volume Information . . . .  2-68
          2.3.29    GETJPI - Get Job/Process Information . . . . .  2-70
          2.3.30    GETQUI - Get Queue Information . . . . . . . .  2-73
          2.3.31    GETSYI - Get Systemwide Information  . . . . .  2-77
          2.3.32    GET_ACCNAM - Get Access Name Table for 
                    Protected Object Class . . . . . . . . . . . .  2-79
          2.3.33    GET_ACCNAM_BY_CONTEXT - Get Access Name Table 
                    for Protected Object . . . . . . . . . . . . .  2-80
          2.3.34    GET_COMMAND - Get Line from SYS$COMMAND  . . .  2-81
          2.3.35    GET_COMMON - Get String from Common  . . . . .  2-83
          2.3.36    GET_DATE_FORMAT - Get the User's Date Input 
                    Format . . . . . . . . . . . . . . . . . . . .  2-83
          2.3.37    GET_EF - Get Event Flag  . . . . . . . . . . .  2-84
          2.3.38    GET_FOREIGN - Get Foreign Command Line . . . .  2-85
          2.3.39    GET_MAXIMUM_DATE_LENGTH - Retrieve the Maximum 
                    Length of a  . . . . . . . . . . . . . . . . .  2-87
          2.3.40    GET_SYMBOL - Get Value of CLI Symbol . . . . .  2-88
          2.3.41    GET_USERS_LANGUAGE - Return the User's Language 2-90
          2.3.42    INIT_DATE_TIME_CONTEXT - Initialize the Context 
                    Area Used in . . . . . . . . . . . . . . . . .  2-91
          2.3.43    LP_LINES - Lines on Each Printer Page  . . . .  2-93
          2.3.44    PARSE_ACCESS_CODE - Parse Access Encoded Name 
                    String . . . . . . . . . . . . . . . . . . . .  2-93
          2.3.45    PARSE_SOGW_PROT - Parse Protection String  . .  2-95
          2.3.46    PUT_COMMON - Put String to Common  . . . . . .  2-97
          2.3.47    PUT_OUTPUT - Put Line to SYS$OUTPUT  . . . . .  2-98
          2.3.48    RADIX_POINT - Radix Point Symbol . . . . . . .  2-99
          2.3.49    RENAME_FILE - Rename One or More Files . . . . 2-100
          2.3.50    RESERVE_EF - Reserve Event Flag  . . . . . . . 2-105
          2.3.51    RUN_PROGRAM - Run New Program  . . . . . . . . 2-106
          2.3.52    SET_LOGICAL - Set Logical Name . . . . . . . . 2-107
          2.3.53    SET_SYMBOL - Set Value of CLI Symbol . . . . . 2-110
          2.3.54    SUB_TIMES - Subtract Two Quadword Times  . . . 2-112
          2.3.55    TRIM_FILESPEC - Fit Long File Specification 
                    into Fixed Field . . . . . . . . . . . . . . . 2-114
          2.3.56    WAIT - Wait a Specified Period of Time . . . . 2-116
          2.4     vms_mail module  . . . . . . . . . . . . . . . . 2-117
          2.5     vms_sys module . . . . . . . . . . . . . . . . . 2-118
          2.5.1     ADD_HOLDER - Add Holder Record to Rights 
                    Database . . . . . . . . . . . . . . . . . . . 2-119
          2.5.2     ADD_IDENT - Add Identifier to Rights Database  2-122
          2.5.3     ADD_PROXY - Add or Modify Proxy  . . . . . . . 2-123
          2.5.4     ASCEFC - Associate Common Event Flag Cluster . 2-125
          2.5.5     ASCTIM - Convert Binary Time to ASCII String . 2-125
          2.5.6     ASCTOID - Translate Identifier Name to 
                    Identifier . . . . . . . . . . . . . . . . . . 2-127
          2.5.7     ASCUTC - Convert UTC to ASCII  . . . . . . . . 2-128
          2.5.8     BINTIM - Convert ASCII String to Binary Time . 2-129

  PYVMS - Python on OpenVMS -Reference Manual                     PAGE 6
  table of contents


          2.5.9     BINUTC - Convert ASCII String to UTC Binary 
                    Time . . . . . . . . . . . . . . . . . . . . . 2-130
          2.5.10    BRKTHRUW - Breakthrough and Wait . . . . . . . 2-131
          2.5.11    CANWAK - Cancel Wakeup . . . . . . . . . . . . 2-133
          2.5.12    CLREF - Clear Event Flag . . . . . . . . . . . 2-135
          2.5.13    CRELNM - Create Logical Name . . . . . . . . . 2-137
          2.5.14    CRELNT - Create Logical Name Table . . . . . . 2-140
          2.5.15    CREPRC - Create Process  . . . . . . . . . . . 2-142
          2.5.16    DACEFC - Disassociate Common Event Flag 
                    Cluster  . . . . . . . . . . . . . . . . . . . 2-148
          2.5.17    DASSGN - Deassign I/O Channel  . . . . . . . . 2-149
          2.5.18    DELETE_INTRUSION - Delete Intrusion Records  . 2-150
          2.5.19    DELETE_PROXY - Delete or Modify Proxy  . . . . 2-151
          2.5.20    DELLNM - Delete Logical Name . . . . . . . . . 2-152
          2.5.21    DELPRC - Delete Process  . . . . . . . . . . . 2-154
          2.5.22    DEQ - Dequeue Lock Request . . . . . . . . . . 2-156
          2.5.23    DEVICE_SCAN - Scan for Devices . . . . . . . . 2-157
          2.5.24    DISMOU - Dismount Volume . . . . . . . . . . . 2-160
          2.5.25    DISPLAY_PROXY - Display Proxy Information  . . 2-161
          2.5.26    DLCEFC - Delete Common Event Flag Cluster  . . 2-163
          2.5.27    ENQW - Enqueue Lock Request  . . . . . . . . . 2-163
          2.5.28    FILESCAN - Scan String for File Specification  2-166
          2.5.29    FIND_HELD - Find Identifiers Held by User  . . 2-169
          2.5.30    FIND_HOLDER - Find Holder of Identifier  . . . 2-172
          2.5.31    FINISH_RDB - Terminate Rights Database Context 2-175
          2.5.32    FORCEX - Force Exit  . . . . . . . . . . . . . 2-175
          2.5.33    FORMAT_ACL - Format Access Control List Entry  2-178
          2.5.34    GETJPIW - Get Job/Process Information  . . . . 2-180
          2.5.35    GETMSG - Get Message . . . . . . . . . . . . . 2-183
          2.5.36    GETQUIW - Get Queue Information  . . . . . . . 2-185
          2.5.37    GETTIM - Returns the current system time in a 
                    64-bit format  . . . . . . . . . . . . . . . . 2-193
          2.5.38    GETUAI - Get User Authorization Information  . 2-194
          2.5.39    GETUTC - Get UTC Time  . . . . . . . . . . . . 2-204
          2.5.40    GET_SECURITY - Get Security Characteristics  . 2-205
          2.5.41    GRANTID - Grant Identifier to Process  . . . . 2-210
          2.5.42    HIBER - Hibernate  . . . . . . . . . . . . . . 2-213
          2.5.43    IDTOASC - Translate Identifier to Identifier 
                    Name . . . . . . . . . . . . . . . . . . . . . 2-214
          2.5.44    INIT_VOL - Initialize Volume . . . . . . . . . 2-216
          2.5.45    MOD_HOLDER - Modify Holder Record in Rights 
                    Database . . . . . . . . . . . . . . . . . . . 2-217
          2.5.46    MOD_IDENT - Modify Identifier in Rights 
                    Database . . . . . . . . . . . . . . . . . . . 2-220
          2.5.47    MOUNT - Mount Volume . . . . . . . . . . . . . 2-222
          2.5.48    NUMTIM - Convert Binary Time to Numeric Time . 2-223
          2.5.49    NUMUTC - Convert UTC Time to Numeric 
                    Components . . . . . . . . . . . . . . . . . . 2-224
          2.5.50    PARSE_ACL - Parse Access Control List Entry  . 2-225
          2.5.51    PROCESS_SCAN - Process Scan  . . . . . . . . . 2-227
          2.5.52    PURGWS - Purge Working Set . . . . . . . . . . 2-231
          2.5.53    READEF - Read Event Flags  . . . . . . . . . . 2-232
          2.5.54    REM_HOLDER - Remove Holder Record from Rights 
                    Database . . . . . . . . . . . . . . . . . . . 2-235

  PYVMS - Python on OpenVMS -Reference Manual                     PAGE 7
  table of contents


          2.5.55    REM_IDENT - Remove Identifier from Rights 
                    Database . . . . . . . . . . . . . . . . . . . 2-236
          2.5.56    RESUME - Resume Process  . . . . . . . . . . . 2-238
          2.5.57    REVOKID - Revoke Identifier from Process . . . 2-240
          2.5.58    SCAN_INTRUSION - Scan Intrusion Database . . . 2-243
          2.5.59    SCHDWK - Schedule Wakeup . . . . . . . . . . . 2-245
          2.5.60    SETDDIR - Set Default Directory  . . . . . . . 2-247
          2.5.61    SETDFPROT - Set Default File Protection  . . . 2-248
          2.5.62    SETEF - Set Event Flag . . . . . . . . . . . . 2-250
          2.5.63    SETPRI - Set Priority  . . . . . . . . . . . . 2-252
          2.5.64    SETPRN - Set Process Name  . . . . . . . . . . 2-254
          2.5.65    SETPRV - Set Privilege . . . . . . . . . . . . 2-255
          2.5.66    SETSWM - Set Process Swap Mode . . . . . . . . 2-259
          2.5.67    SETUAI - Set User Authorization Information  . 2-260
          2.5.68    SET_RESOUCE_DOMAIN - Set Resource Domain . . . 2-268
          2.5.69    SET_SECURITY - Set Security Characteristics  . 2-269
          2.5.70    SHOW_INTRUSION - Show Intrusion Information  . 2-272
          2.5.71    SNDJBCW - Send to Job Controller . . . . . . . 2-275
          2.5.72    SUBSYSTEM - Subsystem  . . . . . . . . . . . . 2-281
          2.5.73    SUSPND - Suspend Process . . . . . . . . . . . 2-282
          2.5.74    TIMCON - Time Converter  . . . . . . . . . . . 2-284
          2.5.75    TRNLNM - Translate Logical Name  . . . . . . . 2-286
          2.5.76    VERIFY_PROXY - Verify a Proxy  . . . . . . . . 2-290
          2.5.77    WAITFR - Wait for Single Event Flag  . . . . . 2-291
          2.5.78    WAKE - Wake Process from Hibernation . . . . . 2-292
          2.5.79    WFLAND - Wait for Logical AND of Event Flags . 2-293
          2.5.80    WFLOR - Wait for Logical OR of Event Flags . . 2-294
          2.6     'VMSDEF'-related modules . . . . . . . . . . . . 2-294
          2.6.1     maintaining VMSDEF modules . . . . . . . . . . 2-294
          2.6.2     vms_brkdef module  . . . . . . . . . . . . . . 2-295
          2.6.3     vms_ciadef module  . . . . . . . . . . . . . . 2-296
          2.6.4     vms_dcdef module . . . . . . . . . . . . . . . 2-296
          2.6.5     vms_dmtdef module  . . . . . . . . . . . . . . 2-297
          2.6.6     vms_dvidef module  . . . . . . . . . . . . . . 2-297
          2.6.7     vms_dvsdef module  . . . . . . . . . . . . . . 2-298
          2.6.8     vms_fabdef module  . . . . . . . . . . . . . . 2-298
          2.6.9     vms_fscndef module . . . . . . . . . . . . . . 2-298
          2.6.10    vms_initdef module . . . . . . . . . . . . . . 2-299
          2.6.11    vms_jpidef module  . . . . . . . . . . . . . . 2-299
          2.6.12    vms_kgbdef module  . . . . . . . . . . . . . . 2-299
          2.6.13    vms_lckdef module  . . . . . . . . . . . . . . 2-300
          2.6.14    vms_lnmdef module  . . . . . . . . . . . . . . 2-300
          2.6.15    vms_maildef module . . . . . . . . . . . . . . 2-301
          2.6.16    vms_mntdef module  . . . . . . . . . . . . . . 2-301
          2.6.17    vms_namdef module  . . . . . . . . . . . . . . 2-302
          2.6.18    vms_ossdef module  . . . . . . . . . . . . . . 2-302
          2.6.19    vms_prcdef module  . . . . . . . . . . . . . . 2-302
          2.6.20    vms_prvdef module  . . . . . . . . . . . . . . 2-303
          2.6.21    vms_pscandef module  . . . . . . . . . . . . . 2-303
          2.6.22    vms_quidef module  . . . . . . . . . . . . . . 2-304
          2.6.23    vms_rabdef module  . . . . . . . . . . . . . . 2-304
          2.6.24    vms_rsdmdef module . . . . . . . . . . . . . . 2-304
          2.6.25    vms_sjcdef module  . . . . . . . . . . . . . . 2-305
          2.6.26    vms_statedef module  . . . . . . . . . . . . . 2-305

  PYVMS - Python on OpenVMS -Reference Manual                     PAGE 8
  table of contents


          2.6.27    vms_syidef module  . . . . . . . . . . . . . . 2-305
          2.6.28    vms_trmdef module  . . . . . . . . . . . . . . 2-306
          2.6.29    vms_uaidef module  . . . . . . . . . . . . . . 2-306
          2.6.30    vms_xaballdef module . . . . . . . . . . . . . 2-306
          2.6.31    vms_xabdatdef module . . . . . . . . . . . . . 2-307
          2.6.32    vms_xabfhcdef module . . . . . . . . . . . . . 2-307
          2.6.33    vms_xabitmdef module . . . . . . . . . . . . . 2-307
          2.6.34    vms_xabkeydef module . . . . . . . . . . . . . 2-308
          2.6.35    vms_xabprodef module . . . . . . . . . . . . . 2-308


  CHAPTER 3       VMS Objects

          3.0.1     vmsobj_fab object  . . . . . . . . . . . . . . . 3-2
          3.0.2     vmsobj_iosb object . . . . . . . . . . . . . . . 3-7
          3.0.3     vmsobj_lksb object . . . . . . . . . . . . . .  3-10
          3.0.4     vmsobj_nam object  . . . . . . . . . . . . . .  3-12
          3.0.5     vmsobj_rab object  . . . . . . . . . . . . . .  3-14
          3.0.6     vmsobj_xaball object . . . . . . . . . . . . .  3-20
          3.0.7     vmsobj_xabdat object . . . . . . . . . . . . .  3-22
          3.0.8     vmsobj_xabfhc object . . . . . . . . . . . . .  3-25
          3.0.9     vmsobj_xabitm object . . . . . . . . . . . . .  3-27
          3.0.10    vmsobj_xabkey object . . . . . . . . . . . . .  3-31
          3.0.11    vmsobj_xabpro object . . . . . . . . . . . . .  3-34
          3.0.12    vmsobj_xabrdt object . . . . . . . . . . . . .  3-37
          3.0.13    vmsobj_xabsum object . . . . . . . . . . . . .  3-39
          3.0.14    vmsobj__access_names object  . . . . . . . . .  3-41
          3.0.15    vmsobj__membuf object  . . . . . . . . . . . .  3-43
          3.0.16    vmsobj__ownership_names object . . . . . . . .  3-46


  INDEX
                                                                 INDEX-1












                                CHAPTER 1

                               Introduction



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



  1.1  Welcome

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

                     This is the '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'.
  ------------------------------------------------------------------------
  05-MAY-1999 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:

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


  PYVMS - Python on 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.


  ------------------------------------------------------------------------
  Examples:

  >>> import pyvms
  >>> dir (pyvms)
  ['__doc__', '__name__', 'definitions', 'history_delete', 'error',
  'history_get', 'item_get', 'history_size', 'item_list',
  'history_show', 'vms_version_number']
  >>>
  >>> type (pyvms.definitions)
  <type 'list'>
  >>> print pyvms.definitions
  ['$CIADEF', '$DCDEF', '$DMTDEF', '$DVIDEF', '$DVSDEF', '$FABDEF',
  '$FSCNDEF', '$INITDEF', '$JPIDEF', '$LCKDEF', '$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)
  <type 'int'>
  >>> print pyvms.vms_version_number
  6100

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-3
  pyvms module



  -- compare this with:

  >>> import vms_lib
  >>> print vms_lib.getsyi ('SYI$_VERSION',0)
  (0, 'V6.1    ')
  >>>

  >>> import os
  >>> os.system('write sys$output F$GETSYI("VERSION")')
  V6.1       <--- output from F$GETSYI()
  65537      <--- status from os.system() = RMS$_NORMAL

  >>> print pyvms.definitions[1]
  $JPIDEF
  >>> print len(pyvms.definitions)
  4

  >>> item_list = pyvms.item_list ('$DVIDEF');
  >>> print len(item_list)
  161
  >>> print item_list
  ['DVI$_ACPPID', 'DVI$_ACPTYPE', 'DVI$_ALL', 'DVI$_ALLDEVNAM',
  'DVI$_ALLOCLASS', 'DVI$_ALT_HOST_AVAIL', 'DVI$_ALT_HOST_NAME',
  [...]
  'DVI$_VPROT', 'DVI$_WCK']

  >>> values = pyvms.item_get ('$DVIDEF', 'DVI$_CYLINDERS', None)
  >>> type (values)
  <type 'dictionary'>
  >>> print values
  {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1,
  'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None,
  'returns_bitmask': 0, 'item_code': 40}

  >>> print values['vms_version_max']
  32767

  >>> values = pyvms.item_get ('$SYIDEF', 'SYI$_CHECK_CLUSTER', None)
  >>> print values
  {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 0,
  'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None,
  'returns_bitmask': 0, 'item_code': 8243}

  --> 'applies_to_alpha': 0

  >>> values = pyvms.item_get ('$QUIDEF', 'QUI$_FILE_FLAGS', None)
  >>> print values
  {'buffer_size': 4, 'applies_to_vax': 1, 'applies_to_alpha': 1,
  'vms_version_min' : 5520, 'vms_version_max': 32767, 'bitmask': None,
  'returns_bitmask': 1, 'item_code': 19}
  >>>
  >>> values = pyvms.item_get ('$QUIDEF', 'QUI$_FILE_FLAGS', 1)
  >>> print values

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-4
  pyvms module



  {'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)
  <type '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
  {'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

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-5
  pyvms module


   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 UAF-related routines:

        -  UAF_GET_USERNAMES - Get list of usernames from authorization
           file

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



  2.1.1  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
  build in to limit privilege usage to this routine!

  Note:   the  system  services  SYS$GETUAI  and  SYS$SETUAI  provide  a
  'context' argument, but it can only be used for repeated access to the

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-6
  pyvms.uaf_get_usernames() routine


  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)
  <type 'dictionary'>

  >>> 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)
  ('%RMS-E-EOF, end of file detected', (0, 0, 0, 0))
  >>>

  >>> # loop over list and list usernames with owner
  >>> usernames = dict.get('usernames')
  >>> for username in usernames:

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-7
  pyvms.uaf_get_usernames() routine


  ...   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
    GETUAI_TST, PYVMS-getuai-TEST
   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
    SETUAI_TST, SU_NEW_OWNER
        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 "<stdin>", 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)
  ('%RMS-E-PRV, insufficient privilege or file protection violation',\
   (0, 0, 0, 0))
  >>> stv = dict.get('stv')
  >>> print vms_sys.getmsg (stv)

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-8
  pyvms.uaf_get_usernames() routine


  ('%SYSTEM-F-NOPRIV, insufficient privilege or object protection\
   violation', (0, 0, 0, 0))
  >>>


  $ define SYSUAF XX

  >>> import vms_sys
  >>> dict = pyvms.uaf_get_usernames ()
  >>> dict
  {'sts': 98962, 'stv': 2320}

  >>> sts = dict.get('sts')
  >>> print vms_sys.getmsg (sts)
  ('%RMS-E-FNF, file not found', (0, 0, 0, 0))
  >>> stv = dict.get('stv')
  >>> print vms_sys.getmsg (stv)
  ('%SYSTEM-W-NOSUCHFILE, no such file', (0, 0, 0, 0))
  >>>


  $ define sysuaf no_disk:[000000]SYSUAF.DAT

  >>> dict = pyvms.uaf_get_usernames ()
  >>> dict
  {'sts': 99524, 'stv': 324}
  >>> sts = dict.get('sts')
  >>> print vms_sys.getmsg (sts)
  ('%RMS-F-DEV, error in device name or inappropriate device type\
   for operation', (0, 0, 0, 0))
  >>> stv = dict.get('stv')
  >>> print vms_sys.getmsg (stv)
  ('%SYSTEM-F-IVDEVNAM, invalid device name', (0, 0, 0, 0))
  >>>

  13-MAY-1999 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

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



  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:


  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 2-9
  pyvms.crtl_from_vms() routine


      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
          A Python function that is called for each file processed.  See
          the  examples setion 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 it it 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
  >>>



  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-10
  pyvms.crtl_from_vms() routine


  >>> 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
  >>>
  >>> # 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***

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-11
  pyvms.crtl_from_vms() routine


  /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
  ...    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  posix.open()
  routine, but it allows to specify a fourth argument.

  Note:  the creat() and open() routine in the C RTL expect 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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-12
  pyvms.crtl_open() routine


  fd
          file descriptor
          Use the routines in the 'posix' module to work with it.

  Arguments:

  filename
          name of the file to open
  flag
          flags like O_WRONLY or O_CREAT
  mode
          file-protection mode.  Use None or 0777 (that's octal!) to use
          VMS' default mechanism.
  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

  >>> O_WRONLY =   001
  >>> O_CREAT  = 01000
  >>> #          ^--------- these are OCTAL values !
  >>> flags = O_WRONLY + O_CREAT


  >>> fd = pyvms.crtl_open \
  ...      ('CRTL_OPEN.TMP'                 # filename
  ...      ,flags                           # flag
  ...      ,None                            # mode
  ...      ,("alq=200","rat=ftn","rfm=stm") # RMS-arguments
  ...      )
  >>> import posix
  >>> posix.write (fd, ' Hello!')
  7                                         # number of bytes written
  >>> posix.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:   <None specified>
  Backup:    <No backup recorded>

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-13
  pyvms.crtl_open() routine


  Effective: <None specified>
  Recording: <None specified>
  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.
  $


  ----------

  >>> flags = 0
  >>> fd = pyvms.crtl_open \
  ...      ('%CRTL_OPEN.TMP'                # *BAD* filename
  ...      ,flags                           # flag
  ...      ,None                            # mode
  ...      ,("alq=200","rat=ftn","rfm=stm") # RMS-arguments
  ...      )
  Traceback (innermost last):
    File "<stdin>", 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 pyvms

  >>> O_WRONLY =   001
  >>> O_CREAT  = 01000
  >>> #          ^--------- these are OCTAL values !
  >>> flags = O_WRONLY + O_CREAT

  >>> fd = pyvms.crtl_open \
  ...      ('SPOOL.TMP'                     # filename
  ...      ,flags                           # flag
  ...      ,None                            # mode
  ...      ,("fop=spl",)                    # RMS-arguments

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-14
  pyvms.crtl_open() routine


  ...      )        # ^- need a tuple, here !  
  >>> import posix
  >>> posix.write (fd, ' Hello!')
  7                                         # number of bytes written
  >>> posix.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
  $ deassign SYS$PRINT
  $ delete /queue PY_SPL_TEST
  $ delete SPOOL.TMP;1
  $

  12-MAR-1999 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 setion below.  Return 1 to indicate continuation
          of wildcard processing; 0 to abort.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-15
  pyvms.crtl_to_vms() routine


          If the action routine is omitted, then an internal routine  is
          used that appends the filename it it passed to 'file_list'.
  allow_wild
          If 0 (the default), then wildcards found in 'vms_filespec' are
          not expanded.
  no_directory
          3 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

  >>> 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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-16
  pyvms.crtl_to_vms() routine


  >>>
  >>> 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)
  ('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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-17
  pyvms.crtl_to_vms() routine


  ...
  ('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)
  ('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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-18
  pyvms.crtl_to_vms() routine


  ('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.
  @@ to be enhanced
  ------------------------------------------------------------------------
  15-JUL-1999 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.
  ------------------------------------------------------------------------
  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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-19
  vms_lbr module


  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 ommit this  argument,  then  the  RTL
          routine LIB$GET_INPUT will be used internally.

  Examples:

  >>> import vms_lbr

  >>> # define the output_routine
  >>> def fnc_out(message_string):
  ...     print "FNC_OUT(",message_string,") called"
  ...     return 1
  ...
  >>>

  >>> # define the input_routine
  >>> def fnc_inp(prompt_string):
  ...     print "FNC_INP(",prompt_string,") called"
  ...     r = (1,"SET")
  ...     return r
  ...
  >>>

  >>> # use all defaults
  >>> vms_lbr.output_help (None)

    Information available:

    :=       =        @        ACCOUNTING ALLOCATE ANALYZE  APPEND
  ...
    WRITE

  Topic? <RETURN>
  1        <-- this is the status, returned from vms_lbr.output_help()

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-20
  vms_lbr module


  >>>


  >>> # supply a specific output_width
  >>> vms_lbr.output_help (None,40)

    Information available:

    :=         =          @
    ACCOUNTING ALLOCATE   ANALYZE
  ...
    WAIT       WRITE

  Topic? <RETURN>
  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? <RETURN>
  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? <RETURN>
  Topic? <RETURN>
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-21
  vms_lbr module



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


  >>> # 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")

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-22
  vms_lbr module


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


  @@ 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<CONTROL-Y>
   *INTERRUPT*


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-23
  vms_lbr module


  $ STOP

  @@ Obviously there is a bug, here ...
  ------------------------------------------------------------------------
  28-OCT-1998 ZE.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-24
  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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-25
  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.


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-26
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 1: must be long integer

  >>> resultant_time = vms_lib.add_times (time1, 'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: must be long integer

  >>> resultant_time = vms_lib.add_times ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 2 arguments; 0 given

  >>> resultant_time = vms_lib.add_times (time1, 2)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: must be long integer

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-27
  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,

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-28
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name')
  >>>

  29-NOV-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-29
  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (1409940, '%LIB-F-ATTREQREF, attach request refused')

  >>> vms_lib.attach ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> vms_lib.attach (None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-30
  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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-31
  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 "<stdin>", 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 "<stdin>", 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, \

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-32
  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.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-33
  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 "<stdin>", 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)


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-34
  vms_lib.cvtf_from_internal_time() routine


  Returns:

  resultant_time
          F-Floating-Point Value that results from the conversion.

  Arguments:

  operation
          Conversion type to be  performed.   Codes  (LIB$K_DELTA_xxx_F)
          are currently (24-OCT-1998) not available.
  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_DELTA_WEEKS_F   = 26
  >>> LIB_K_DELTA_DAYS_F    = 27
  >>> LIB_K_DELTA_HOURS_F   = 28
  >>> LIB_K_DELTA_MINUTES_F = 29
  >>> LIB_K_DELTA_SECONDS_F = 30

  >>> op = 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
  0.5
  >>>


  >>> op = LIB_K_DELTA_DAYS_F
  >>> q_deltim = vms_sys.bintim ('0 18:00:00.00')
  >>> q_deltim
  -648000000000L
  >>> vms_lib.cvtf_from_internal_time (op, q_deltim)
  0.749999940395        <-- @@ test on other versions
  >>> print 18.0/24.0 #
  0.75
  >>>


  >>> op = LIB_K_DELTA_DAYS_F
  >>> q_deltim = vms_sys.bintim ('0 06:00:00.00')
  >>> q_deltim
  -216000000000L
  >>> vms_lib.cvtf_from_internal_time (op, q_deltim)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-35
  vms_lib.cvtf_from_internal_time() routine


  0.25
  >>> print 6.0/24.0 #
  0.25
  >>>


  >>> vms_lib.cvtf_from_internal_time ('X', q_deltim)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>
  >>> # -------------------------------v
  >>> vms_lib.cvtf_from_internal_time (1, q_deltim)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (1410060, '%LIB-F-INVOPER, invalid operation specified')
  >>>
  >>> vms_lib.cvtf_from_internal_time (op, 'X')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (1410052, '%LIB-F-DELTIMREQ, delta time required,\
   absolute time supplied')
  >>>

  24-OCT-1998 ZE.
  ------------------------------------------------------------------------



  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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-36
  vms_lib.cvtf_to_internal_time() routine


  operation
          Conversion type to be  performed.   Codes  (LIB$K_DELTA_xxx_F)
          are currently (24-OCT-1998) not available.
  input_time
          Delta time to be converted (F-Floating-Point value).

  Examples:

  >>> import vms_lib

  >>> # set up some constants
  >>> LIB_K_DELTA_WEEKS_F   = 26
  >>> LIB_K_DELTA_DAYS_F    = 27
  >>> LIB_K_DELTA_HOURS_F   = 28
  >>> LIB_K_DELTA_MINUTES_F = 29
  >>> LIB_K_DELTA_SECONDS_F = 30

  >>> op = 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 = 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'
  >>>


  >>> op = 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 = LIB_K_DELTA_WEEKS_F
  >>> resultant_time = vms_lib.cvtf_to_internal_time (op, 0.5)
  >>> resultant_time
  -3024000000000L
  >>> vms_sys.asctim (resultant_time)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-37
  vms_lib.cvtf_to_internal_time() routine


  '   3 12:00:00.00'
  >>>


  >>> vms_lib.cvtf_to_internal_time ('X', 0.5)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>
  >>> # -----------------------------v
  >>> vms_lib.cvtf_to_internal_time (1, 0.5)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (1410060, '%LIB-F-INVOPER, invalid operation specified')
  >>>
  >>> vms_lib.cvtf_to_internal_time (op, 'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal 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.
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-38
  vms_lib.cvt_from_internal_time() routine


  >>> 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)
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-39
  vms_lib.cvt_from_internal_time() routine


  >>>

  >>> vms_lib.cvt_from_internal_time (LIB_K_MONTH_OF_YEAR, q_deltim)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", 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')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: input-time - must be long integer
  >>>

  25-OCT-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-40
  vms_lib.cvt_to_internal_time() routine


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


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



  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-41
  vms_lib.cvt_to_internal_time() routine


  >>> 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>

  >>> vms_lib.cvt_to_internal_time (op, 'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>

  25-OCT-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-42
  vms_lib.cvt_vectim() routine


  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 7 given
  >>>

  >>> # wrong order of arguments
  >>> input_time = (78,56,34,12,29,2,2000)
  >>> resultant_time = vms_lib.cvt_vectim (input_time)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (1410012, '%LIB-F-IVTIME, invalid time passed in,\
   or computed')
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-43
  vms_lib.cvt_vectim() routine



  >>> # 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 ()
  >>> date_time_string
  ' 2-NOV-1997 16:23:21.93'

  * Note that there can be a space character at the begin!

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-44
  vms_lib.date_time() routine



  >>> vms_lib.date_time ()
  '15-MAR-1996 22:12:31.48'

  >>> vms_lib.date_time ('S')
  Traceback (innermost last):
    File "<stdin>", 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
  51603
  >>> day_time
  372304


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-45
  vms_lib.day() routine


  >>> 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 "<stdin>", line 1, in ?
  TypeError: argument 1: must be long integer or None

  >>> vms_lib.day ('A','B')
  Traceback (innermost last):
    File "<stdin>", 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:

  >>> import vms_lib
  >>> import vms_sys

  >>> weekday_list = [0,'Monday','Tuesday','Wednesday','Thursday',

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-46
  vms_lib.day_of_week() routine


  ... '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 "<stdin>", line 1, in ?
  TypeError: argument 1: must be long integer or None

  >>> vms_lib.day_of_week ('A', 'B')
  Traceback (innermost last):
    File "<stdin>", 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 ( \
                  filespec [,default-filespec] [,related-filespec] \
                  [,user-success-procedure] [,user-error-procedure] \
                  [,user-confirm-procedure] [,user-specified-argument] \
                  [,file-scan-context])

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-47
  vms_lib.delete_file() routine



  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
          by  calling  the  vms_lib.file_scan_end()  routine  with   the
          context as its argument.

  Examples:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-48
  vms_lib.delete_file() routine



  >>> 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
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee81bc>
  delete.tmp;              <-- fab.FNA
  <type 'string'> uspec-arg
  *user-success-procedure

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-49
  vms_lib.delete_file() routine


  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1
  <type 'string'> 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
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee81bc>
  delete.tmp;              <-- fab.FNA
  <type 'string'> uspec-arg
  *user-error-procedure
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE.TMP;1
  <type 'int'> 98954    <-- rms_sts
  <type 'int'> 2048     <-- rms_stv
  <type 'int'> 1        <-- error-source, 1= error deleting file
  <type 'string'> 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
  >>>



  >>> # example of wildcard delete with context
  >>> file = open ('DELETE1.TMP','w'); file.close()

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-50
  vms_lib.delete_file() routine


  >>> 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
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE1.TMP;1
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee81bc>
  delete*.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE1.TMP;1
  <type 'string'> uspec-arg
  *user-confirm-procedure
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE2.TMP;1
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee81bc>
  delete*.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE2.TMP;1
  <type 'string'> uspec-arg
  *user-confirm-procedure
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE3.TMP;1
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee81bc>
  delete*.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.DELETE]DELETE3.TMP;1
  <type 'string'> 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])

  Returns:

  None

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-51
  vms_lib.delete_logical() routine


  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)

  (DECW$LOGICAL_NAMES)
  %SHOW-S-NOTRAN, no translation for logical name LNM_*
  $

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-52
  vms_lib.delete_logical() routine



  >>> logical_name = 'S' * 257
  >>> vms_lib.delete_logical (logical_name)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')
  >>>

  >>> vms_lib.delete_logical ('NO_LOGICAL')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (444, '%SYSTEM-F-NOLOGNAM, no logical name match')
  >>>

  >>> vms_lib.delete_logical ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires at least 1 argument; 0 given
  >>>

  >>> vms_lib.delete_logical (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found
  >>>

  >>> s= 65536*'*'
  >>> vms_lib.delete_logical (s)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  ValueError: argument 1: logical-name - string size limited to\
   65535 characters
  >>>

  >>> vms_lib.delete_logical ('X',s)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  ValueError: argument 2: table-name - string size limited to\
   65535 characters
  >>>

  01-DEC-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-53
  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 "<stdin>", 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):

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-54
  vms_lib.delete_symbol() routine


    File "<stdin>", line 1, in ?
  ValueError: argument 1: symbol - string size limited to 65535 characters
  >>>

  >>> vms_lib.delete_symbol ('SYMBOL', 3)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)')
  >>>

  >>> vms_lib.delete_symbol ('NON_EXIST_SYMBOL')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (1409892, '%LIB-F-NOSUCHSYM, no such symbol')
  >>>

  >>> vms_lib.delete_symbol (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found
  >>> # that means 'string' ------^^^^^^^^^^^^^^^^

  >>> vms_lib.delete_symbol ()
  Traceback (innermost last):
    File "<stdin>", 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


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-55
  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given
  >>>

  >>> vms_lib.digit_sep (None)
  Traceback (innermost last):
    File "<stdin>", 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


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-56
  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 "<stdin>", 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 "<stdin>", 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!)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-57
  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 ommitted) ...
  >>> import vms_lib

  >>> status, acp_status, filespec = vms_lib.fid_to_name (
  ... 'DKA100:', (12621,13,0))
  >>> print status, acp_status, filespec
  1 1 DISK$D1:[PYTHON.PYTHON-1_5.VMS]TEST.TMP;1
  >>>
  >>> import 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'
  >>>



  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-58
  vms_lib.fid_to_name() routine


  >>> status, acp_status, filespec = vms_lib.fid_to_name (
  ... 'DKA100:', (12621,99999,0))
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-59
  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.
  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 "<stdin>", line 1, in ?
  vms_lib.error: (99596, '%RMS-F-FAB, invalid FAB or FAB not accessible')
  >>>



  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-60
  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
  >>>


  -- use multiple and provide a default-filespec


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-61
  vms_lib.find_file() routine


  $ 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;*

  25-DEC-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-62
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-63
  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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-64
  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.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-65
  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
  <vmsobj__access_names, ACCESS_NAMES at 0x002a241c>
  >>> 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, '=', '|')

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-66
  vms_lib.format_sogw_prot() routine


  (1, 'System=rwd|Owner=ed|Group=red|World=wed')
  >>>

  >>> ownshp = pyvms.vmsobj__ownership_names ()
  >>> print ownshp
  <vmsobj__ownership_names, OWNERSHIP_NAMES at 0x00298590>
  >>> 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 "<stdin>", 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 "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-67
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (1409708, '%LIB-F-EF_RESSYS, event flag reserved to system')
  >>>

  >>> # event flags 32 - 63 are initially free

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-68
  vms_lib.free_ef() routine


  >>> print vms_lib.free_ef (32)
  Traceback (innermost last):
    File "<stdin>", 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


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-69
  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 "<stdin>", line 1, in ?
  vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name')


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-70
  vms_lib.getdvi() routine


  >>> vms_lib.getdvi ("INVALID_ITEM",None,"SYS$COMMAND:")
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  ValueError: argument 1: unknown DVI$_ item code

  >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",'X',"SYS$COMMAND:")
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name')

  >>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,1)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-71
  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'.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-72
  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 "<stdin>", line 1, in ?
  vms_lib.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_lib.getjpi ('JPI$_PID',sys)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-73
  vms_lib.getjpi() routine


  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: process-id - must be integer or None

  >>> vms_lib.getjpi ('JPI$_PID',None,None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')

  >>> vms_lib.getjpi ('JPI$_PID',None,sys)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 3: expected read-only buffer, module found

  >>> vms_lib.getjpi ('JPI$_PID',None,1)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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:


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-74
  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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-75
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_lib.error: (294970, '%JBC-E-NOSUCHQUE, no such queue')

  >>> vms_lib.getqui ("BAD-FUNCTION")
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  ValueError: argument 1: unknown QUI$_ function code

  >>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","BAD-ITEM")
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  ValueError: argument 2: unknown QUI$_ item code

  >>> vms_lib.getqui ("QUI$_NOTE","QUI$_NOTE",None)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 3: search-number - must be integer or None

  *** example of wildcard lookup ***


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-76
  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,'*')

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-77
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-78
  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 "<stdin>", line 1, in ?
  vms_lib.error: (652, '%SYSTEM-F-NOSUCHNODE, remote node is unknown')
  >>>


  >>> vms_lib.getsyi (sys,0)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, module found

  >>> vms_lib.getsyi ("SYI$_RMS_GBLBUFQUO",sys)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 3: expected read-only buffer, module found
  >>>

  04-DEC-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-79
  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
  <vmsobj__access_names, ACCESS_NAMES at 0x0029521c>
  >>>

  >>> accnam = vms_lib.get_accnam ('QUEUE')
  >>> print accnam
  <vmsobj__access_names, ACCESS_NAMES at 0x00295360>
  >>>

  >>> accnam = vms_lib.get_accnam ('QUEUE', 'NOQUEUE')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_lib.error: (294970, '%JBC-E-NOSUCHQUE, no such queue')
  >>>

  >>> accnam = vms_lib.get_accnam ('BAD_CLASS')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  ValueError: argument 1: clsnam - string size limited to 65535\
   characters
  >>>

  28-JUN-1999 ZE.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-80
  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', 'DCC_VMS.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
  <vmsobj__access_names, ACCESS_NAMES at 0x0029041c>
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-81
  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 "<stdin>", 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])


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-82
  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<RETURN>

  ('input-text', 10)
  >>> vms_lib.get_command (None,5)
  input2-text2<RETURN>

  ('input', -5)
  >>> vms_lib.get_command ('Yes?')
  Yes?3input-3text<RETURN>

  ('3input-3text', 12)
  >>> vms_lib.get_command ('Yes?',7)
  Yes?4input-4text<RETURN>

  ('4input-', -7)

  >>> vms_lib.get_command ('INPUT> ',None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>

  30-SEP-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-83
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-84
  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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-85
  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 ()
  ... <RETURN>
  59
  58
    ...
  33
  32
  1
  Traceback (innermost last):
    File "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-86
  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<RETURN>

  ('DATA', 0)
  >>> print vms_lib.get_foreign ('$.',None)
  $.text<RETURN>

  ('TEXT', 1)

  -----
  $ type VMS_LIB_GET_FOREIGN1.PY
  import vms_lib
  print vms_lib.get_foreign()
  print vms_lib.get_foreign('?>')
  print vms_lib.get_foreign('!>',None)
  $ python VMS_LIB_GET_FOREIGN1.PY
  ('VMS_LIB_GET_FOREIGN1.PY', 0)
  ('VMS_LIB_GET_FOREIGN1.PY', 0)
  ('VMS_LIB_GET_FOREIGN1.PY', 1)
  $

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-87
  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<RETURN>

  ('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 \

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-88
  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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-89
  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)
  <type 'tuple'>

  >>> 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  ValueError: argument 1: symbol - string size limited to\
   65535 characters
  >>>

  >>> vms_lib.get_symbol ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> vms_lib.get_symbol (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-90
  vms_lib.get_symbol() routine


  >>> # that means 'string' ------!!!!!!!!!

  >>> vms_lib.get_symbol (None)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given

  >>> vms_lib.get_users_language (None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given
  >>>


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-91
  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 "<stdin>", 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|" + \

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-92
  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.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-93
  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 "<stdin>", 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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-94
  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 = \

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-95
  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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-96
  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), \

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-97
  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 "<stdin>", 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 "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-98
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 2-99
  vms_lib.put_output() routine


  None                    <-- return-value from put_output()

  >>> print vms_lib.put_output ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> print vms_lib.put_output (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found

  >>> print vms_lib.put_output ("1", "2")
  Traceback (innermost last):
    File "<stdin>", 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"

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-100
  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given

  >>> vms_lib.radix_point (None)
  Traceback (innermost last):
    File "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-101
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-102
  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
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
  rename-from.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;1
  <type 'string'> uspec-arg
  >>>
  >>> print status, context
  1 0
  >>> vms_sys.getmsg (status)
  ('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-103
  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
  <type 'string'> USER_HERE:[ZESSIN.RENAME]NO-FILE.TMP;
  <type 'string'> new-file.tmp;
  <type 'int'> 98962    <-- rms_sts
  <type 'int'> 2320     <-- rms_stv
  <type 'int'> 0        <-- error-source
  <type 'string'> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-104
  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
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.T-TMP;
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
  rename*.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.T-TMP;1
  <type 'string'> uspec-arg
  *user-confirm-procedure
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.T-TMP;
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
  rename*.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.T-TMP;1
  <type 'string'> uspec-arg
  *user-confirm-procedure
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;
  <type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
  rename*.tmp;
  <type 'string'> uspec-arg
  *user-success-procedure
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1
  <type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;1
  <type 'string'> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-105
  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 "<stdin>", 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 "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-106
  vms_lib.reserve_ef() routine


  >>> print vms_lib.reserve_ef (32)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-107
  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 "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-108
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-109
  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,

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-110
  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_*

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-111
  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 3: table-type-indicator must be integer or None
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-112
  vms_lib.set_symbol() routine



  >>> vms_lib.set_symbol ()
  Traceback (innermost last):
    File "<stdin>", 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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-113
  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 1: must be long integer
  >>>

  >>> resultant_time = vms_lib.sub_times (time1, 'X')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-114
  vms_lib.sub_times() routine


  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: must be long integer
  >>>

  >>> resultant_time = vms_lib.sub_times ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 2 arguments; 0 given
  >>>

  >>> resultant_time = vms_lib.sub_times (time1, 2)
  Traceback (innermost last):
    File "<stdin>", 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'

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-115
  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 = \

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-116
  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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-117
  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-118
  vms_sys module


  2.5  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-119
  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
        -  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.5.1  ADD_HOLDER - Add Holder Record to Rights Database

  Adds a specified holder record to a target identifier.

  Format:

      vms_sys.add_holder (id, holder [,attrib])


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-120
  vms_sys.add_holder() routine


  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)
  >>> vms_sys.add_holder (id_2, (uic_system,0), None)

  UAF> show /identifier /full ID_2

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-121
  vms_sys.add_holder() routine


    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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 2: holder - tuple-element:1 is not an integer
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-122
  vms_sys.add_ident() routine


  2.5.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
    Name                             Value           Attributes
    NEW_ID_2                         %X80010014      DYNAMIC
  UAF>


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-123
  vms_sys.add_ident() routine



  >>> vms_sys.add_ident ('x23456789012345678901234567890123')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 3: attrib - must be integer or None
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.3  ADD_PROXY - Add or Modify Proxy

  Format:

      vms_sys.add_proxy (rem_node, rem_user, local_user [,flags])

  Returns:

  None

  Arguments:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-124
  vms_sys.add_proxy() routine


  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 "<stdin>", line 1, in ?
  vms_sys.error: (116311642, '%SECSRV-E-DUPLICATEUSER, username\
   already exists in the proxy record')
  >>>

  21-JAN-1999 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-125
  vms_sys.ascefc() routine


  2.5.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.5.5  ASCTIM - Convert Binary Time to ASCII String

  Format:

      timbuf = vms_sys.asctim (timadr [,cvtflg])

  Returns:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-126
  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 "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation

  >>> vms_sys.asctim ('0x009A0070B0CB6D60L', 1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: timadr - must be long integer

  >>> vms_sys.asctim ('string')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-127
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-128
  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> vms_sys.asctoid (None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, None found

  >>> vms_sys.asctoid ('NON_EXIST')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier')

  >>> vms_sys.asctoid ('-')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (8740, '%SYSTEM-F-IVIDENT, invalid identifier format')
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-129
  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 "<stdin>", line 1, in ?
  TypeError: argument 1: utcadr - must be long integer
  >>>

  09-JAN-1999 ZE.
  ------------------------------------------------------------------------



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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-130
  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> vms_sys.bintim (None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, None found
  # that means 'string' ----------^^^^^^^^^^^^^^^^

  >>> vms_sys.bintim ('INVALID')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time')

  >>> vms_sys.bintim (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found
  # that means 'string' ----------^^^^^^^^^^^^^^^^
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.9  BINUTC - Convert ASCII String to UTC Binary Time

  Format:

      utcadr = vms_sys.binutc (timbuf)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-131
  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 "<stdin>", line 1, in ?
  vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time')

  >>> utc_tim = vms_sys.binutc ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given
  >>>

  09-JAN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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'

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-132
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-133
  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.5.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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-134
  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 2: expected read-only buffer, int found

  >>> nonexist_pid = 99
  >>> vms_sys.canwak (nonexist_pid)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-135
  vms_sys.canwak() routine


  >>> vms_sys.canwak (None,'NONEXPRC')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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!)



  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-136
  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 "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')

  >>> setflg, state = vms_sys.readef (255)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')

  >>> setflg = vms_sys.setef (255)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')
  >>>

  >>> setflg = vms_sys.clref ('X')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (564, '%SYSTEM-F-UNASEFC, unassociated event flag cluster')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-137
  vms_sys.clref() routine


  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-138
  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*')


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-139
  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))

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-140
  vms_sys.crelnm() routine


  >>>

  @@ more examples for CRELNM

  29-NOV-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-141
  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 *
  $

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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-142
  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.5.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:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-143
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-144
  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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-145
  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,

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-146
  vms_sys.creprc() routine


  ... l_uic, None, l_stsflg)
  Traceback (innermost last):
    File "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-147
  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 "<stdin>", 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  + \

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-148
  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (380, '%SYSTEM-F-IVSTSFLG, invalid status flag')
  >>>

  @@ more examples for CREPRC

  24-MAR-1999 ZE.
  ------------------------------------------------------------------------



  2.5.16  DACEFC - Disassociate Common Event Flag Cluster

  Releases the calling process's association with a  common  event  flag
  cluster.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-149
  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.5.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.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-150
  vms_sys.delete_intrusion() routine


  2.5.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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (10468, '%SYSTEM-F-NOSYSPRV, operation requires\
   SYSPRV privilege')
  >>>
  >>>

  31-MAY-1999 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-151
  vms_sys.delete_proxy() routine


  2.5.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 "<stdin>", 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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-152
  vms_sys.delete_proxy() routine



  REMNOD::REMUSR
      NOPRIV
  UAF>


  >>> vms_sys.delete_proxy ('REMNOD_NO', 'REMUSR_NO')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (116311666, '%SECSRV-E-NOSUCHPROXY, no proxy record\
   matches your specification')
  >>>

  21-JAN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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')"

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-153
  vms_sys.dellnm() routine


  Traceback (innermost last):
    File "<string>", 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]

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-154
  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.5.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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-155
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-156
  vms_sys.delprc() routine



  >>> audit_server_pid = 265
  >>> print vms_sys.delprc (265)
  Traceback (innermost last):
    File "<stdin>", 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.5.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:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-157
  vms_sys.deq() routine


  See the examples section of the vms_sys.enqw() routine.

  30-MAY-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-158
  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 "<stdin>", 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 "<stdin>", line 2, in ?
  vms_sys.error: (2648, '%SYSTEM-W-NOMOREDEV, no more devices')
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-159
  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 3: contxt - must be long integer or None
  >>>

  >>> dev, ctx = vms_sys.device_scan('*','X')
  Traceback (innermost last):

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-160
  vms_sys.device_scan() routine


    File "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found
  >>> #   that means 'string' --- ^^^^^^^^^^^^^^^^
  >>>

  10-DEC-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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 "<stdin>", line 1, in ?
  vms_sys.error: (7573552, '%DISM-W-USERFILES, 0 user files open on volume')
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-161
  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 "<stdin>", 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.5.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:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-162
  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, \

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-163
  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 "<stdin>", line 2, in ?
  vms_sys.error: (1777, '%SYSTEM-S-NOMOREITEMS, no more items to be\
   returned')
  >>>

  >>>

  21-JAN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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.5.27  ENQW - Enqueue Lock Request

  Note:  the 'vms_lckdef' module contains bitmasks  and  constants  that
  are defined in '$LCKDEF'.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-164
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-165
  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 = <vmsobj_lksb, LKSB at 0x00289730>
  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:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-166
  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.5.28  FILESCAN - Scan String for File Specification

  Searches a string for a file specification and parses  the  components
  of that file specification.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-167
  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.


  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.

          Items that the system service could not  locate  will  not  be
          returned in the dictionary ('dict').

  Examples:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-168
  vms_sys.filescan() routine



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

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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-169
  vms_sys.filescan() routine


  >>> # a single-item tuple --v
  >>> valuelst = ('FSCN$__BAD', )
  >>> dict     = vms_sys.filescan ('X', valuelst)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 2 arguments; 1 given
  >>>

  >>> dict = vms_sys.filescan ('X','Y')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: valuelst - must be a tuple of strings
  >>>

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

  @@ more examples for FILESCAN

  24-MAR-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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.
  attrib
          Attributes associated with the holder returned  in  'id'  when
          FIND_HELD  completes execution.  Bitmask values are defined in
          module 'vms_kgbdef'.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-170
  vms_sys.find_held() routine


  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)
  >>>
  >>> # 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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-171
  vms_sys.find_held() routine


  >>> 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 "<stdin>", 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 "<stdin>", 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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-172
  vms_sys.find_held() routine


  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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (8740, '%SYSTEM-F-IVIDENT, invalid identifier format')
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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
          FIND_HOLDER.
  contxt
          Context value used when repeatedly calling  FIND_HOLDER.   See
          the system services reference manual for more information.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-173
  vms_sys.find_holder() routine


  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
  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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-174
  vms_sys.find_holder() routine


  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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
  >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier')


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-175
  vms_sys.find_holder() routine


  >>> id = 0x80011234        # this identifier does not exist
  >>> uic, attrib, fnd_ctx = vms_sys.find_holder (id, None)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier')
  >>>

  27-SEP-1998 ZE.
  ------------------------------------------------------------------------



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



  2.5.32  FORCEX - Force Exit

  Causes an Exit ($EXIT) service call  to  be  issued  on  behalf  of  a
  specified process.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-176
  vms_sys.forcex() routine


  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 "<stdin>", line 1, in ?
  vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')

  >>> print vms_sys.forcex (None,'')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')

  >>> print vms_sys.forcex (None,None)
  %NONAME-W-NOMSG, Message number 00000000
  $ ! current process forced to exit

  >>> print vms_sys.forcex (None,None,None)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-177
  vms_sys.forcex() routine


  %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 "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.forcex (None,'NO_SUCH_PRC')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.forcex (None,'PROCESS_NAME_TO_LONG')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')

  >>> vms_sys.forcex ('BAD')
  Traceback (innermost last):

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-178
  vms_sys.forcex() routine


    File "<stdin>", line 1, in ?
  TypeError: argument 1: pidadr - must be integer or None

  >>> vms_sys.forcex (None,1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: expected read-only buffer, int found

  >>> vms_sys.forcex (None,None,'BAD')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 3: code - must be integer or None
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-179
  vms_sys.format_acl() routine


          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
  >>>
  >>> 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
  >>> 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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-180
  vms_sys.format_acl() routine


  (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.5.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
                  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-181
  vms_sys.getjpiw() routine


          '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
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-182
  vms_sys.getjpiw() routine


          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 = <vmsobj_iosb, IOSB at 0x00218bd8>
  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))
  >>>


  >>> # 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()
  >>> 

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-183
  vms_sys.getjpiw() routine


  >>> 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 = <vmsobj_iosb, IOSB at 0x0021c208>
  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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 5: iosb - must be vmsobj_iosb or None
  >>>

  @@ more vms_sys.getjpiw() examples
  >>>

  12-JUN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.35  GETMSG - Get Message

  Format:

      bufadr, outadr = vms_sys.getmsg (msgid [,flags])

  Returns:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-184
  vms_sys.getmsg() routine


  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
  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-185
  vms_sys.getmsg() routine


  '%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 "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>> vms_sys.getmsg (1,'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: flags - must be integer or None
  >>>

  17-OCT-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-186
  vms_sys.getquiw() routine


  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.


  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-187
  vms_sys.getquiw() routine


          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
                  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'

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-188
  vms_sys.getquiw() routine


                  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 = <vmsobj_iosb, IOSB at 0x0022da88>
  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))
  >>>
  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-189
  vms_sys.getquiw() routine


  >>>


  >>> # 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
  <vmsobj_iosb, IOSB at 0x0022da10>
  >>>
  >>> dict = vms_sys.getquiw (None, 'QUI$_CANCEL_OPERATION', \
  ...                         context, None, iosb)
  >>>
  >>> for key in dict.keys():
  ...   print key, '=', dict.get(key)
  ...
  iosb = <vmsobj_iosb, IOSB at 0x0022da10>
  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
  <vmsobj_iosb, IOSB at 0x0022da10>
  >>> # 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):
  ...   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')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-190
  vms_sys.getquiw() routine


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

  itmlst_file  = (("QUI$_SEARCH_FLAGS",                  \
                       vms_quidef.QUI_M_SEARCH_WILDCARD) \
                  ,"QUI$_FILE_IDENTIFICATION"            \
                  ,"QUI$_FILE_SPECIFICATION"             \
                 )

  context = -1    # create a new wildcard context

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-191
  vms_sys.getquiw() routine


  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:
                  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')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-192
  vms_sys.getquiw() routine


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

  --------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-193
  vms_sys.getquiw() routine



  >>> dict = vms_sys.getquiw ('BADEFN', 'QUI$_DISPLAY_JOB')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: efn - must be integer or None
  >>>


  >>> dict = vms_sys.getquiw (None, 'QUI$_QUEUE_NAME')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 5: iosb - must be vmsobj_iosb or None
  >>>

  @@ more vms_sys.getquiw() examples
  >>>

  31-MAY-1999 ZE.
  ------------------------------------------------------------------------



  2.5.37  GETTIM - Returns the current system time in a 64-bit format

  Format:

      timadr = vms_sys.gettim ()


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-194
  vms_sys.gettim() routine


  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given

  >>> vms_sys.gettim (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



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

      dict = vms_sys.getuai (None, [contxt], usrnam, itmlst \
              [,None] [,None] [,None])

  Returns:

  dict

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-195
  vms_sys.getuai() routine


          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).  You can 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
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-196
  vms_sys.getuai() routine


          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
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-197
  vms_sys.getuai() routine


          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= "PYVMS-getuai-TEST" -
       /uic= [12345,13524] /account= "PYVMS_GT" -
       /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)

  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-198
  vms_sys.getuai() routine



  Username: GETUAI_TST    Owner:  PYVMS-getuai-TEST
  Account:  PYVMS_GT      UIC:    [12345,13524] ([PYVMS_GT,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)
  <type 'dictionary'>

  >>> dict
  {'UAI$_OWNER': 'PYVMS-getuai-TEST', 'status': 1}

  >>> dict = vms_sys.getuai (None,None,'GETUAI_TST', \
  ...   ('UAI$_OWNER', 'UAI$_EXPIRATION'))
  >>> returned_items = dict.items()
  >>> returned_items.sort()
  >>> for itm in range(len(returned_items)):
  ...   print returned_items[itm]
  ...
  ('UAI$_EXPIRATION', 44585444967800000L)
  ('UAI$_OWNER', 'PYVMS-getuai-TEST')
  ('status', 1)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-199
  vms_sys.getuai() routine


  >>>

  >>> q_expdat = dict.get('UAI$_EXPIRATION')
  >>> q_expdat
  44585444967800000L
  >>> type (q_expdat)
  <type 'long int'>
  >>> 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
  >>> l_local_access_s
  4322305
  >>> hex (l_local_access_s)
  '0x41f401'
  >>>


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-200
  vms_sys.getuai() routine


  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()
  >>> for itm in range(len(returned_items)):
  ...   print returned_items[itm]
  ...
  ('UAI$_ACCOUNT', 'PYVMS_GT                        ')
  ('UAI$_ASTLM', 115)
  ('UAI$_BATCH_ACCESS_P', (0, 0, 0))

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-201
  vms_sys.getuai() routine


  ('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', 'PYVMS-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))
  ('UAI$_REMOTE_ACCESS_S', (0, 0, 0))
  ('UAI$_SALT', 29702)
  ('UAI$_SHRFILLM', 112)
  ('UAI$_TQCNT', 116)
  ('UAI$_UIC', 350558036)
  ('UAI$_USERNAME', 'GETUAI_TST                      ')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-202
  vms_sys.getuai() routine


  ('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
  >>> # 'dict' is from a different account

  >>> dict = vms_sys.getuai (None,None,'NOPRIV',
  ...   ('UAI$_PWD_DATE','UAI$_PWD_LIFETIME'))
  >>> q_expdate = dict.get('UAI$_PWD_DATE') + \
  ...             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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-203
  vms_sys.getuai() routine


  '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')
  >>> 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):
        print 'FILLM =', w_fillm, 'too small for user', \
              username
      #
    #
  #
  $ python CHK_FILLM.PY

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-204
  vms_sys.getuai() routine


  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 "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 4: tuple-element:0 item code must be a string
  >>>

  31-MAY-1999 ZE.
  ------------------------------------------------------------------------



  2.5.39  GETUTC - Get UTC Time

  Returns the current time in 128-bit UTC format.

  Format:

      utcadr = vms_sys.getutc ()

  Returns:

  utcadr
          128-bit UTC value - a Python long integer

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-205
  vms_sys.getutc() routine


  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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given

  >>> vms_sys.getutc (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given
  >>>

  09-JAN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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])

  Returns:

  dict
          A dictionary that has the following keys:

          'status'

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-206
  vms_sys.get_security() routine


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

  special notes about some item codes:

  OSS$_ACCESS_NAMES
          Returns a 'vmsobj__access_names' object.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-207
  vms_sys.get_security() routine


  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]

  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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-208
  vms_sys.get_security() routine



  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)
  >>> print vms_sys.getmsg (status) [0]
  %SYSTEM-S-NORMAL, normal successful completion
  >>>
  >>> contxt = 0
  >>> flags  = 0
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-209
  vms_sys.get_security() routine


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

  19-JUL-1999 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-210
  vms_sys.grantid() routine


  2.5.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.
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-211
  vms_sys.grantid() routine


          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')
  (0, 91, (-2147418094, 2), 0)
  >>> id = -2147418094 # check
  >>> namlen, nambuf, resid, attrib, id_ctx = vms_sys.idtoasc (id,0)
  >>> nambuf
  'ID_2'
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-212
  vms_sys.grantid() routine



  $ 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 "<stdin>", 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:
   INTERACTIVE
   LOCAL
   ID_1                              resource
   ID_2                              dynamic

  System rights:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-213
  vms_sys.grantid() routine


   SYS$NODE_HERE
   ID_1                              resource, dynamic     <--
  $
  @@ GRANTID - more examples
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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 "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given

  >>> vms_sys.hiber (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 0 arguments; 1 given

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-214
  vms_sys.hiber() routine


  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-215
  vms_sys.idtoasc() routine


    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 = \
  ...     vms_sys.idtoasc (id, context)
  ...   print nambuf
  ...   context = fnd_ctx
  ...
  BATCH
  DECNET

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-216
  vms_sys.idtoasc() routine


  DECWINDOWS
  DEFAULT
  DIALUP
  FAL$SERVER
  FIELD
  [...]
  VPM$SERVER
  ZESSIN
  Traceback (innermost last):
    File "<stdin>", 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.5.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.


  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-217
  vms_sys.init_vol() routine


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



  2.5.45  MOD_HOLDER - Modify Holder Record in Rights Database

  Modifies the specified holder record of the target identifier  in  the
  rights database.

  Format:


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-218
  vms_sys.mod_holder() routine


      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
      Holder                           Attributes
      SYSTEM                           DYNAMIC
  UAF>


  >>> import vms_sys
  >>> import vms_kgbdef

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-219
  vms_sys.mod_holder() routine



  >>> 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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier')
  >>>

  >>> vms_sys.mod_holder (id_1, 'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: holder - must be a tuple of 2 integers
  >>>
  >>> vms_sys.mod_holder (id_1, (0,'X'))
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-220
  vms_sys.mod_holder() routine


  TypeError: argument 2: holder - tuple-element:0 is not an integer
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.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
  %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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-221
  vms_sys.mod_ident() routine


    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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name')
  >>>

  >>> # rename identifier %X80012345 (named ID_1) to ID_1X which
  >>> #   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>


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-222
  vms_sys.mod_ident() routine


  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



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

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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-223
  vms_sys.mount() routine


  >>> 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.5.48  NUMTIM - Convert Binary Time to Numeric Time

  Format:

      timbuf = vms_sys.numtim ([timadr])

  Returns:

  timbuf
          a tuple of 7 (16-bit) integers consisting of:
          (year, month, day, hour, minute, second, hundredth)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-224
  vms_sys.numtim() routine


  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 "<stdin>", line 1, in ?
  TypeError: argument 1: timadr - must be long integer
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.49  NUMUTC - Convert UTC Time to Numeric Components

  Format:

      timbuf = vms_sys.numutc ([utcadr])

  Returns:

  timbuf
          a tuple of 7 (16-bit) integers consisting of:
          (year, month, day, hour, minute, second, hundredth,
          inaccuracy-days, in-hours, in-minutes, in-seconds
          in-hundredth, TDF-in-minutes)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-225
  vms_sys.numutc() routine


  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 "<stdin>", line 1, in ?
  vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time')

  >>> vms_sys.numutc ('X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: utcadr - must be long integer
  >>>

  09-JAN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.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])

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-226
  vms_sys.parse_acl() routine



  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)'
  >>>
  >>> # 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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-227
  vms_sys.parse_acl() routine


  ''
  >>>
  >>> import vms_lib
  >>>
  >>> # get access names table of QUEUE
  >>> accnam_queue = vms_lib.get_accnam ('QUEUE')
  >>> print accnam_queue
  <vmsobj__access_names, ACCESS_NAMES at 0x002b6a20>
  >>> 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.5.51  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:

      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:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-228
  vms_sys.process_scan() routine


          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
  ...       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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-229
  vms_sys.process_scan() routine


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



  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-230
  vms_sys.process_scan() routine


  >>> 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),
  ...  )
  ... )
  >>> 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+

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-231
  vms_sys.process_scan() routine


  ...                            vms_pscandef.PSCAN_M_WILDCARD)
  ...  )
  ... )
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", 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 "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 2: itmlst - item:0 data must be string
  >>>


  >>> ctx = vms_sys.process_scan (0,
  ...  (('PSCAN$__BAD', 1,vms_pscandef.PSCAN_M_NEQ), )
  ... )
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  ValueError: argument 2: itmlst - unknown item code: PSCAN$__BAD
  >>>

  12-JUN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.52  PURGWS - Purge Working Set

  Format:

      vms_sys.purgws (start-addr, end-addr)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-232
  vms_sys.purgws() routine



  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

  >>> <CONTROL-T>
  NODE::PRCNAM 19:06:29 PYTHON  CPU=00:08:06.24 PF=101647 IO=7846 MEM=1201
  >>> allocate_memory = range (50000)
  >>> <CONTROL-T>
  NODE::PRCNAM 19:07:13 PYTHON  CPU=00:08:09.52 PF=103644 IO=7860 MEM=2886
  >>> vms_sys.purgws (0,2147483647)
  >>> <CONTROL-T>
  NODE::PRCNAM 19:07:42 PYTHON  CPU=00:08:09.93 PF=103850 IO=7867 MEM=331
                                                                      ^^^
  >>> vms_sys.purgws ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 2 arguments; 0 given

  >>> vms_sys.purgws (1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 2 arguments; 1 given

  >>> vms_sys.purgws (1,None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: illegal argument type for built-in operation
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.53  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-233
  vms_sys.readef() routine


  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


  >>> 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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-234
  vms_sys.readef() routine


  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 "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')

  >>> setflg, state = vms_sys.readef (255)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')

  >>> setflg = vms_sys.setef (255)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')
  >>>

  >>> setflg = vms_sys.clref ('X')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (564, '%SYSTEM-F-UNASEFC, unassociated event flag cluster')
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-235
  vms_sys.rem_holder() routine


  2.5.54  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)
  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
  >>> import vms_kgbdef


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-236
  vms_sys.rem_holder() routine


  >>> 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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (8684, '%SYSTEM-F-NOSUCHID, unknown rights identifier')
  >>>

  >>> vms_sys.rem_holder (id_1, 'X')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 2: holder - tuple-element:1 is not an integer
  >>>
  >>> vms_sys.rem_holder (id_1, ('X',0))
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: holder - tuple-element:0 is not an integer
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.55  REM_IDENT - Remove Identifier from Rights Database

  Removes the specified identifier record and all its holder records (if
  any) from the rights database.

  Format:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-237
  vms_sys.rem_ident() routine



      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])
  [...]
    SYSLCK    SYSNAM    SYSPRV    TMPMBX    UPGRADE   VOLPRO    WORLD
  Identifier                         Value           Attributes
    ID_2                             %X80010016      DYNAMIC
    ID_1                             %X80010011      RESOURCE
  UAF>


  >>> import vms_sys
  >>> import vms_kgbdef

  >>> id_1 = 0x80010011    # identifier ID_1
  >>> id_2 = 0x80010012    # identifier ID_2

  >>> vms_sys.rem_ident (id_1)


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-238
  vms_sys.rem_ident() routine


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



  2.5.56  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-239
  vms_sys.resume() routine


          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 "<stdin>", line 1, in ?
  TypeError: argument 2: expected read-only buffer, int found

  >>> nonexist_pid = 99
  >>> vms_sys.resume (nonexist_pid)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.resume (None,'NONEXPRC')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.resume ()
  352             <-- set RESUME on current process - the next
  $ SET PROCESS/SUSPEND ! continues immediately

  >>> vms_sys.resume (None,None)
  352             <-- set RESUME on current process - the next
  $ SET PROCESS/SUSPEND ! continues immediately

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-240
  vms_sys.revokid() routine


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

  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-241
  vms_sys.revokid() routine


          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
   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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-242
  vms_sys.revokid() routine


   |  |     |            |------ 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 "<stdin>", 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
   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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-243
  vms_sys.revokid() routine


   |  |    |            |   |- 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.5.58  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
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-244
  vms_sys.scan_intrusion() routine


          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'
  >>> 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'

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-245
  vms_sys.scan_intrusion() routine


  >>>

  $
  %%%%%%%%%%%  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.5.59  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:

  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-246
  vms_sys.schdwk() routine


          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 ()
  >>> 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 <CONTROL-Y> to exit


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-247
  vms_sys.schdwk() routine


  >>> # 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 "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')


  >>> vms_sys.schdwk (None, 1, 0xFFFFFFFFFA0A1F00L)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  TypeError: argument 3: daytim - must be long integer

  >>> vms_sys.schdwk (None, None, 0xFFFFFFFFFA0A1F00L, 1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 4: reptim - must be long integer
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



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

  Format:

      cur-dir = vms_sys.setddir ([new-dir])

  Returns:

  cur-dir
          Current /old default directory.   Note  that  this  is  always
          returned!

  Arguments:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-248
  vms_sys.setddir() routine


  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 "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found

  >>> vms_sys.setddir (None,2)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires at most 1 argument; 2 given

  >>> vms_sys.setddir ('BAD#DIRECTORY#SYNTAX#')
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (99532, '%RMS-F-DIR, error in directory name')
  >>>

  12-JUN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.61  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-249
  vms_sys.setdfprot() routine


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


  >>> 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
  $

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-250
  vms_sys.setdfprot() routine



  >>> vms_sys.setdfprot ('X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: new-def-prot - must be positive\
   16-bit integer or None
  >>>

  01-JAN-1999 ZE.
  ------------------------------------------------------------------------



  2.5.62  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
  (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!)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-251
  vms_sys.setef() 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 "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')

  >>> setflg, state = vms_sys.readef (255)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')

  >>> setflg = vms_sys.setef (255)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (236, '%SYSTEM-F-ILLEFC, illegal event flag cluster')
  >>>

  >>> setflg = vms_sys.clref ('X')
  Traceback (innermost last):
    File "<stdin>", 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):

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-252
  vms_sys.setef() routine


    File "<stdin>", line 1, in ?
  vms_sys.error: (564, '%SYSTEM-F-UNASEFC, unassociated event flag \
   cluster')
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.63  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.
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-253
  vms_sys.setpri() routine



  >>> # 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 "<stdin>", line 1, in ?
  TypeError: function requires at least 3 arguments; 0 given

  >>> vms_sys.setpri (0,None)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires at least 3 arguments; 2 given

  >>> vms_sys.setpri (1,2,3)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.setpri (None,'NONEXPRC',4)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.setpri (__name__,'X',4)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: pidadr - must be integer or None
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-254
  vms_sys.setprn() routine


  2.5.64  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)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: expected read-only buffer, int found

  >>> vms_sys.setprn (None,2)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires at most 1 argument; 2 given

  >>> vms_sys.setprn ('THIS_PROCESS_NAME_IS_INVALID')
  Traceback (innermost last):

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-255
  vms_sys.setprn() routine


    File "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name')
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.65  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'.
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-256
  vms_sys.setprv() routine


                           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)
  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"

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-257
  vms_sys.setprv() routine



  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

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

  $ 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-258
  vms_sys.setprv() routine


  [...]
  $


  $ 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 "<stdin>", line 1, in ?
  TypeError: argument 1: enbflg - must be integer or None
  >>>

  >>> vms_sys.setprv (1,'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: prvadr - must be long integer or None
  >>>

  >>> vms_sys.setprv (1,0L,'X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 3: prmflg - must be integer or None
  >>>


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-259
  vms_sys.setprv() routine


  14-FEB-1999 ZE.
  ------------------------------------------------------------------------



  2.5.66  SETSWM - Set Process Swap Mode

  Format:

      oldflg = vms_sys.setswm ([swpflg])

  Returns:

  oldflg
          This  is  the  'condition  value  returned'  from  the  system
          service.   The  values  of  'SS$_WASSET'  or  'SS$_WASCLR' are
          returned as numbers 0 or 1 -  other  conditions  result  in  a
          Python exception.

  Arguments:

  swpflg
          Indicator specifying whether the process can be swapped.

  Examples:

  $ SET PROCESS/PRIVILEGE=PSWAPM

  >>> import vms_sys

  >>> # 1= disable swapping
  >>> vms_sys.setswm (1)
  0

  >>> # 0= enable swapping
  >>> vms_sys.setswm (0)
  1
  >>> vms_sys.setswm (0)
  0

  >>> # None = disable swapping
  >>> vms_sys.setswm (None)
  0
  >>> # 0= enable swapping
  >>> vms_sys.setswm (0)
  1

  >>> vms_sys.setswm ()
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> vms_sys.setswm ('X')
  Traceback (innermost last):

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-260
  vms_sys.setswm() routine


    File "<stdin>", line 1, in ?
  TypeError: argument 1: swpflg must be integer or None


  $ SET PROCESS/PRIVILEGE=NOPSWAPM
  ...
  >>> vms_sys.setswm (0)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (36, '%SYSTEM-F-NOPRIV, insufficient privilege or object\
   protection violation')
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



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


  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-261
  vms_sys.setuai() routine


          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 current 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
          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-262
  vms_sys.setuai() routine


          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
          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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-263
  vms_sys.setuai() routine


  Examples:

  UAF> add SETUAI_TST /owner= "PYVMS-setuai-TEST" -
       /uic= [12345,13527] /account= "PYVMS_ST" -
       /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:  PYVMS-setuai-TEST
  Account:  PYVMS_ST                         UIC:    [12345,13527]
   ([PYVMS_GT,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
  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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-264
  vms_sys.setuai() routine


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

  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-265
  vms_sys.setuai() routine



  >>> 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            )
  ... ,('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')

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-266
  vms_sys.setuai() routine


  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 PYVMS_GT
    Name                             Value           Attributes
    PYVMS_GT                         [012345,177777]
  UAF> SHOW/IDENTIFIER SETUAI_TST
    Name                             Value           Attributes
    SETUAI_TST                       [012345,013527]
  UAF>

  You need vms_sys.mod_ident() to do this.

  ----------------------------------------
  The contents from UAI$_USER_DATA is not shown by AUTHORIZE:

  >>> dict = vms_sys.getuai (None,None,'SETUAI_TST', \
  ... ('UAI$_USER_DATA',))

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-267
  vms_sys.setuai() routine


  >>> #                ^-- 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:  -#######-#######-#######            ###-#######-#######-####
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-268
  vms_sys.setuai() routine


  [...]
  >>>

  18-APR-1999 ZE.
  ------------------------------------------------------------------------



  2.5.68  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
          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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-269
  vms_sys.set_resouce_domain() routine


  >>> 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 = <vmsobj_lksb, LKSB at 0x00285718>
  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.
  ------------------------------------------------------------------------



  2.5.69  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], \

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-270
  vms_sys.set_security() routine


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

          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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-271
  vms_sys.set_security() routine


  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]

  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]


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-272
  vms_sys.set_security() routine


  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.5.70  SHOW_INTRUSION - Show Intrusion Information

  Format:

      status, intruder, breakin_block, context = \
          vms_sys.show_intrusion (user_criteria, [flags], [context])

  Returns:

  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-273
  vms_sys.show_intrusion() routine


                  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
     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'

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-274
  vms_sys.show_intrusion() routine


  ...   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)
   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
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-275
  vms_sys.show_intrusion() routine


  >>> 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.5.71  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
                  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-276
  vms_sys.sndjbcw() routine


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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-277
  vms_sys.sndjbcw() routine


  $ 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 = <vmsobj_iosb, IOSB at 0x00231330>
  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
  >>> 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")

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-278
  vms_sys.sndjbcw() routine


          /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 = <vmsobj_iosb, IOSB at 0x0022d2a8>
  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
  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-279
  vms_sys.sndjbcw() routine


    -----  -------         --------     ------  ------
       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",  "PYVMS-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 = <vmsobj_iosb, IOSB at 0x0022c778>
  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
  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::
    <PYVMS-test-queue>
    /BASE_PRIORITY=4 /JOB_LIMIT=5 /OWNER=[G1,SYSTEM]
    /PROTECTION=(S:M,O:D,G:R,W:S) /RETAIN=ERROR /WSQUOTA=5000
  $


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-280
  vms_sys.sndjbcw() routine


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

  -- 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 = <vmsobj_iosb, IOSB at 0x0022cc60>
  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 "<stdin>", line 1, in ?
  ValueError: itmlst - unknown item code: SJC$_ERR
  >>>

  >>> itmlst = ('SJC$_BATCH',)
  >>> # <vmsobj_iosb or
  >>> dict = vms_sys.sndjbcw (None, "SJC$_CREATE_QUEUE", None, \
  ...                         itmlst, 'X')
  >>> # <vmsobj_iosb> or None expected -^
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 5: iosb - must be vmsobj_iosb or None
  >>>


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-281
  vms_sys.sndjbcw() routine


  >>> itmlst = ('SJC$_BATCH',)
  >>> dict = vms_sys.sndjbcw (None, "BAD_FUNC", None, itmlst)
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  ValueError: argument 2: not a valid function code: SJC$_BATCH
  >>>

  @@ more SNDJBCW examples
  >>>

  31-MAR-1999 ZE.
  ------------------------------------------------------------------------



  2.5.72  SUBSYSTEM - Subsystem

  Format:

      oldflg = vms_sys.subsystem ([enbflg])

  Returns:

  oldflg
          This  is  the  'condition  value  returned'  from  the  system
          service.   The  values  of  'SS$_WASSET'  or  'SS$_WASCLR' are
          returned as numbers 0 or 1 -  other  conditions  result  in  a
          Python exception.

  Arguments:

  enbflg
          Value specifying whether the protected  subsystem  identifiers
          are to be saved (=0) or restored (=1).

  Examples:

  >>> import vms_sys

  >>> vms_sys.subsystem (1)
  0
  >>> vms_sys.subsystem (0)
  1
  >>> vms_sys.subsystem (None)

  >>> vms_sys.subsystem ()

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-282
  vms_sys.subsystem() routine


  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: function requires exactly 1 argument; 0 given

  >>> vms_sys.subsystem ('X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: enbflg - must be integer or None
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.73  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.
  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!

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-283
  vms_sys.suspnd() routine


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


  >>> nonexist_pid = 9999
  >>> print vms_sys.suspnd (nonexist_pid)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> print vms_sys.suspnd (None,"NO_SUCH_PRC")
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')
  >>>

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-284
  vms_sys.suspnd() routine



  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.74  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 ()
  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-285
  vms_sys.timcon() routine


  >>>

  >>> 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 "<stdin>", 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
  >>>

  >>> o_utctim = vms_sys.timcon ("",1)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: argtim - must be long integer
  >>>

  09-JAN-1999 ZE.
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-286
  vms_sys.trnlnm() routine


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

  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 *

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-287
  vms_sys.trnlnm() routine


  ...   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)
  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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-288
  vms_sys.trnlnm() routine



  >>> 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"
    "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)    ,

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-289
  vms_sys.trnlnm() routine


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

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

  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-290
  vms_sys.trnlnm() routine


  >>>
  >>> 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.5.76  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
  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-291
  vms_sys.verify_proxy() routine



  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 "<stdin>", 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 "<stdin>", line 1, in ?
  vms_sys.error: (116311666, '%SECSRV-E-NOSUCHPROXY, no proxy record\
   matches your specification')
  >>>

  21-JAN-1999 ZE.
  ------------------------------------------------------------------------



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

      vms_sys.waitfr (efn)

  Returns:

  None

  Arguments:

  efn
          Number of the event flag for which to wait.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-292
  vms_sys.waitfr() routine


  Examples:

  >>> import vms_sys

  @@ WAITFR not yet (15-SEP-1998) tested
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.78  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

  >>> 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

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-293
  vms_sys.wake() routine


  >>> vms_sys.wake (nonexist_pid)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.wake (None,'NONEXPRC')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

  >>> vms_sys.wake (1,2)
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 2: expected read-only buffer, int found

  >>> vms_sys.wake ('X')
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: argument 1: pidadr - must be integer or None
  >>>

  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-294
  vms_sys.wfland() routine


  28-SEP-1998 ZE.
  ------------------------------------------------------------------------



  2.5.80  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.
  ------------------------------------------------------------------------
  15-AUG-1999 ZE.  (VMS_SYS.HTML)



  2.6  'VMSDEF'-related modules

  2.6.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:
              $ @DMACRO_VMS VMSDEF_DIRECTORY.MAR

          Due to a deficy in VMSDEF2MAR.COM at least one item code, even
          if it is a dummy one, MUST be present.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-295
  maintaining VMSDEF modules


  VMSDEF_$fac.MAR
          This is a file that is run  through  the  macro  assembler  by
          using the following command:
              $ @DMACRO_VMS VMSDEF_$fac.MAR

          The resulting object file (VMSDEF_$DCDEF.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:
              $ @DMACRO_VMS 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.


  ------------------------------------------------------------------------
  02-MAR-1999 ZE.



  2.6.2  vms_brkdef module

  The 'vms_brkdef' module  contains  bitmasks  and  comstants  that  are
  defined in '$BRKDEF'.  These definitions are used by:


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-296
  vms_brkdef module


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



  2.6.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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-297
  vms_dcdef module


  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.6.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.6.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'
  module.

  Related files:
  - VMSDEF_$DVIDEF.DAT
  - VMSDEF_$DVIDEF.MAR
  (See 'maintaining VMSDEF modules' for details)

  ------------------------------------------------------------------------
  28-FEB-1999 ZE.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-298
  vms_dvsdef module


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

  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-299
  vms_initdef module


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



  2.6.12  vms_kgbdef module

  The 'vms_kgbdef' module  contains  constants  and  bitmasks  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()

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-300
  vms_kgbdef module


        -  vms_sys.grantid()
        -  vms_sys.idtoasc()
        -  vms_sys.mod_holder()
        -  vms_sys.mod_ident()
        -  vms_sys.revokid()

  The  current  implementation  of  the  'vms_kgbdef'  module  uses  the
  old-style  C-tables!   Access from the 'pyvms' module is currently not
  possible.

  Related files:
  - VMSDEF_$KGBDEF.DAT
  - VMSDEF_$KGBDEF.MAR
  (See 'maintaining VMSDEF modules' for details)

  ------------------------------------------------------------------------
  01-MAR-1999 ZE.



  2.6.13  vms_lckdef module

  The 'vms_lckdef' module  contains  bitmasks  and  constants  that  are
  defined   in  '$LCKDEF'.   A  number  of  system  services  use  these
  definitions:

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


  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-301
  vms_lnmdef module


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

  ------------------------------------------------------------------------
  23-MAY-1999 ZE.



  2.6.16  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-302
  vms_namdef module


  2.6.17  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.6.18  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)

  ------------------------------------------------------------------------
  03-JUL-1999 ZE.



  2.6.19  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)

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-303
  vms_prcdef module


  ------------------------------------------------------------------------
  02-MAR-1999 ZE.



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



  2.6.21  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-304
  vms_quidef module


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



  2.6.24  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-305
  vms_rsdmdef module


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



  2.6.25  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.6.26  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.6.27  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-306
  vms_syidef module


  (See 'maintaining VMSDEF modules' for details)

  ------------------------------------------------------------------------
  02-MAR-1999 ZE.



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



  2.6.29  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.6.30  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:

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-307
  vms_xaballdef module


  - VMSDEF_$XABALLDEF.DAT
  - VMSDEF_$XABALLDEF.MAR
  (See 'maintaining VMSDEF modules' for details)

  ------------------------------------------------------------------------
  02-MAR-1999 ZE.



  2.6.31  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.6.32  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
  '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.6.33  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.

  PYVMS - Python on OpenVMS -Reference Manual                 PAGE 2-308
  vms_xabitmdef module


  Related files:
  - VMSDEF_$XABITMDEF.DAT
  - VMSDEF_$XABITMDEF.MAR
  (See 'maintaining VMSDEF modules' for details)

  ------------------------------------------------------------------------
  02-MAR-1999 ZE.



  2.6.34  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
  - VMSDEF_$XABKEYDEF.MAR
  (See 'maintaining VMSDEF modules' for details)

  ------------------------------------------------------------------------
  02-MAR-1999 ZE.



  2.6.35  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.   Please  note  that  the
  attribute names are not visible, Python's "dir()" function  will  just
  display an empty list unless the object contains any methods:

  >>> fab = pyvms.vmsobj_fab()
  >>> dir (fab)
  []
  >>>
  >>> membuf = pyvms.vmsobj__membuf(5)
  >>> dir (membuf)
  ['zero']
  >>>


  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

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-2
  VMS Objects - introduction


  name as the attribute:

  >>> # set FAB$M_GET
  >>> fab.M_GET = 1
  >>> print fab.M_GET
  1
  >>> print fab.B_FAC  # FAB$M_GET is in FAB$B_FAC
  2
  >>>


  Other, more complex datatypes will  be  described  together  with  the
  object.
  ------------------------------------------------------------------------
  03-MAR-1999 ZE.



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

  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 ()

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-3
  vmsobj_fab object


          >>> type (fab)
          <type 'vmsobj_fab'>
          >>>

          >>> print fab.CTX
          None
          >>>
          >>> print fab.L_CTX  # the in-memory address of 'fab'
          2190784
          >>> id (fab)
          2190784
          >>>

          >>> str = "CONTEXT-1"
          >>> 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
          <type 'int'> 2
          >>>


          >>> fab.L_CTX = 1
          Traceback (innermost last):
            File "<stdin>", 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.


  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-4
  vmsobj_fab object


          >>> fab = pyvms.vmsobj_fab ()
          >>> type (fab)
          <type 'vmsobj_fab'>
          >>>
          >>> t_dna = 'A.DAT'
          >>> fab.DNA = t_dna
          >>> str = fab.DNA
          >>> type (t_dna), id (t_dna)
          (<type 'string'>, 2183816)
          >>> type (str), id (str)
          (<type 'string'>, 2183816)
          >>>
          >>> fab.L_DNA
          2183836
          >>> 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 "<stdin>", line 1, in ?
          ValueError: string length limited to 255 characters
          >>>
          >>> fab.DNA = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: attribute must be string or None
          >>>
          >>> fab.L_DNA = 2
          Traceback (innermost last):
            File "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-5
  vmsobj_fab object


          attribute  "L_NAM"  returns  the memory address of the OpenVMS
          NAM.

          >>> fab = pyvms.vmsobj_fab ()
          >>> type (fab)
          <type 'vmsobj_fab'>
          >>>
          >>> print fab.NAM
          None
          >>> print fab.L_NAM
          0
          >>>
          >>> nam = pyvms.vmsobj_nam ()
          >>> type (nam)
          <type 'vmsobj_nam'>
          >>>
          >>>
          >>> fab.NAM = nam
          >>> fab.NAM
          <vmsobj_nam, NAM at 0x001ab0b0>
          >>> hex (fab.L_NAM)
          '0x1ab0b0'
          >>>
          >>>
          >>> fab.NAM = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_nam object or None
          >>>
          >>> fab.L_NAM = 2
          Traceback (innermost last):
            File "<stdin>", 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)
          <type 'vmsobj_fab'>
          >>>
          >>> print fab.XAB
          None
          >>> print fab.L_XAB
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-6
  vmsobj_fab object


          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>
          >>>
          >>> fab.XAB = xaball
          >>> fab.XAB
          <vmsobj_xaball, XABALL at 0x0021a330>
          >>> hex (fab.L_XAB)
          '0x21a330'
          >>>
          >>>
          >>> # remove XAB from FAB
          >>> fab.XAB = None
          >>> print fab.XAB
          None
          >>> print fab.L_XAB
          0
          >>>


          >>> fab.XAB = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> fab.L_XAB = 2
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          AttributeError: read-only vmsobj_fab attribute
          >>>


  ------------------------------------------------------------------------
  Creation:

  For now the 'pyvms' module contains a function to explicitly create  a
  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)
  <type 'vmsobj_fab'>

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-7
  vmsobj_fab object


  >>> fab
  <vmsobj_fab, FAB at 0x001acbf8>
  >>>


  >>> # invalid attribute access
  >>> fab.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_fab attribute
  >>> fab.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ..  @@
  ------------------------------------------------------------------------
  11-FEB-1999 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
          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

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-8
  vmsobj_iosb object


          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)
  <type 'vmsobj_iosb'>
  >>> iosb
  <vmsobj_iosb, IOSB at 0x00218530>
  >>>

  >>> iosb.b0
  0
  >>> iosb.w1
  0
  >>> iosb.l1
  0
  >>> iosb.q
  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'

  PYVMS - Python on OpenVMS -Reference Manual                   PAGE 3-9
  vmsobj_iosb object


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


  >>> iosb.b0 = 'X'
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: vms__cvt_py2bin(): data of item must be integer
  >>>
  >>> iosb.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_iosb attribute
  >>>
  >>> iosb.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ..  @@

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-10
  vmsobj_iosb object


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

  ------------------------------------------------------------------------
  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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-11
  vmsobj_lksb object


  <type 'vmsobj_lksb'>
  >>> lksb
  <vmsobj_lksb, LKSB at 0x00218530>
  >>>

  >>> 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)
  >>> lksb.q
  48358647401807873L
  >>>


  >>> lksb.b0 = 'X'
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: vms__cvt_py2bin(): data of item must be integer
  >>>
  >>> lksb.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_lksb attribute
  >>>
  >>> lksb.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-12
  vmsobj_lksb object


  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 PYVMS 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",
          "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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-13
  vmsobj_nam object


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


  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-14
  vmsobj_nam object


  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)
  <type 'vmsobj_nam'>
  >>> nam
  <vmsobj_nam, NAM at 0x001acbf8>
  >>>


  >>> # invalid attribute access
  >>> nam.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_nam attribute
  >>> nam.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ..  @@
  ------------------------------------------------------------------------
  11-FEB-1999 ZE.



  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  PYVMS
  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.
                                 --------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-15
  vmsobj_rab object


  ------------------------------------------------------------------------
  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)
          <type 'vmsobj_rab'>
          >>>

          >>> print rab.CTX
          None
          >>>
          >>> print rab.L_CTX  # the in-memory address of 'rab'
          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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-16
  vmsobj_rab object


          >>>

          >>> rab.CTX = 2      # other type are possible
          >>> ctx_o = rab.CTX
          >>> print type(ctx_o), ctx_o
          <type 'int'> 2
          >>>


          >>> rab.L_CTX = 1
          Traceback (innermost last):
            File "<stdin>", 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)
          <type 'vmsobj_rab'>
          >>>
          >>> fab = pyvms.vmsobj_fab ()
          >>> type (fab)
          <type 'vmsobj_fab'>
          >>> rab.FAB = fab
          >>> f2 = rab.FAB
          >>> fab
          <vmsobj_fab, FAB at 0x001ad9f8>
          >>> f2
          <vmsobj_fab, FAB at 0x001ad9f8>
          >>>
          >>> 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 "<stdin>", line 1, in ?
          AttributeError: read-only vmsobj_rab attribute

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-17
  vmsobj_rab object


          >>>
          >>> rab.FAB = 'X'
          Traceback (innermost last):
            File "<stdin>", 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
          'key'
          >>> rab.PBF = None
          >>> print rab.KBF
          None
          >>> rab.L_KBF
          0
          >>> rab.B_KSZ
          0
          >>>
          >>> rab.B_KSZ = 1
          Traceback (innermost last):
            File "<stdin>", 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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-18
  vmsobj_rab object


          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!


          @@
           6.16  RAB$L_RBF Field

            When a program invokes a service that writes records to
            a file, the output record buffer address (RBF) field contains
            the symbolic address of the buffer that holds the record to
            be written. The record size field (RAB$W_RSZ) specifies the
            size of the record buffer.

            When you invoke the Get or Read service, RMS sets this field
            to the address of the record just read from the file; you do not
            need to initialize this field. The record's address can be based
            on whether the program specifies locate mode (RAB$V_
            LOC). For locate mode, the address can be within an RMS
            buffer; otherwise, the address is in the user buffer (RAB$L_
            UBF) provided by the program.

           6.24  RAB$L_UBF Field

            The user record buffer address (UBF) field indicates the
            location of a record or block buffer.

                                            Note

                When you invoke the Get service, RMS takes control
                of the record buffer and can modify it. RMS returns
                the record size and only guarantees the contents from
                where it accessed the record to the completion of the
                record.


            This field contains the symbolic address of a work area
            (buffer) within your program. The size of this buffer must be
            defined in the RAB$W_USZ (user record area size) field.

            When you invoke a Get service, this field must contain the
            buffer address, regardless of the record transfer mode (locate
            or move). This option also applies when you invoke the Read
            service for block I/O. However, a Put or Write service never
            needs a user buffer.


          The buffer space is hidden behind a  'vmsobj__membuf'  object.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-19
  vmsobj_rab 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
              <vmsobj__membuf, buffer at 0x002165b8>
              >>> rab.RBF
              <vmsobj__membuf, buffer at 0x002165b8>
              >>>

           *  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
              <vmsobj__membuf, buffer at 0x002145f8>
              >>> membuf = rab.RBF
              >>> membuf
              <vmsobj__membuf, buffer at 0x002145f8>
              >>> 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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-20
  vmsobj_rab object


  XAB
          There  is  currently  no  appropriate  XAB  object  for   this
          attribute,  so  this  attribute  is non-functional.  RAB$L_XAB
          only accepts a XABTRM and a XABRU (on  OpenVMS  VAX  V6.1  and
          perhaps later versions of OpenVMS Alpha).

          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:

  >>> import pyvms

  >>> # create a vmsobj_rab object
  >>>
  >>> rab = pyvms.vmsobj_rab ()
  >>> type (rab)
  <type 'vmsobj_rab'>
  >>> rab
  <vmsobj_rab, RAB at 0x001dcc08>
  >>>


  >>> # invalid attribute access
  >>> rab.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_rab attribute
  >>> rab.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ..  @@
  ------------------------------------------------------------------------
  11-FEB-1999 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  PYVMS  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-21
  vmsobj_xaball object


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

  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)
          <type 'vmsobj_xaball'>
          >>>
          >>> print xaball.NXT
          None
          >>> print xaball.L_NXT
          0
          >>>
          >>> # this example uses a XABDAT
          >>> xabdat = pyvms.vmsobj_xabdat ()
          >>> type (xabdat)
          <type 'vmsobj_xabdat'>
          >>>
          >>>
          >>> xaball.NXT = xabdat
          >>> xabdat
          <vmsobj_xabdat, XABDAT at 0x001ea898>
          >>> xaball.NXT
          <vmsobj_xabdat, XABDAT at 0x001ea898>
          >>> hex (xaball.L_NXT)
          '0x1ea898'
          >>>
          >>>
          >>> xaball.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xaball.L_NXT = 2

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-22
  vmsobj_xaball object


          Traceback (innermost last):
            File "<stdin>", 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

  >>> # create a vmsobj_xaball object
  >>>
  >>> xaball = pyvms.vmsobj_xaball ()
  >>> type (xaball)
  <type 'vmsobj_xaball'>
  >>> xaball
  <vmsobj_xaball, XABALL at 0x0021a628>
  >>>


  >>> # invalid attribute access
  >>> xaball.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xaball attribute
  >>> xaball.no_attr
  Traceback (innermost last):
    File "<stdin>", 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  PYVMS  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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-23
  vmsobj_xabdat object


  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 - 128-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 XABDAT.   Remember  that
          each XAB contains a "NXT" / "L_NXT" attribute to build a chain
          of multiple XABs.

          >>> xabdat = pyvms.vmsobj_xabdat ()
          >>> type (xabdat)
          <type 'vmsobj_xabdat'>
          >>>
          >>> print xabdat.NXT
          None
          >>> print xabdat.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>
          >>>
          >>> xabdat.NXT = xaball
          >>> xaball
          <vmsobj_xaball, XABALL at 0x0021a368>
          >>> xabdat.NXT
          <vmsobj_xaball, XABALL at 0x0021a368>
          >>> hex (xabdat.L_NXT)
          '0x21a368'
          >>>
          >>>
          >>> xabdat.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xabdat.L_NXT = 2
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          AttributeError: read-only vmsobj_xabdat attribute

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-24
  vmsobj_xabdat object


          >>>



  ------------------------------------------------------------------------
  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 ()
  >>> type (xabdat)
  <type 'vmsobj_xabdat'>
  >>> xabdat
  <vmsobj_xabdat, XABDAT at 0x001eaa78>
  >>>


  >>> # invalid attribute access
  >>> xabdat.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabdat attribute
  >>> xabdat.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ------------------------------------------------------------------------
  Use:

  >>> import pyvms
  >>>
  >>> fab = pyvms.vmsobj_fab()
  >>> fab.FNA = 'dcc_vms.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)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-25
  vmsobj_xabdat object


  '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 PYVMS documentation will 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)
          <type 'vmsobj_xabfhc'>
          >>>
          >>> print xabfhc.NXT
          None
          >>> print xabfhc.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>
          >>>
          >>> xabfhc.NXT = xaball

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-26
  vmsobj_xabfhc object


          >>> xaball
          <vmsobj_xaball, XABALL at 0x0021db98>
          >>> xabfhc.NXT
          <vmsobj_xaball, XABALL at 0x0021db98>
          >>> hex (xabfhc.L_NXT)
          '0x21db98'
          >>>
          >>>
          >>> xabfhc.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xabfhc.L_NXT = 2
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          AttributeError: read-only vmsobj_xabfhc attribute
          >>>



  ------------------------------------------------------------------------
  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)
  <type 'vmsobj_xabfhc'>
  >>> xabfhc
  <vmsobj_xabfhc, XABFHC at 0x001f0dd0>
  >>>


  >>> # invalid attribute access
  >>> xabfhc.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabfhc attribute
  >>> xabfhc.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ..  @@
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-27
  vmsobj_xabfhc object


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

  ------------------------------------------------------------------------
  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-28
  vmsobj_xabitm object


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

          >>>
          >>> item_list = \
          ...   (
          ...    ('XAB$_NET_BLOCK_COUNT','BAD'),
          ...    ('XAB$_NET_BUFFER_SIZE',)
          ...   )
          >>>
          >>> xabitm.ITEMLIST = item_list
          Traceback (innermost last):
            File "<stdin>", 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 "<stdin>", line 1, in ?
          TypeError: itemlist must be a tuple of strings, \
           tuples (string,data) or None
          >>>

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-29
  vmsobj_xabitm object


          >>> xabitm.L_ITEMLIST = 2
          Traceback (innermost last):
            File "<stdin>", 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)
          <type 'vmsobj_xabitm'>
          >>>
          >>> print xabitm.NXT
          None
          >>> print xabitm.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>
          >>>
          >>> xabitm.NXT = xaball
          >>> xaball
          <vmsobj_xaball, XABALL at 0x002210c8>
          >>> xabitm.NXT
          <vmsobj_xaball, XABALL at 0x002210c8>
          >>> hex (xabitm.L_NXT)
          '0x2210c8'
          >>>
          >>>
          >>> xabitm.NXT = None
          >>> xabitm.L_NXT
          0
          >>>
          >>> xabitm.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xabitm.L_NXT = 2
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          AttributeError: read-only vmsobj_xabitm attribute
          >>>


  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-30
  vmsobj_xabitm object


  ------------------------------------------------------------------------
  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)
  <type 'vmsobj_xabitm'>
  >>> xabitm
  <vmsobj_xabitm, XABITM at 0x002213f8>
  >>>


  >>> # invalid attribute access
  >>> xabitm.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabitm attribute
  >>> xabitm.no_attr
  Traceback (innermost last):
    File "<stdin>", 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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-31
  vmsobj_xabitm object


  ...   #
  ...   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 = \
  ...     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  PYVMS  documentation  will  neither  list all possible
  attributes (although you can  find  them  by  looking  into  the  file

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-32
  vmsobj_xabkey object


  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.

          >>> xabkey = pyvms.vmsobj_xabkey ()
          >>> type (xabkey)
          <type 'vmsobj_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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-33
  vmsobj_xabkey object


          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: attribute must be string or None
          >>>
          >>> xabkey.L_KNM = 2
          Traceback (innermost last):
            File "<stdin>", 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)
          <type 'vmsobj_xabkey'>
          >>>
          >>> print xabkey.NXT
          None
          >>> print xabkey.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>


          >>> xabkey.NXT = xaball
          >>> xaball
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> xabkey.NXT
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> hex (xabkey.L_NXT)
          '0x221568'
          >>>


          >>> xabkey.NXT = None
          >>> print xabkey.NXT
          None
          >>> xabkey.L_NXT
          0
          >>>


          >>> xabkey.NXT = 0
          Traceback (innermost last):

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-34
  vmsobj_xabkey object


            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xabkey.L_NXT = 2
          Traceback (innermost last):
            File "<stdin>", 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
  >>>
  >>> xabkey = pyvms.vmsobj_xabkey ()
  >>> type (xabkey)
  <type 'vmsobj_xabkey'>
  >>> xabkey
  <vmsobj_xabkey, XABKEY at 0x00221668>
  >>>


  >>> # invalid attribute access
  >>> xabkey.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabkey attribute
  >>> xabkey.no_attr
  Traceback (innermost last):
    File "<stdin>", 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  PYVMS  documentation  will neither list all

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-35
  vmsobj_xabpro object


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

          A read operation results in a new Python  string.   Note  that
          ACLs contain binary information.

          You must not provide a buffer that is bigger that 512 bytes or
          the  read  operation  will fail with an SS$_BADATTR@@ error in
          FAB$L_STV.  The ACP-QIO interface that RMS uses is limited  to
          this  amount  (ATR$C_READACL).  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.

          An example can be found in file [.DEMO.RMS]READ_ACL.TXT

  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-36
  vmsobj_xabpro object


          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)
          <type 'vmsobj_xabpro'>
          >>>
          >>> print xabpro.NXT
          None
          >>> print xabpro.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>


          >>> xabpro.NXT = xaball
          >>> xaball
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> xabpro.NXT
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> hex (xabpro.L_NXT)
          '0x221568'
          >>>


          >>> xabpro.NXT = None
          >>> print xabpro.NXT
          None
          >>> xabpro.L_NXT
          0
          >>>


          >>> xabpro.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xabpro.L_NXT = 2
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          AttributeError: read-only vmsobj_xabpro attribute
          >>>



  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-37
  vmsobj_xabpro object


  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)
  <type 'vmsobj_xabpro'>
  >>> xabpro
  <vmsobj_xabpro, XABPRO at 0x00221668>
  >>>


  >>> # invalid attribute access
  >>> xabpro.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabpro attribute
  >>> xabpro.no_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: no_attr
  >>>

  ..  @@
  ------------------------------------------------------------------------
  28-JUN-1999 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 PYVMS 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 - 128-bit datatype)

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-38
  vmsobj_xabrdt object


  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)
          <type 'vmsobj_xabrdt'>
          >>>
          >>> print xabrdt.NXT
          None
          >>> print xabrdt.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>


          >>> xabrdt.NXT = xaball
          >>> xaball
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> xabrdt.NXT
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> hex (xabrdt.L_NXT)
          '0x221568'
          >>>


          >>> xabrdt.NXT = None
          >>> print xabrdt.NXT
          None
          >>> xabrdt.L_NXT
          0
          >>>


          >>> xabrdt.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None
          >>>
          >>> xabrdt.L_NXT = 2
          Traceback (innermost last):

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-39
  vmsobj_xabrdt object


            File "<stdin>", 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

  >>> # create a vmsobj_xabrdt object
  >>>
  >>> xabrdt = pyvms.vmsobj_xabrdt ()
  >>> type (xabrdt)
  <type 'vmsobj_xabrdt'>
  >>> xabrdt
  <vmsobj_xabrdt, XABRDT at 0x00221668>
  >>>


  >>> # invalid attribute access
  >>> xabrdt.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabrdt attribute
  >>> xabrdt.no_attr
  Traceback (innermost last):
    File "<stdin>", 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  PYVMS  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

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-40
  vmsobj_xabsum object


  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.

          >>> xabsum = pyvms.vmsobj_xabsum ()
          >>> type (xabsum)
          <type 'vmsobj_xabsum'>
          >>>
          >>> print xabsum.NXT
          None
          >>> print xabsum.L_NXT
          0
          >>>
          >>> # this example uses a XABALL
          >>> xaball = pyvms.vmsobj_xaball ()
          >>> type (xaball)
          <type 'vmsobj_xaball'>
          >>>


          >>> xabsum.NXT = xaball
          >>> xaball
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> xabsum.NXT
          <vmsobj_xaball, XABALL at 0x00221568>
          >>> hex (xabsum.L_NXT)
          '0x221568'
          >>>


          >>> xabsum.NXT = None
          >>> print xabsum.NXT
          None
          >>> xabsum.L_NXT
          0
          >>>


          >>> xabsum.NXT = 0
          Traceback (innermost last):
            File "<stdin>", line 1, in ?
          TypeError: must be a vmsobj_xabXXX object or None

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-41
  vmsobj_xabsum object


          >>>
          >>> xabsum.L_NXT = 2
          Traceback (innermost last):
            File "<stdin>", 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:

  >>> import pyvms

  >>> # create a vmsobj_xabsum object
  >>>
  >>> xabsum = pyvms.vmsobj_xabsum ()
  >>> type (xabsum)
  <type 'vmsobj_xabsum'>
  >>> xabsum
  <vmsobj_xabsum, XABSUM at 0x00221668>
  >>>


  >>> # invalid attribute access
  >>> xabsum.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj_xabsum attribute
  >>> xabsum.no_attr
  Traceback (innermost last):
    File "<stdin>", 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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-42
  vmsobj__access_names object


  The following routines create an object:

        -  vms_lib.get_accnam()
        -  vms_lib.get_accnam_by_context()
        -  vms_sys.get_security()


  The following routines acceppt this 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 "<stdin>", line 1, in ?
  ValueError: string length limited to 65535 characters
  >>>
  >>> accnam [2] = 1
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: must be a string or None
  >>>

  >>> print accnam [3]
  DELETE
  >>> accnam [3] = None
  >>> print accnam [3]
  None

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-43
  vmsobj__access_names object


  >>> print accnam [4]
  CONTROL
  >>> del (accnam [4])
  >>> print accnam [4]
  None
  >>>

  >>> print accnam [30]
  None
  >>> print accnam [31]
  None
  >>> print accnam [32]
  Traceback (innermost last):
    File "<stdin>", 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 "<stdin>", line 1, in ?
  ValueError: accnam_ass_slice: remaining code not implemented
  >>>

  ..  @@
  ------------------------------------------------------------------------
  11-AUG-1999 ZE.



  3.0.15  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:

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-44
  vmsobj__membuf object


  buffer
          Returns the contents of the buffer as a Python string  object.
          WARNING!  The buffer can contain control characters (including
          0).

          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
          >>> membuf.buffer
          'abc123'
          >>> # overwrite contents
          >>> membuf.zero()
          >>> # show updated contents
          >>> 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.

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-45
  vmsobj__membuf object


  Examples:

  >>> import pyvms

  >>> # create a zero-filled buffer
  >>>
  >>> membuf = pyvms.vmsobj__membuf (5)
  >>> type (membuf)
  <type 'vmsobj__membuf'>
  >>> membuf
  <vmsobj__membuf, buffer at 0x00213f78>
  >>> membuf.size
  5
  >>> membuf.buffer
  '\000\000\000\000\000'
  >>>


  >>> # create a string-filled buffer
  >>>
  >>> membuf = pyvms.vmsobj__membuf ('data')
  >>> type (membuf)
  <type 'vmsobj__membuf'>
  >>> membuf
  <vmsobj__membuf, buffer at 0x00214628>
  >>> membuf.size
  4
  >>> membuf.buffer
  'data'
  >>>


  >>> # invalid attribute access
  >>> membuf.bad_attr
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing vmsobj__membuf attribute
  >>>
  >>> membuf.size = 9
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing or readonly vmsobj__membuf attribute
  >>> membuf.buffer = 'x'
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing or readonly vmsobj__membuf attribute
  >>> membuf.no_attr = 0
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  AttributeError: non-existing or readonly vmsobj__membuf attribute
  >>>

  ..  @@
  ------------------------------------------------------------------------

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-46
  vmsobj__membuf object


  12-AUGR-1999 ZE.



  3.0.16  vmsobj__ownership_names object

  The vmsobj__ownership_names object provides high-level ownership to an
  OpenVMS 'ownership name table'.

  The following routinee acceppts 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
  >>>

  >>> 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 "<stdin>", line 1, in ?
  ValueError: string length limited to 65535 characters
  >>>
  >>> ownnam [2] = 1
  Traceback (innermost last):
    File "<stdin>", line 1, in ?
  TypeError: must be a string or None
  >>>

  >>> print ownnam [3]
  WORLD
  >>> ownnam [3] = None
  >>> print ownnam [3]

  PYVMS - Python on OpenVMS -Reference Manual                  PAGE 3-47
  vmsobj__ownership_names object


  None
  >>> print ownnam [2]
  G_R_O_U_P
  >>> del (ownnam [2])
  >>> print ownnam [2]
  None
  >>>

  >>> print ownnam [10]
  Traceback (innermost last):
    File "<stdin>", 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):
    File "<stdin>", line 1, in ?
  ValueError: ownnam_ass_slice: remaining code not implemented
  >>>

  ..  @@
  ------------------------------------------------------------------------
  12-AUG-1999 ZE.

  Index                                                     PAGE INDEX-1
   


                                  INDEX



  files                                 VMSDEF_$RSDMDEF.DAT, 2-304
    VMSDEF_$BRKDEF.DAT, 2-296           VMSDEF_$RSDMDEF.MAR, 2-304
    VMSDEF_$BRKDEF.MAR, 2-296           VMSDEF_$SJCDEF.DAT, 2-305
    VMSDEF_$CIADEF.DAT, 2-296           VMSDEF_$SJCDEF.MAR, 2-305
    VMSDEF_$CIADEF.MAR, 2-296           VMSDEF_$STATEDEF.DAT, 2-305
    VMSDEF_$DCDEF.DAT, 2-297            VMSDEF_$STATEDEF.MAR, 2-305
    VMSDEF_$DCDEF.MAR, 2-297            VMSDEF_$SYIDEF.DAT, 2-305
    VMSDEF_$DMTDEF.DAT, 2-297           VMSDEF_$SYIDEF.MAR, 2-305
    VMSDEF_$DMTDEF.MAR, 2-297           VMSDEF_$TRMDEF.DAT, 2-306
    VMSDEF_$DVIDEF.DAT, 2-297           VMSDEF_$TRMDEF.MAR, 2-306
    VMSDEF_$DVIDEF.MAR, 2-297           VMSDEF_$UAIDEF.DAT, 2-306
    VMSDEF_$DVSDEF.DAT, 2-298           VMSDEF_$UAIDEF.MAR, 2-306
    VMSDEF_$DVSDEF.MAR, 2-298           VMSDEF_$XABALLDEF.DAT, 2-306
    VMSDEF_$FABDEF.DAT, 2-298           VMSDEF_$XABALLDEF.MAR, 2-307
    VMSDEF_$FABDEF.MAR, 2-298           VMSDEF_$XABFHCDEF.DAT, 2-307
    VMSDEF_$FSCNDEF.DAT, 2-298          VMSDEF_$XABFHCDEF.MAR, 2-307
    VMSDEF_$FSCNDEF.MAR, 2-298          VMSDEF_$XABITMDEF.DAT, 2-308
    VMSDEF_$INITDEF.DAT, 2-299          VMSDEF_$XABITMDEF.MAR, 2-308
    VMSDEF_$INITDEF.MAR, 2-299          VMSDEF_$XABKEYDEF.DAT, 2-308
    VMSDEF_$JPIDEF.DAT, 2-299           VMSDEF_$XABKEYDEF.MAR, 2-308
    VMSDEF_$JPIDEF.MAR, 2-299           VMSDEF_$XABPRODEF.DAT, 2-308
    VMSDEF_$KGBDEF.DAT, 2-300           VMSDEF_$XABPRODEF.MAR, 2-308
    VMSDEF_$KGBDEF.MAR, 2-300
    VMSDEF_$LCKDEF.DAT, 2-300         logical names
    VMSDEF_$LCKDEF.MAR, 2-300           creation, 2-107, 2-137
    VMSDEF_$LNMDEF.DAT, 2-301           deletion, 2-50, 2-152
    VMSDEF_$LNMDEF.MAR, 2-301           retrieval, 2-286
    VMSDEF_$MAILDEF.DAT, 2-301          SYS$CURRENCY, 2-33
    VMSDEF_$MAILDEF.MAR, 2-301          SYS$DIGIT_SEP, 2-54
    VMSDEF_$MNTDEF.DAT, 2-301           SYS$LANGUAGE, 2-90
    VMSDEF_$MNTDEF.MAR, 2-301           SYS$LP_LINES, 2-93
    VMSDEF_$NAMDEF.DAT, 2-302           SYS$RADIX_POINT, 2-99
    VMSDEF_$NAMDEF.MAR, 2-302
    VMSDEF_$OSSDEF.DAT, 2-302         privileges
    VMSDEF_$OSSDEF.MAR, 2-302           BYPASS, 2-230
    VMSDEF_$PRCDEF.DAT, 2-302           CMKRNL, 2-242
    VMSDEF_$PRCDEF.MAR, 2-302           PSWAPM, 2-259
    VMSDEF_$PRVDEF.DAT, 2-303           SYSNAM, 2-137, 2-141, 2-152,
    VMSDEF_$PRVDEF.MAR, 2-303               2-242
    VMSDEF_$PSCANDEF.DAT, 2-303
    VMSDEF_$PSCANDEF.MAR, 2-303
    VMSDEF_$QUIDEF.DAT, 2-304         symbols
    VMSDEF_$QUIDEF.MAR, 2-304           creation, 2-110
    VMSDEF_$RABDEF.DAT, 2-304           deletion, 2-53
    VMSDEF_$RABDEF.MAR, 2-304           retrieval, 2-88