vms_lib module

(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index)

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


Format:
    resultant_time = vms_lib.add_times (time1, time2)
Returns:
resultant_time
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Arguments:
time1 + time2
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Examples:
>>> import vms_lib
>>> import vms_sys        # needed for ascii/integer conversion

>>> time1 = vms_sys.bintim ('29-FEB-2000 12:34:56.78')
>>> print time1
44585444967800000L

>>> time2 = vms_sys.bintim ('0 01:02:03.11')
>>> print time2
-37231100000L

>>> resultant_time = vms_lib.add_times (time1, time2)
>>> print resultant_time
44585482198900000L
>>> vms_sys.asctim (resultant_time);
'29-FEB-2000 13:36:59.89'

>>> vms_sys.asctim (time1);
'29-FEB-2000 12:34:56.78'
>>> resultant_time = vms_lib.add_times (time1, time1)
Traceback (innermost last):
  File "<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 ?
ValueError: argument 1: must be long int

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

>>> 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 ?
ValueError: argument 2: must be long int
>>>

ASN_WTH_MBX - Assign Channel with Mailbox


Format:
    device-channel, mailbox-channel= vms_lib.asn_wth_mbx \
        (device-name, [maximum-message-size] [,buffer-quota])
Returns:
device-channel
channel to device, received from SYS$ASSIGN
mailbox-channel
channel to mailbox, received from SYS$CREMBX
Arguments:
device-name
name of device that will be passed to SYS$ASSIGN
maximum-message-size
maximum message size that can be sent to the mailbox
buffer-quota
number of system dynamic memory bytes that can be used to buffer messages sent to the mailbox
Examples:
>>> import vms_lib

>>> devchn, mbxchn = vms_lib.asn_wth_mbx ("TT")
>>> print devchn, mbxchn
240 224

>>> print vms_lib.getdvi ("DVI$_DEVNAM", devchn)
_FTA13:
>>> print vms_lib.getdvi ("DVI$_DEVNAM", mbxchn)
_MBA233:

(Note: the device name argument is ommited in vms_lib.getdvi())

$ show device/full _MBA233:
Device MBA233: is online, record-oriented device, shareable,
 mailbox device.

  Error count                0    Operations completed              0
  Owner process             ""    Owner UIC             [HOME,ZESSIN]
  Owner process ID    00000000    Dev Prot          S:RWPL,O:RWPL,G,W
  Reference count            2    Default buffer size             256


>>> devchn, mbxchn = vms_lib.asn_wth_mbx("TT",44,33)
>>> print devchn, mbxchn
240 224
>>> print vms_lib.getdvi ("DVI$_DEVNAM", mbxchn)
_MBA241:
>>>

$ show device/full _MBA241:
Device MBA241: is online, record-oriented device, shareable,
 mailbox device.

  Error count                0    Operations completed              0
  Owner process             ""    Owner UIC             [HOME,ZESSIN]
  Owner process ID    00000000    Dev Prot          S:RWPL,O:RWPL,G,W
  Reference count            2    Default buffer size              44
                                                                   **

>>> # 1st call
>>> devchn, mbxchn = vms_lib.asn_wth_mbx("TT")
>>> # 2nd call
>>> devchn, mbxchn = vms_lib.asn_wth_mbx("TT")
Traceback (innermost last):
  File "<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')
>>>

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

CREATE_DIR - Create a Directory


@@ Oops, left out - will be filled in, later

Format:

  LIB$CREATE_DIR  device-directory-spec
                        [,owner-UIC] [,protection-enable]
                        [,protection-value] [,maximum-versions]
                        [,relative-volume-number]

CURRENCY - Get System Currency Symbol


Format:
    currency_string = vms_lib.currency ()
Returns:
currency_string
The value of the logical name 'SYS$CURRENCY' or, if the translation fails the default currency symbol ($).
Arguments:

vms_lib.currency() does not take any arguments.

Examples:

>>> import vms_lib

>>> currency_string = vms_lib.currency()
>>> currency_string
'$'

$ DEFINE SYS$CURRENCY "C&"
>>> vms_lib.currency()
'C&'

* don't forget to use '$ DEASSIGN SYS$CURRENCY' !

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

CVT_VECTIM - Convert 7-Word Vector to Internal Time


Format:
    resultant_time = vms_lib.cvt_vectim (input_time)
Returns:
resultant_time
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Arguments:
input_time
a tuple that consists of:
(year, month, day, hour, minute, second, hundredth)
Examples:
>>> import vms_lib

>>> input_time = (2000, 2, 29, 12, 34, 56, 78)
>>> resultant_time = vms_lib.cvt_vectim (input_time)
>>> print resultant_time
44585444967800000L
>>> import vms_sys
>>> print vms_sys.asctim (resultant_time)
29-FEB-2000 12:34:56.78

>>> resultant_time = vms_lib.cvt_vectim ((2000, 2, 29, 12, 34, 56, 78))
>>> print vms_sys.asctim (resultant_time)
29-FEB-2000 12:34:56.78

>>> # a tuple is required as argument 1 - not seven arguments
>>> resultant_time = vms_lib.cvt_vectim (2000, 2, 29, 12, 34, 56, 78)
Traceback (innermost last):
  File "<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')
>>>

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

>>> # tuple element 2 out of range ------------vvvvv
>>> resultant_time = vms_lib.cvt_vectim ((2000,65536,29,12,34,56,78))
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: tuple-element:n is not a 16-bit integer
>>>

>>> # tuple element 2 is invalid ---------------v
>>> resultant_time = vms_lib.cvt_vectim ((2000,'X',29,12,34,56,78))
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: tuple-element:n is not an integer
>>>

DATE_TIME - Date and Time Returned as a String


Format:
    date_time_string = vms_lib.date_time ()
Returns:
date_time_string
Returns the date current date and time as a 23 character string. Format: 'dd-mmm-yyyy hh:mm:ss.hh'.
Arguments:

vms_lib.date_time() does not take any arguments.

Examples:

>>> import vms_lib

>>> date_time_string = vms_lib.date_time ()
>>> date_time_string
' 2-NOV-1997 16:23:21.93'

* Note that there can be a space character at the begin!

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

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

DAY - Day Number Returned as a Longword Integer


Format:
    number_of_days, day_time = vms_lib.day ([user-time])
Returns:
number_of_days
The number of days since the system zero date
('17-NOV-1858 00:00:00.00').
day_time
The number of 10-millisecond units since midnight of the user_time argument.
Arguments:
user-time
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
If the argument is not present, then the current date + time is used.
Examples:
>>> import vms_lib
>>> import vms_sys

>>> binary_time = vms_sys.bintim ('29-FEB-2000 01:02:03.04')
>>> binary_time
44585029230400000L

>>> number_of_days, day_time = vms_lib.day (binary_time)
>>> number_of_days
51603
>>> day_time
372304

>>> vms_lib.day (binary_time)
(51603, 372304)

>>> vms_lib.day (vms_sys.gettim ())
(51037, 5151320)

>>> vms_lib.day ()
(51037, 5152244)

>>> vms_lib.day (None)
(51037, 5153719)

>>> vms_lib.day ('A')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be long int

>>> vms_lib.day ('A','B')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: function requires at most 1 argument; 2 given
>>>

DAY_OF_WEEK - Show Numeric Day of Week


Format:
    day_number = vms_lib.day_of_week ([user-time])
Returns:
day_number
Numeric day of week.
1 = Monday through 7 = Sunday
Arguments:
user-time
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
If the argument is not present, then the current date + time is used.
Examples:
>>> import vms_lib
>>> import vms_sys

>>> weekday_list = [0,'Monday','Tuesday','Wednesday','Thursday',
... 'Friday','Saturday','Sunday']

>>> binary_time = vms_sys.bintim ('29-FEB-2000 01:02:03.04')
>>> binary_time
44585029230400000L

>>> vms_lib.day_of_week (binary_time)
2
>>> day_number = vms_lib.day_of_week (binary_time)
>>> day_number
2
>>> print weekday_list[day_number]
Tuesday

$ WRITE SYS$OUTPUT F$CVTIME("29-FEB-2000 01:02:03.04",,"WEEKDAY")
Tuesday

$ WRITE SYS$OUTPUT F$TIME()
12-AUG-1998 14:54:54.50
$ WRITE SYS$OUTPUT F$CVTIME(F$TIME(),,"WEEKDAY")
Wednesday

>>> vms_lib.day_of_week (vms_sys.gettim ())
3
>>> vms_lib.day_of_week ()
3
>>> vms_lib.day_of_week (None)
3

>>> vms_lib.day_of_week ('A')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be long int

>>> vms_lib.day_of_week ('A', 'B')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: function requires at most 1 argument; 2 given
>>>

DELETE_LOGICAL - Delete Logical Name


Format:
    vms_lib.delete_logical (logical-name [,table-name])
Returns:

None

Arguments:

logical-name
The logical name to be deleted.
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_*
$

>>> 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 string, int found
>>>

DELETE_SYMBOL - Delete CLI Symbol


Format:
    vms_lib.delete_symbol (symbol [,table-type-indicator])
Returns:

None

Arguments:

symbol
Name of the symbol to be deleted.
table-type-indicator
"GLOBAL" or "LOCAL", this is _not_ a numeric value as in LIB$DELETE_SYMBOL but a clear text name. This parameter is optional. The default value is "LOCAL".
Examples:
>>> import vms_lib

$ VMS_LIB_SYM_DEFAULT = "VALUE_DEFAULT"
$ VMS_LIB_SYM_NONE    = "VALUE_NONE"
$ VMS_LIB_SYM_GLOBAL  == "VALUE_GLOBAL"
$ VMS_LIB_SYM_LOCAL   = "VALUE_LOCAL"

>>> vms_lib.delete_symbol ('VMS_LIB_SYM_GLOBAL', 'GLOBAL')
>>> vms_lib.delete_symbol ('VMS_LIB_SYM_LOCAL',  'LOCAL')
>>> vms_lib.delete_symbol ('VMS_LIB_SYM_NONE',   None)
>>> vms_lib.delete_symbol ('VMS_LIB_SYM_DEFAULT')
$ show symbol VMS_LIB_SYM_*
%DCL-W-UNDSYM, undefined symbol - check validity and spelling
$

>>> # maximum length of symbol name is 255 characters
>>> symbol_name = 'S' * 256
>>> vms_lib.delete_symbol (symbol_name, 'GLOBAL')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name')
>>>

>>> vms_lib.delete_symbol ('SYMBOL', 'BAD')
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', 'GLOBAL')
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 string, int found
>>>

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

DIGIT_SEP - Get Digit Separator Symbol


Format:
    digit_separator = vms_lib.digit_sep ()
Returns:
digit_separator
The digit separator symbol as returned by LIB$DIGIT_SEP.
Arguments:

vms_lib.digit_sep() does not take any arguments.

Examples:

>>> import vms_lib

>>> digit_sep_symbol = vms_lib.digit_sep ()
>>> digit_sep_symbol
','

$ DEFINE SYS$DIGIT_SEP "C&"
>>> vms_lib.digit_sep()
'C&'

* don't forget to use '$ DEASSIGN SYS$DIGIT_SEP' !

>>> vms_lib.digit_sep ('S')
Traceback (innermost last):
  File "<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
>>>

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

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

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

FID_TO_NAME - Convert Device and File ID to File Specification


Please note that You MUST check status and/or acp_status because FID_TO_NAME() does NOT raise an exception when something goes wrong!

Format:

    status, acp_status, filespec = \
        vms_lib.fid_to_name (device_name, file_id [,directory_id])
Returns:
status
The return-status from LIB$FID_TO_NAME.
acp_status
The status resulting from traversing the backward links.
filespec
The resulting file specification string.
Arguments:
device_name
Name of the device on which the file resides. (64 characters or less!)
file_id
The file identifier. This is a tuple of 3 (16-bit) integers.
directory_id
The directory file identifier. Please read the description of LIB$FID_TO_NAME for details.
Examples:
$ COPY _NLA0: TEST.TMP
$ DIRECTORY /FILE_ID TEST.TMP

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

TEST.TMP;1           (12621,13,0)

Total of 1 file.

$ python
... (Python's banner ommitted) ...
>>> import vms_lib

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

>>> import os
>>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')'
>>> os.system (command)
%SYSTEM-S-NORMAL, normal successful completion  <-- [1]
65537                                           <-- [2]
>>>

    [1] this is the output of 'command'
    [2] this is the return status from os.system()
        65537 = %RMS-S-NORMAL, normal successful completion

>>> status, acp_status, filespec = vms_lib.fid_to_name (
... 'DKA100:', (12621,13,999))
>>> print status, acp_status, filespec
2456 2456 DISK$D1:
>>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')'
>>> os.system (command)
%SYSTEM-W-NOTVOLSET, volume is not part of a volume set
65537
>>>

>>> status, acp_status, filespec = vms_lib.fid_to_name (
... 'DKA100:', (12621,999,0))
>>> print status, acp_status, filespec
2320 2320 DISK$D1:
>>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')'
>>> os.system (command)
%SYSTEM-W-NOSUCHFILE, no such file
65537
>>>

>>> status, acp_status, filespec = vms_lib.fid_to_name (
... 'DKA100:', (12621,99999,0))
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: tuple-element:n is not a 16-bit integer
>>> status, acp_status, filespec = vms_lib.fid_to_name (
... 'DKA100:', (12621,'X',0))
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: tuple-element:n is not an integer
>>> status, acp_status, filespec = vms_lib.fid_to_name ('DKA100:', 'X')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: must be a tuple of 3 integers
>>>

>>> status, acp_status, filespec = vms_lib.fid_to_name (
... 'DKA100:', (12621,13,0), (12621,99,0))
>>> print status, acp_status, filespec
>>> command = 'WRITE SYS$OUTPUT F$MESSAGE(' + str(status) + ')'
>>> os.system (command)
%SYSTEM-W-NOSUCHFILE, no such file
1
>>>

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

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

GETDVI - Get Device/Volume Information


Format:
    import vms_dvidef, vms_lib
    item_value = vms_lib.getdvi \
        (item_name, channel_number [,device_name])
Returns:
item_value
Return information requested from 'item_name'. Note: this can be an integer _or_ a string value. 'Boolean' values (TRUE/FALSE) are returned as integers 1/0.
Arguments:
item_name
Text-string of item to retrieve (e.g. 'DVI$_OWNUIC').
channel_number
I/O channel, assigned to the device about which the information should be retrieved. Use 'None' to skip the channel parameter and use device_name instead.
device_name
Name of device to get information about. Note: normally channel_number overrides device_name! Use channel_number = 'None' to force usage of device_name.
Examples:
>>> import vms_lib

>>> vms_lib.getdvi ("DVI$_OWNUIC",None,"DKA100:")
'[G1,SYSTEM]'

>>> vms_lib.getdvi ("DVI$_LOGVOLNAM",None,"DKA100:")
'DISK$D1'

>>> vms_lib.getdvi ("DVI$_FREEBLOCKS",None,"DKA100:")
528888
>>> vms_lib.getdvi ("DVI$_FREEBLOCKS",32,None)
528888
>>> vms_lib.getdvi ("DVI$_FREEBLOCKS",32)
528888

* 32 is a channel number that was learned via SDA> show process/channel

>>> used_blocks = vms_lib.getdvi ("DVI$_MAXBLOCK",None,"DKA100:") - \
... vms_lib.getdvi ("DVI$_FREEBLOCKS",None,"DKA100:")
>>> used_blocks
1562256

>>> vms_lib.getdvi ("DVI$_TT_HOSTSYNC",None,"SYS$COMMAND:")
1    <-- means TRUE
>>> vms_lib.getdvi ("DVI$_TT_DIALUP",None,"SYS$COMMAND:")
0    <-- means FALSE

>>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,"SYS$COMMAND:")
'_HERE$FTA10:'

>>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,"NO_DEVICE")
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_lib.error: (324, '%SYSTEM-F-IVDEVNAM, invalid device name')

>>> vms_lib.getdvi ("INVALID_ITEM",None,"SYS$COMMAND:")
Traceback (innermost last):
  File "<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 number must be integer or None

>>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,None)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_lib.error: (316, '%SYSTEM-F-IVCHAN, invalid I/O channel')

>>> vms_lib.getdvi ("DVI$_FULLDEVNAM",None,1)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 3: device_name must be string or None

>>> vms_lib.getdvi ('DVI$_LOGVOLNAM',None,sys)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: device_name must be string or None
>>>

GETJPI - Get Job/Process Information


Note: the 'vms_jpidef' module contains constants and bitmasks that are defined in '$JPIDEF'. Access to the item-codes ("JPI$_name") is possible via the 'pyvms' module.

Format:

    ctx_out, item_value = \
        vms_lib.getjpi (item_name, pid_ctx [,process_name])
Returns:
ctx_out
pid of the target process or a pid-context that can be used for the next step in a wildcard lookup
item_value
Return information requested from 'item_name'. Note: all items are returned as string values _except_ for item 'PID' which is always returned as integer. This eases wildcard lookups and other usages.
Arguments:
item_name
Text-string of item to retrieve (e.g. 'JPI$_BIOLM').
pid_ctx
PID of process to lookup or context-value for the next wildcard lookup.
process_name
Name of process to lookup. Note: normally pid_ctx overrides process_name! Use pid_ctx = 'None' to force usage of process_name.
Examples:
>>> import vms_lib

>>> pid, state = vms_lib.getjpi ('JPI$_STATE',0)
>>> pid, state
(232, 'CUR')

>>> vms_lib.getjpi ('JPI$_PRCNAM',65)
(65, 'SWAPPER')

>>> vms_lib.getjpi ('JPI$_PID',None,'DEST_PROC')
(1058, 1058)

>>> vms_lib.getjpi ('JPI$_PRCNAM',1058)
(1058, 'DEST_PROC')

>>> vms_lib.getjpi ('JPI$_PID',1234)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_lib.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')

>>> vms_lib.getjpi ('JPI$_PID',sys)
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: process_name must be string or None

>>> vms_lib.getjpi ('JPI$_PID',None,1)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 3: process_name must be string or None

*** example of wildcard lookup ***

>>> ctx = -1
>>> while 1:
...         ctx,pid = vms_lib.getjpi ('JPI$_PID',ctx)
...         x,pn = vms_lib.getjpi ('JPI$_PRCNAM',pid)
...         x,li = vms_lib.getjpi ('JPI$_LOGINTIM',pid)
...         print ctx,pid,pn,li,'\n'
... #-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')
>>>
The date of 10-MAR-1996 is not faked! This really is one of the oldest examples.

GETQUI - Get Queue Information


Note: the 'vms_quidef' module contains constants and bitmasks that are defined in '$QUIDEF'. Access to the item-codes ("QUI$_name") is possible via the 'pyvms' module.

Format:

    import vms_quidef, vms_lib
    result = vms_lib.getqui (function_code, item_name, \
        search_number, search_name, search_flags)
Returns:
result
Return information requested from 'item_name'.
Arguments:
function_code
Text-string of function to perform (e.g. 'QUI$_CANCEL_OPERATION' or 'QUI$_DISPLAY_ENTRY').
item_name
Text-string of item to retrieve (e.g. 'QUI$_JOB_NAME').
search_number
Numeric value (e.g. an entry number) used to process the request. Use 'None' to signal an empty parameter.
search_name
Character string (e.g. a queue name) used to process the request.
search_flags
Optional bit mask. Constants are containted in the vms_quidef module (e.g. vms_quidef.QUI_M_SEARCH_ALL_JOBS).
Examples:
>>> import vms_quidef, vms_lib

>>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_JOB_NAME",5)
'X2'
>>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_PRIORITY",5)
100
>>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_NOTE",5)
''
>>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_QUEUE_NAME",5)
'HERE_BACKUP'
>>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_MANAGER_NAME",
...     None,"HERE_SYSTEM")
'SYS$QUEUE_MANAGER'
>>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_PENDING_JOB_COUNT",
...     None,"HERE_SYSTEM")
0
>>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_PENDING_JOB_COUNT",
...     None,"UUCP_BATCH")
2
>>> vms_lib.getqui ("QUI$_DISPLAY_QUEUE","QUI$_AUTOSTART_ON",None,
...     "HERE_SYSTEM")
''
>>> vms_lib.getqui ("QUI$_DISPLAY_ENTRY","QUI$_NOTE",9999)
Traceback (innermost last):
  File "<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 number or None

*** example of wildcard lookup ***

>>> import vms_quidef, vms_lib
>>> vms_lib.getqui ("QUI$_CANCEL_OPERATION")
>>> while 1:
...     queue_name = ''
...     try:
...         queue_name = vms_lib.getqui("QUI$_DISPLAY_QUEUE",
...           "QUI$_QUEUE_NAME",None,'*')
...     except vms_lib.error:
...         break
...     queue_desc = vms_lib.getqui("QUI$_DISPLAY_QUEUE",
...       "QUI$_QUEUE_DESCRIPTION",None,'*',
...       vms_quidef.QUI_M_SEARCH_FREEZE_CONTEXT)
...     print 'Queue:', queue_name, '<', queue_desc, '>'
...     while 1:
...         try:
...             js = vms_lib.getqui("QUI$_DISPLAY_JOB",
...                 "QUI$_JOB_STATUS",-1,'*',
...                 vms_quidef.QUI_M_SEARCH_ALL_JOBS)
...         except vms_lib.error:
...             break
...         jn = vms_lib.getqui("QUI$_DISPLAY_JOB",
...             "QUI$_JOB_NAME",-1,'*',
...             vms_quidef.QUI_M_SEARCH_ALL_JOBS+
...             vms_quidef.QUI_M_SEARCH_FREEZE_CONTEXT)
...         en = vms_lib.getqui("QUI$_DISPLAY_JOB",
...             "QUI$_ENTRY_NUMBER",-1,'*',
...             vms_quidef.QUI_M_SEARCH_ALL_JOBS+
...             vms_quidef.QUI_M_SEARCH_FREEZE_CONTEXT)
...         print 'Job:', jn, '(', en, ')'
... #end
...
Queue: BATQ_BACKUP <  >
Queue: BATQ_BATCH <  >
Job: Q ( 833 )
Job: Q ( 834 )
Queue: BATQ_RAYTRACE01 <  >
Queue: BATQ_RAYTRACE02 <  >
Queue: BATQ_SYSTEM <  >
Job: Q ( 832 )
Queue: HERE_BACKUP <  >
Queue: HERE_BATCH <  >
Queue: HERE_RAYTRACE01 < Raytracing, PRIO:1 >
Queue: HERE_RAYTRACE02 < Raytracing, PRIO:2 >
Queue: HERE_SYSTEM <  >
Queue: UUCP_BATCH < UUCP Daemons and Administrative Processing >
Job: UUXQT_BATCH ( 753 )
Job: UUXQT_BATCH ( 761 )
Job: UUXQT_BATCH ( 784 )
>>> vms_lib.getqui("QUI$_CANCEL_OPERATION")
>>> vms_lib.getqui("QUI$_CANCEL_OPERATION")
>>> queue_name = vms_lib.getqui("QUI$_DISPLAY_QUEUE",
...             "QUI$_QUEUE_NAME",None,'*')
>>> queue_name = vms_lib.getqui("QUI$_DISPLAY_QUEUE",
...             "QUI$_QUEUE_NAME",None,'*')
>>> print 'Queue:', queue_name, '<', queue_desc, '>'
Queue: BATQ_BATCH <  >
>>> # (queue does not have a description)
>>> vms_lib.getqui ("QUI$_CANCEL_OPERATION")
>>>

GETSYI - Get Systemwide Information


Note: the 'vms_syidef' module contains constants and bitmasks that are defined in '$SYIDEF'. Access to the item-codes ("SYI$_name") is possible via the 'pyvms' module.

@@ As of 01-MAR-1998 this function has not been tested in a VMScluster.

Format:

    import vms_syidef, vms_lib
    ctx_out, item_value = vms_lib.getsyi (item_name, \
        csid_ctx [,node_name])
Returns:
csid_ctx
cluster system id (CSID) of nodename or a csid-context that can be used for the next step in a wildcard lookup
item_value
Return information requested from 'item_name'. Note: whenever possible items are returned as integer values. This eases wildcard lookups and other usages. 'Boolean' values (TRUE/FALSE) are returned as integers 1/0.
Arguments:
item_name
Text-string of item to retrieve (e.g. 'SYI$_NODENAME').
csid_ctx
cluster system id (CSID) of nodename to lookup or context-value for the next wildcard lookup.
node_name
Name of node to retrieve information from. Note: normally csid_ctx overrides node_name! Use csid_ctx = 'None' to force usage of node_name.
Examples:
>>> import vms_syidef, vms_lib

>>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',0)
>>> csid, item
(0, 'HERE')

>>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,'HERE')
(-2, 'HERE')

>>> vms_lib.getsyi ("SYI$_PAGFILCNT",0)
(0, 4)

>>> vms_lib.getsyi ("SYI$_NODE_SWTYPE",0)
(0, 'VMS ')
>>> vms_lib.getsyi ("SYI$_VERSION",0)
(0, 'V6.1    ')

>>> vms_lib.getsyi ("SYI$_RMS_GBLBUFQUO",0)
(0, 1024)

>>> vms_lib.getsyi (sys,0)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: expected string, 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 number or None

>>> csid, item = vms_lib.getsyi ('SYI$_NODENAME',None,sys)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 3: expected string, module found
>>>

GET_COMMAND - Get Line from SYS$COMMAND


Format:
    data_from_command, resultant_length = \
        vms_lib.get_command ([prompt] [,buffer_length])
Returns:
data_from_command
String that LIB$GET_COMMAND gets from SYS$COMMAND.
resultant_length
Length of 'data_from_command'.
Arguments:
prompt
Prompt message to be displayed. Optional.
buffer_length
This argument is optional, default=65535.
By specifying buffer_length you can limit the input that LIB$GET_COMMAND accepts. If string truncation occured, then 'resultant_length' is negative to indicate this! This behaviour is different than LIB$GET_COMMAND.
Examples:
>>> import vms_lib

>>> # (text that is entered is either in italics or underlined)
>>> vms_lib.get_command ()
input-text<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
>>>

GET_COMMON - Get String from Common


Retrieves a maximum of 252 characters from the common area. This includes the \0 character. The data is stored with vms_lib.put_common() in the common area.

Format:

    resultant_string, resultant_length = vms_lib.get_common ()
Returns:
resultant_string
A copy of the data that was stored by vms_lib.put_common() in the common area.
resultant_length
Number of characters that were retrieved from the common area.
Arguments:

vms_lib.get_common() does not take any arguments.

Examples:

>>> import vms_lib

>>> data = '1234ABC'
>>> length_put = vms_lib.put_common (data)
>>> print length_put
7

>>> resultant_string, resultant_length = vms_lib.get_common ()
>>> print resultant_string
1234ABC
>>> print len (resultant_string)
7
>>> print resultant_length
7
>>>

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:

vms_lib.get_ef() does not take any arguments.

Examples:

>>> import vms_lib

>>> event_flag_number = vms_lib.get_ef ()
>>> print event_flag_number
62
>>> print vms_lib.get_ef ()
61

>>> # event flags 1 - 23 are initially reserved
>>> #  (compatibility to the RSX operating system)
>>> vms_lib.free_ef (1)
>>> print vms_lib.get_ef ()
60

>>> while (1):
...     print vms_lib.get_ef ()
... 
59
58
  ...
33
32
1
Traceback (innermost last):
  File "<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)

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
the 'flags' argument of LIB$GET_FOREIGN is passed 'by reference' because it can be modified. 'flags_out' returns the value from 'flags' after the call to LIB$GET_FOREIGN.
Please check the examples and read the documentation for more details!
Arguments:
prompt_string
Optional text which is used for prompting when no command line is available.
flags
Please read the documentation to understand the usage of this argument.
Examples:
-----
$ python
Python 1.5.1 (V001, May  8 1998, 19:23:14) [DECC] on vms
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
portions Copyright 1996-1998 Uwe Zessin
>>> import vms_lib
>>> print vms_lib.get_foreign ()
('', 0)

>>> # (text that is entered is either in italics or underlined)
>>> print vms_lib.get_foreign ('$.')
$.data<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)
$

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

GET_SYMBOL - Get Value of CLI Symbol


Format:
    resultant_string, table_type = vms_lib.get_symbol (symbol)
Returns:
resultant_string
contents of 'symbol'
table-type-indicator
"GLOBAL" or "LOCAL" - this is _not_ a numeric value as in LIB$GET_SYMBOL. It is a text string.
Arguments:
symbol
name of the symbol
Examples:
>>> import vms_lib

>>> print vms_lib.get_symbol ('$STATUS')
('%X00000001', 'GLOBAL')
>>>

>>> symbol, table = vms_lib.get_symbol ('$STATUS')
>>> print symbol, '-', table
%X00000001 - GLOBAL
>>>

>>> t = vms_lib.get_symbol ('$STATUS')
>>> t
('%X00000001', 'GLOBAL')
>>> type(t)
<type 'tuple'>

>>> print vms_lib.get_symbol ('$STATUS')[0]
%X00000001
>>>

>>> 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 string, int found

>>> vms_lib.get_symbol (None)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: expected string, None found
>>>

GET_USERS_LANGUAGE - Return the User's Language


Format:
    users_language = vms_lib.users_language ()
Returns:
users_language
Translation of the logical name "SYS$LANGUAGE". If the translation fails, then 'ENGLISH' is returned.
Arguments:

vms_lib.users_language() does not take any arguments.

Examples:

>>> import vms_lib

>>> users_language = vms_lib.get_users_language ()
>>> users_language 
'ENGLISH'

$ DEFINE SYS$LANGUAGE "GERMAN"
>>> vms_lib.get_users_language ()
'GERMAN'

* don't forget to use '$ DEASSIGN SYS$LANGUAGE' !

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

LP_LINES - Lines on Each Printer Page


Format:
    lp_line_count = vms_lib.lp_lines ()
Returns:
lp_line_count
The default number of lines on a physical printer page. If the logical name ("LIB$LP_LINES") translation or conversion to binary fails, a default value of 66 is returned.
Arguments:

vms_lib.lp_lines() does not take any arguments.

Examples:

>>> import vms_lib

>>> lp_line_count = vms_lib.lp_lines ()
>>> lp_line_count
66

$ DEFINE SYS$LP_LINES "_INVALID_"
>>> vms_lib.lp_lines ()
66

$ DEFINE SYS$LP_LINES "72"
>>> vms_lib.lp_lines ()
72

* don't forget to use '$ DEASSIGN SYS$LP_LINES' !

>>> vms_lib.lp_lines ('S')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: function requires no arguments
>>>

PUT_COMMON - Put String to Common


Stores a maximum of 252 characters into the common area. This includes the \0 character. The data can be retrieved with vms_lib.get_common().

Format:

    resultant_length = vms_lib.put_common (source_string)
Returns:
resultant_length
The actual number of characters copied to the common area - maximum = 252.
Arguments:
source_string
Source string to be copied to the common area.
Examples:
>>> import vms_lib

>>> data = '1234ABC'
>>> length_put = vms_lib.put_common (data)
>>> print length_put
7

>>> resultant_string, resultant_length = vms_lib.get_common ()
>>> print resultant_string
1234ABC
>>> print len (resultant_string)
7
>>> print resultant_length
7
>>>

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

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

vms_lib.radix_point() does not take any arguments.

Examples:

>>> import vms_lib

>>> radix_point_string = vms_lib.radix_point ()
>>> radix_point_string
'.'

$ DEFINE SYS$RADIX_POINT ","
>>> vms_lib.radix_point ()
','

$ DEFINE SYS$RADIX_POINT "XYZ"
>>> vms_lib.radix_point ()
'XYZ'

* don't forget to use '$ DEASSIGN SYS$RADIX_POINT' !

>>> vms_lib.radix_point ('S')
Traceback (innermost last):
  File "<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
>>>

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

RUN_PROGRAM - Run New Program


Note that you will not be returned to Python. Not even when the program you wish to run does not exist! Please read the documentation for details.

Format:

    vms_lib.run_program (program_name)
Returns:

None

Arguments:

program_name
File name of the program to run in place of the current program (Python).
Examples:
>>> import vms_lib

>>> vms_lib.run_program ('SYS$SYSTEM:NCP.EXE')
NCP>

>>> vms_lib.run_program ('')
$

>>> vms_lib.run_program (None)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: expected string, None found

>>> vms_lib.run_program ('no-file')
%DCL-W-ACTIMAGE, error activating image NO-FILE
-CLI-E-IMAGEFNF, image file not found
DKA100:[PYTHON.PYTHON-1.4.VMS]NO-FILE.EXE;
$

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.
Arguments:
logical-name
Logical name to be defined or redefined.
value-string
Value to be given to the logical name. For multiple values use the item-list parameter.
table
Name of the table in which to create the logical name. If omitted, LNM$PROCESS is used.
attributes
Logical name or translation attributes. Please see the VMS documentation for details.
item-list
Item list describing the equivalence names for this logical name. You can also specify 'LNM$_TABLE' as an output item.
Examples:
>>> import vms_lib
>>> import os   # only for testing

>>> vms_lib.set_logical('LNM1','VAL1')
{'status': 1}   <-- return status from LIB$SET_LOGICAL
>>> os.system ('show logical /full LNM1')
   "LNM1" [super] = "VAL1" (LNM$PROCESS_TABLE)
1               <-- return status from os.system()
>>>


>>> vms_lib.set_logical('LNM2','VAL2','LNM$JOB')
{'status': 1}   <-- return status from LIB$SET_LOGICAL
>>> os.system('show logical /full LNM2')
   "LNM2" [super] = "VAL2" (LNM$JOB_814E0700)
1               <-- return status from os.system()
>>>


>>> import vms_lnmdef
>>> vms_lib.set_logical('LNM3','VAL3','LNM$JOB',vms_lnmdef.LNM_M_CONCEALED)
{'status': 1}   <-- return status from LIB$SET_LOGICAL
>>> os.system('show logical /full LNM3')
   "LNM3" [super] = "VAL3" [concealed] (LNM$JOB_814E0700)
1               <-- return status from os.system()
>>>


>>> vms_lib.set_logical('LNM3','VAL3','LNM$JOB',vms_lnmdef.LNM_M_CONCEALED+
... vms_lnmdef.LNM_M_TERMINAL)
{'status': 1585}  <-- return status from LIB$SET_LOGICAL
>>> os.system('write sys$output f$message(1585)')
%SYSTEM-S-SUPERSEDE, logical name superseded
65537           <-- return status from os.system() due to '$WRITE'
>>>

* Note: the logical name LNM3 has been replaced


>>> vms_lib.set_logical('LNM5',None,'LNM$GROUP',None,
...   ( ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED),
...     ('LNM$_STRING','S5A'),('LNM$_STRING','S5B')
...   )
... )
{'status': 1}   <-- return status from LIB$SET_LOGICAL
>>> os.system('show logical /full LNM5')
   "LNM5" [super] = "S5A" [concealed] (LNM$GROUP_010040)
        = "S5B" [concealed]
1               <-- return status from os.system()
>>>


>>> vms_lib.set_logical('LNM6',None,'LNM$GROUP',None,
...   ( ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED),
...     ('LNM$_STRING','S6A'),
...     ('LNM$_ATTRIBUTES',0),
...     ('LNM$_STRING','S6B')
...   )
... )
{'status': 1}   <-- return status from LIB$SET_LOGICAL
>>> os.system('show logical /full LNM6')
   "LNM6" [super] = "S6A" [concealed] (LNM$GROUP_010040)
        = "S6B"
1               <-- return status from os.system()
>>>


>>> d = vms_lib.set_logical('LNM7',None,'LNM$GROUP',None,
...   ( ('LNM$_TABLE','X'),
...     ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED),
...     ('LNM$_STRING','S7A'),
...     ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED),
...     ('LNM$_STRING','S7B'),
...     ('LNM$_ATTRIBUTES',0),
...     ('LNM$_STRING','S7C')
...   )
... )
>>> d
{'LNM$_TABLE': 'LNM$GROUP_010040', 'status': 1}

-- 'LNM$_TABLE' is an output-item
-- 'status' is the condition value returned from LIB$SET_LOGICAL

>>> os.system('show logical /full LNM7')
   "LNM7" [super] = "S7A" [concealed] (LNM$GROUP_010040)
        = "S7B" [concealed]
        = "S7C"
1               <-- return status from os.system()
>>>

>>> vms_lib.set_logical('LNM8',None,'LNM$GROUP',None,
...   ( ('LNM$_ACMODE',3),
...     ('LNM$_ATTRIBUTES',vms_lnmdef.LNM_M_CONCEALED),
...     ('LNM$_STRING','S7A'),
...     ('LNM$_ATTRIBUTES',0),
...     ('LNM$_STRING','S7B')
...   )
... )
{'status': 20}  <-- return status from LIB$SET_LOGICAL
>>> os.system('write sys$output f$message(20)')
%SYSTEM-F-BADPARAM, bad parameter value
65537           <-- return status from os.system() due to '$WRITE'
>>>

SET_SYMBOL - Set Value of CLI Symbol


Format:
    vms_lib.set_symbol (symbol, value-string [,table-type-indicator])
Returns:

None

Arguments:

symbol
name of the symbol
value-string
contents of 'symbol'
table-type-indicator
"GLOBAL" or "LOCAL" - this is _not_ a numeric value as in LIB$SET_SYMBOL. You must specify a text string. This parameter is optional. The default value is "LOCAL".
Examples:
>>> import vms_lib

>>> vms_lib.set_symbol ('VMS_LIB_SYM_GLOBAL',  'VALUE_GLOBAL', 'GLOBAL')
>>> vms_lib.set_symbol ('VMS_LIB_SYM_LOCAL',   'VALUE_LOCAL',  'LOCAL')
>>> vms_lib.set_symbol ('VMS_LIB_SYM_NONE',    'VALUE_NONE',   None)
>>> vms_lib.set_symbol ('VMS_LIB_SYM_DEFAULT', 'VALUE_DEFAULT')
$ show symbol VMS_LIB_SYM_*
  VMS_LIB_SYM_DEFAULT = "VALUE_DEFAULT"        <-- local symbol
  VMS_LIB_SYM_GLOBAL == "VALUE_GLOBAL"
  VMS_LIB_SYM_LOCAL = "VALUE_LOCAL"            <-- local symbol
  VMS_LIB_SYM_NONE = "VALUE_NONE"              <-- local symbol
$

* don't forget to delete these symbols!
  $ delete/symbol/local  VMS_LIB_SYM_DEFAULT
  $ delete/symbol/global VMS_LIB_SYM_GLOBAL
  $ delete/symbol/local  VMS_LIB_SYM_LOCAL
  $ delete/symbol/local  VMS_LIB_SYM_NONE

>>> symbol_name = 'S' * 257
>>> vms_lib.set_symbol (symbol_name, 'VALUE_STRING', 'GLOBAL')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_lib.error: (1409932, '%LIB-F-INVSYMNAM, invalid symbol name')
>>>

>>> value_string = 'V' * 257
>>> vms_lib.set_symbol ('SYMBOL', value_string, 'GLOBAL')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_lib.error: (1409588, '%LIB-F-INVARG, invalid argument(s)')
>>>

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

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

SUB_TIMES - Subtract Two Quadword Times


Format:
    resultant_time = vms_lib.sub_times (time1, time2)
Returns:
resultant_time
The result of subtracting time2 from time1.
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Arguments:
time1
First time, from which LIB$SUB_TIMES subtracts the second time. 64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
time2
Second time, which LIB$SUB_TIMES subtracts from the first time. 64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Examples:
>>> import vms_lib
>>> import vms_sys    # needed for ascii/integer conversion

>>> time1 = vms_sys.bintim ('29-FEB-2000 12:34:56.78')
>>> print time1
44585444967800000L

>>> time2 = vms_sys.bintim ('0 01:02:03.11')
>>> print time2
-37231100000L

>>> time3 = vms_sys.bintim ('01-JAN-2000 12:56:34.89')
>>> print time3
44534481948900000L

>>> time4 = vms_sys.bintim ('0 04:03:02.11')
>>> print time4
-145821100000L

>>> resultant_time = vms_lib.sub_times (time1, time2)
>>> print resultant_time, vms_sys.asctim (resultant_time);
44585407736700000L 29-FEB-2000 11:32:53.67

>>> resultant_time = vms_lib.sub_times (time1, time3)
>>> print resultant_time, vms_sys.asctim (resultant_time);
-50963018900000L   58 23:38:21.89

>>> 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 ?
ValueError: argument 1: must be long int
>>>

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

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

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

(go to: table of contents, index)

12-AUG-1998 ZE.