(go to: table of contents, index)
None
Arguments:
Format:
vms_lib.currency() does not take any arguments.
Examples:
vms_lib.date_time() does not take any arguments.
Examples:
None
Arguments:
None
Arguments:
vms_lib.digit_sep() does not take any arguments.
Examples:
Format:
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:
Format:
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:
None
Arguments:
Format:
Format:
@@ As of 01-MAR-1998 this function has not been tested in a VMScluster.
Format:
Format:
vms_lib.get_common() does not take any arguments.
Examples:
Format:
vms_lib.get_ef() does not take any arguments.
Examples:
vms_lib.users_language() does not take any arguments.
Examples:
vms_lib.lp_lines() does not take any arguments.
Examples:
Format:
Format:
None
Arguments:
vms_lib.radix_point() does not take any arguments.
Examples:
Format:
None
Arguments:
Format:
None
Arguments:
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:
None
Arguments:
None
Arguments:
12-AUG-1998 ZE.
ADD_TIMES - Add Two Quadword Times
Format:
resultant_time = vms_lib.add_times (time1, time2)
Returns:
Arguments:
See 'Programming', 'special OpenVMS datatypes' for details.
See 'Programming', 'special OpenVMS datatypes' for details.
>>> 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
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:
Arguments:
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
ATTACH - Attach Terminal to Process
Format:
vms_lib.attach (process_id)
Returns:
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
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:
Arguments:
>>> 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:
Arguments:
See 'Programming', 'special OpenVMS datatypes' for details.
Examples:
(year, month, day, hour, minute, second, hundredth)
>>> 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')
>>>
DATE_TIME - Date and Time Returned as a String
Format:
date_time_string = vms_lib.date_time ()
Returns:
Arguments:
>>> 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'
DAY - Day Number Returned as a Longword Integer
Format:
number_of_days, day_time = vms_lib.day ([user-time])
Returns:
Arguments:
('17-NOV-1858 00:00:00.00').
Examples:
See 'Programming', 'special OpenVMS datatypes' for details.
If the argument is not present, then the current date + time is used.
>>> 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:
Arguments:
1 = Monday through 7 = Sunday
See 'Programming', 'special OpenVMS datatypes' for details.
If the argument is not present, then the current date + time is used.
>>> 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:
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_*
$
DELETE_SYMBOL - Delete CLI Symbol
Format:
vms_lib.delete_symbol (symbol [,table-type-indicator])
Returns:
>>> 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:
Arguments:
>>> 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!
vms_lib.do_command (command-string)
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!
status, acp_status, filespec = \
vms_lib.fid_to_name (device_name, file_id [,directory_id])
Returns:
Arguments:
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'!
symbol_value, status = \
vms_lib.find_image_symbol (filename, symbol [,image_name])
Returns:
Arguments:
Examples:
no device, type, version
default = 'SYS$SHARE:.EXE'
>>> 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:
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:
Arguments:
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.
ctx_out, item_value = \
vms_lib.getjpi (item_name, pid_ctx [,process_name])
Arguments:
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.
import vms_quidef, vms_lib
result = vms_lib.getqui (function_code, item_name, \
search_number, search_name, search_flags)
Returns:
Arguments:
>>> 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.
import vms_syidef, vms_lib
ctx_out, item_value = vms_lib.getsyi (item_name, \
csid_ctx [,node_name])
Returns:
Arguments:
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:
Arguments:
Examples:
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.
>>> import vms_lib
>>> # (text that is entered is either in italics or underlined)
>>> vms_lib.get_command ()
GET_COMMON - Get String from Common
resultant_string, resultant_length = vms_lib.get_common ()
Returns:
Arguments:
>>> 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).
event_flag_number = vms_lib.get_ef ()
Returns:
Arguments:
>>> 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 ()
...
GET_FOREIGN - Get Foreign Command Line
Format:
resultant_string, flags_out = vms_lib.get_foreign \
([prompt_string] [,flags])
Returns:
Arguments:
Please check the examples and read the documentation for more details!
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 ('$.')
GET_SYMBOL - Get Value of CLI Symbol
Format:
resultant_string, table_type = vms_lib.get_symbol (symbol)
Returns:
Arguments:
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'>
GET_USERS_LANGUAGE - Return the User's Language
Format:
users_language = vms_lib.users_language ()
Returns:
Arguments:
>>> 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' !
LP_LINES - Lines on Each Printer Page
Format:
lp_line_count = vms_lib.lp_lines ()
Returns:
Arguments:
>>> 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
resultant_length = vms_lib.put_common (source_string)
Returns:
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
>>>
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.
vms_lib.put_output (message_string)
Returns:
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:
Arguments:
>>> 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.
vms_lib.reserve_ef (event_flag_number)
Returns:
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')
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.
vms_lib.run_program (program_name)
Returns:
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
SET_LOGICAL - Set Logical Name
This routine is used to set a supervisor-mode logical name.
dict = vms_lib.set_logical (logical-name, [value-string] [,table] \
[,attributes] [,item-list])
Returns:
Arguments:
Examples:
>>> import vms_lib
>>> import os # only for testing
SET_SYMBOL - Set Value of CLI Symbol
Format:
vms_lib.set_symbol (symbol, value-string [,table-type-indicator])
Returns:
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:
Arguments:
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Examples:
See 'Programming', 'special OpenVMS datatypes' for details.
See 'Programming', 'special OpenVMS datatypes' for details.
>>> 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
WAIT - Wait a Specified Period of Time
Format:
vms_lib.wait (seconds)
Returns:
Examples:
>>> import vms_lib
>>> vms_lib.wait (5.5)
>>> delay = 3
>>> wait_returns = vms_lib.wait (delay)
>>> print wait_returns
None
>>>