vms_sys module

(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index)

The 'vms_sys' module provides access to some OpenVMS SYS$ routines. Most functions DO NOT return a status code; they raise the exception 'vms_sys.error' when something went wrong. Functions that behave differently have it mentioned at their description.


Alphabetical list of routines:
  • ASCTIM - Convert Binary Time to ASCII String
  • ASCTOID - Translate Identifier Name to Identifier
  • ASCUTC - Convert UTC to ASCII
  • BINTIM - Convert ASCII String to Binary Time
  • BINUTC - Convert ASCII String to UTC Binary Time
  • CANWAK - Cancel Wakeup
  • DELPRC - Delete Process
  • FORCEX - Force Exit
  • GETTIM - Returns the current system time in a 64-bit format
  • GETUTC - Get UTC Time
  • HIBER - Hibernate
  • NUMTIM - Convert Binary Time to Numeric Time
  • NUMUTC - Convert UTC Time to Numeric Components
  • PURGWS - Purge Working Set
  • RESUME - Resume Process
  • SCHDWK - Schedule Wakeup
  • SETDDIR - Set Default Directory
  • SETPRI - Set Priority
  • SETPRN - Set Process Name
  • SETSWM - Set Process Swap Mode
  • SUBSYSTEM - Subsystem
  • SUSPND - Suspend Process
  • TIMCON - Time Converter
  • WAKE - Wake Process from Hibernation


ASCTIM - Convert Binary Time to ASCII String


Format:
    timbuf = vms_sys.asctim (timadr [,cvtflg])
Returns:
timbuf
Converted Date and Time as an ASCII string.
Arguments:
timadr
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
cvtflg
Conversion indicator. Please consult the system reference manual for details.
Examples:
>>> import vms_sys

>>> vms_sys.asctim ()
'12-AUG-1998 10:32:12.47'

>>> vms_sys.asctim (None)
'12-AUG-1998 10:32:17.69'

>>> vms_sys.asctim (None,0)
'12-AUG-1998 10:32:47.51'

>>> vms_sys.asctim (None,1)
'10:33:01.12'


>>> vms_sys.asctim (0x009A0070B0CB6D60L)
'28-MAR-1996 20:50:41.59'

>>> print 0x009A0070B0CB6D60L
43347630415900000L
>>> vms_sys.asctim (43347630415900000L, 0)
'28-MAR-1996 20:50:41.59'

>>> vms_sys.asctim (0x009A0070B0CB6D60L, 1)
'20:50:41.59'

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

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

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

>>> # this is only an int, not a long int
>>> vms_sys.asctim (0x12345)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be long int

>>> # 'None' for argument 2 is not supported
>>> vms_sys.asctim (None,None)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: illegal argument type for built-in operation
>>>

ASCTOID - Translate Identifier Name to Identifier


Format:
    id, attrib = vms_sys.asctoid (name)
Returns:
id
identifier value (integer)
attrib
Attributes that are associated with the identifier. The bit values are defined in the module vms_kgbdef.
Arguments:
name
Identifier name to be translated.
Examples:
>>> import vms_sys

>>> id_value, id_attribute = vms_sys.asctoid ('SYSTEM')
>>> print 'ID-value=', id_value, 'ID-attribute=', id_attribute
ID-value= 65540 ID-attribute= 0

>>> uic_group  =  id_value / 65536
>>> uic_member =  id_value - (uic_group * 65536)
>>> uic_spec = 'UIC= [' + str(uic_group) + ',' + str(uic_member) + ']'
>>> print uic_spec
UIC= [1,4]

>>> id_name = 'BATCH'
>>> vms_sys.asctoid (id_name)
(-2147483647, 0)
>>> hex (-2147483647)
'0x80000001'

>>> import os
>>> os.system('WRITE SYS$OUTPUT F$IDENTIFIER("BATCH","NAME_TO_NUMBER")')
-2147483647	<-- output from '$ WRITE'
65537           <-- status from os.system()  = RMS$_NORMAL

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

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

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

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

ASCUTC - Convert UTC to ASCII


Format:
    timbuf = vms_sys.ascutc (utcadr [,cvtflg])
Returns:
timbuf
ASCII String
Arguments:
utcadr
128-bit UTC value - an ASCII string of 32 hex characters.
cvtflg
conversion indicator
0 = return full date and time
1 = return only hour, minute, second, hundredths-of-second
Examples:
>>> import vms_sys

>>> utc_tim = vms_sys.getutc ()
>>> print utc_tim
103CFFFFFFFFFFFF01D177D7D9B13B80
>>> print vms_sys.ascutc (utc_tim)
18-DEC-1997 19:41:52.44
>>> print vms_sys.asctim ()
18-DEC-1997 19:41:53.41

>>> utc_tim = vms_sys.binutc ('29-FEB-2000 12:34:56.78')
>>> print utc_tim
103CFFFFFFFFFFFF01D3EE9C3F46F4C0
>>> print vms_sys.ascutc (utc_tim)
29-FEB-2000 12:34:56.78

>>> print vms_sys.ascutc ()
18-DEC-1997 19:43:55.99

>>> print vms_sys.ascutc (None)
18-DEC-1997 19:44:18.72

>>> # non-hex character ---v
>>> print vms_sys.ascutc ('X03CFFFFFFFFFFFF01D177D7D9B13B80')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be 32 hex characters

>>> # string to long       12345678901234567890123456789012
>>> print vms_sys.ascutc ('103CFFFFFFFFFFFF01D177D7D9B13B80F')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be 32 hex characters

>>> # string to short      12345678901234567890123456789012
>>> print vms_sys.ascutc ('03CFFFFFFFFFFFF01D177D7D9B13B80')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be 32 hex characters

>>> # bad datatype
>>> print vms_sys.ascutc (1)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: expected read-only buffer, int found
>>>

BINTIM - Convert ASCII String to Binary Time


Format:
    timadr = vms_sys.bintim (timbuf)
Returns:
timadr
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Arguments:
timbuf
ASCII date + time to be converted.
Examples:
>>> import vms_sys

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

>>> vms_sys.asctim (44585444967800000L)
'29-FEB-2000 12:34:56.78'

>>> vms_sys.bintim ('0 01:03:04.45')
-37844500000L

>>> vms_sys.asctim (-37844500000L)
'   0 01:03:04.45'

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

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

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

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

BINUTC - Convert ASCII String to UTC Binary Time


Format:
    utcadr = vms_sys.binutc (timbuf)
Returns:
utcadr
128-bit UTC value - an ASCII string of 32 hex characters.
Arguments:
timbuf
ASCII (date +) time to be converted.
Examples:
>>> import vms_sys

>>> utc_tim = vms_sys.binutc ('29-FEB-2000 12:34:56.78')
>>> print utc_tim
103CFFFFFFFFFFFF01D3EE9C3F46F4C0
>>> print vms_sys.ascutc (utc_tim)
29-FEB-2000 12:34:56.78

>>> utc_tim = vms_sys.binutc ('30-FEB-2000 12:34:56.78')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time')

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

CANWAK - Cancel Wakeup


Removes all scheduled wakeup requests for a process from the timer queue, including those made by the caller or by other processes. The Schedule Wakeup ($SCHDWK) service makes scheduled wakeup requests.

Format:

    targpid = vms_sys.canwak ([pidadr] [,prcnam])
Returns:
targpid
Process identification of process for which wakeups have been canceled. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.canwak() raises a Python exception.
Arguments:
pidadr
Process identification of process for which wakeups are to be canceled.
prcnam
Process name of process for which wakeups are to be canceled.
Examples:
>>> import vms_sys

>>> print vms_sys.canwak ()
341			<-- CANWAK on current process

>>> print vms_sys.canwak (None,None)
341			<-- CANWAK on current process

>>> print vms_sys.canwak (387)
387
>>> vms_sys.canwak (None,'TARG_PRC')
387
>>> vms_sys.canwak (0,'TARG_PRC')
387

>>> print vms_sys.canwak (0)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')
--> Argument 1 = 0 or None means that Argument 2 should have a valid
    process name.

>>> print vms_sys.canwak (None)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (340, '%SYSTEM-F-IVLOGNAM, invalid logical name')
--> Argument 1 = 0 or None means that Argument 2 should have a valid
    process name.

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

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

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

DELPRC - Delete Process


Format:
    targpid = vms_sys.delprc ([pidadr] [,prcnam])
Returns:
targpid
Process identification of process which has been deleted - unless, of course the process has deleted itself ...
The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.delprc() raises a Python exception.
Arguments:
pidadr
Process identification of process to be deleted.
prcnam
Process name of process to be deleted.
Examples:
>>> import vms_sys

>>> print vms_sys.delprc ()
(current process is deleted)

>>> print vms_sys.delprc (None,None)
(current process is deleted)

>>> print vms_sys.delprc (353)
353
(target process is deleted + its PID is returned)

$ cmd = "import vms_sys; print 'a'; print 'b'"
$ spawn python -c "''cmd'"
%DCL-S-SPAWNED, process ZESSIN_1 spawned
%DCL-S-ATTACHED, terminal now attached to process ZESSIN_1

a
b
%DCL-S-RETURNED, control returned to process ZESSIN_FTA17
$


$ cmd = "import vms_sys; print 'a'; vms_sys.delprc (); print 'b'"
$ spawn python -c "''cmd'"
%DCL-S-SPAWNED, process ZESSIN_1 spawned
%DCL-S-ATTACHED, terminal now attached to process ZESSIN_1

a
%DCL-S-RETURNED, control returned to process ZESSIN_FTA17
$! --> 'b' is not printed because subprocess is deleted by delprc()


>>> print vms_sys.delprc (0,"TARG_PRC")
355
(target process is deleted + its PID is returned)

>>> print vms_sys.delprc (None,"TARG_PRC")
476
(target process is deleted + its PID is returned)

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

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

>>> audit_server_pid = 265
>>> print vms_sys.delprc (265)
Traceback (innermost last):
  File "", line 1, in ?
vms_sys.error: (9020, '%SYSTEM-F-NODELETE, object cannot be deleted')
>>> # the AUDIT_SERVER process cannot be deleted

FORCEX - Force Exit


Causes an Exit ($EXIT) service call to be issued on behalf of a specified process.

Format:

    targpid = vms_sys.forcex ([pidadr] [,prcnam] [,code])
Returns:
targpid
Process identification of process that has been forced to exit - unless, of course the process has forced itself to exit ...
The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.forcex() raises a Python exception.
Arguments:
pidadr
Process identification of process to be forced to exit.
prcnam
Process name of process to be forced to exit.
code
Completion code value to be used as the exit parameter.
Examples:
>>> import vms_sys

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

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

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

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

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

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

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

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

>>> print vms_sys.forcex (None,None,44)
%SYSTEM-F-ABORT, abort
$ ! current process forced to exit - 44 == SS$_ABORT

>>> pid = 360
>>> prcnam = 'TARG_PRC'
>>> print vms_sys.forcex (pid)
360			<-- this is the target PID
:TARG_PRC output:
%NONAME-W-NOMSG, Message number 00000000

>>> vms_sys.forcex (pid,None,44)
360			<-- this is the target PID
:TARG_PRC output:
%SYSTEM-F-ABORT, abort

>>> vms_sys.forcex (0,prcnam,44)
360			<-- this is the target PID
	Note that the process name was used, not PID 0.
	0 means the target process should be returned.
:TARG_PRC output:
%SYSTEM-F-ABORT, abort

Note: 'None' for Argument 1 is internally changed to 0!
>>> vms_sys.forcex (None,prcnam,44)
360			<-- this is the target PID
	Note that the process name was used, not PID 0
:TARG_PRC output:
%SYSTEM-F-ABORT, abort

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

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

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

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

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

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

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


Format:
    timadr = vms_sys.gettim ()
Returns:
timadr
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Arguments:

vms_sys.gettim() does not take any arguments.

Examples:

>>> import vms_sys

>>> vms_bintim = vms_sys.gettim ()
>>> vms_bintim
44096363555600000L

>>> vms_sys.asctim (vms_bintim)
'12-AUG-1998 10:59:15.56'

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

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

GETUTC - Get UTC Time


Returns the current time in 128-bit UTC format.

Format:

    utcadr = vms_sys.getutc ()
Returns:
utcadr
128-bit UTC value - an ASCII string of 32 hex characters.
Arguments:

vms_sys.getutc() does not take any arguments.

Examples:

>>> import vms_sys

>>> utc_tim = vms_sys.getutc ()
>>> print utc_tim
103CFFFFFFFFFFFF01D1732D81027700

>>> print vms_sys.ascutc (utc_tim)
12-DEC-1997 21:12:24.56

>>> print vms_sys.asctim ()
12-DEC-1997 21:12:25.35

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

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

HIBER - Hibernate


Allows a process to make itself inactive.

There are two ways for the hibernated process to wake up from inside the Python interpreter:

1
The process must be waked up via vms_sys.wake() or SYS$WAKE() from a different process.
2
The process uses the vms_sys.schdwk() routine.

Format:

    vms_sys.hiber ()
Returns:

None

Arguments:

vms_sys.hiber() does not take any arguments.

Examples:

>>> import vms_sys

>>> vms_sys.hiber ()

* the current process hibernates

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

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

NUMTIM - Convert Binary Time to Numeric Time


Format:
    timbuf = vms_sys.numtim ([timadr])
Returns:
timbuf
a tuple of 7 (16-bit) integers consisting of:
(year, month, day, hour, minute, second, hundredth)
Arguments:
timadr
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Examples:
>>> import vms_sys

>>> vms_sys.bintim ('29-FEB-2000 12:34:56.78')
44585444967800000L
>>> vms_sys.numtim (44585444967800000L)
(2000, 2, 29, 12, 34, 56, 78)
>>> # (year, month, day, hour, minute, second, hundredth)

>>> vms_sys.asctim ()
'12-AUG-1998 11:09:11.45'
>>> vms_sys.numtim ()
(1998, 8, 12, 11, 9, 14, 69)
>>> vms_sys.numtim (None)
(1998, 8, 12, 11, 9, 19, 69)
>>> # (year, month, day, hour, minute, second, hundredth)

>>> vms_sys.numtim (vms_sys.bintim ('0 01:02:03.45'))
(0, 0, 0, 1, 2, 3, 45)
>>> # (year, month, day, hour, minute, second, hundredth)

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

NUMUTC - Convert UTC Time to Numeric Components


Format:
    timbuf = vms_sys.numtim ([utcadr])
Returns:
timbuf
a tuple of 7 (16-bit) integers consisting of:
(year, month, day, hour, minute, second, hundredth,
inaccuracy-days, in-hours, in-minutes, in-seconds
in-hundredth, TDF-in-minutes)
Arguments:
utcadr
128-bit UTC value - an ASCII string of 32 hex characters.
Examples:
>>> import vms_sys

>>> vms_sys.binutc ('29-FEB-2000 12:34:56.78')
'103CFFFFFFFFFFFF01D3EE9C3F46F4C0'
>>> vms_sys.numutc ('103CFFFFFFFFFFFF01D3EE9C3F46F4C0')
(2000, 2, 29, 12, 34, 56, 78, -1, -1, -1, -1, -1, 60)

>>> vms_sys.asctim ()
'12-DEC-1997 21:48:11.90'
>>> vms_sys.numutc ()
(1997, 12, 12, 21, 48, 11, 94, -1, -1, -1, -1, -1, 60)
>>> vms_sys.numutc (None)
(1997, 12, 12, 21, 48, 36, 59, -1, -1, -1, -1, -1, 60)
* The tuple consists of: ( year_since_0, month_of_year, day_of_month, hour_of_day, minute_of_hour, second_of_minute, hundredths_of_second, inacc_days, inacc_hours, inacc_minutes, inacc_seconds, inacc_hundredths_of_second, tdf_in_minutes )
>>> vms_sys.numutc (vms_sys.binutc ('0 01:02:03.45'))
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (388, '%SYSTEM-F-IVTIME, invalid time')

>>> vms_sys.numutc ('X')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1 must be 32 hex characters
>>>

PURGWS - Purge Working Set


Format:
    vms_sys.purgws (start-addr, end-addr)
Returns:

None

Arguments:

start-addr
Starting virtual address of the range of pages to be purged.
end-addr
Ending virtual address of the range of pages to be purged.
Note: the original system service accepts one argument that points to two longwords in memory. The Python function requires two separate arguments, not one argument or a tuple.

Examples:

>>> import vms_sys

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

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

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

RESUME - Resume Process


Causes a process previously suspended by the Suspend Process ($SUSPND) service to resume execution or cancels the effect of a subsequent suspend request.

Format:

    targpid = vms_sys.resume ([pidadr] [,prcnam])
Returns:
targpid
Process identification of process that has been resumed.
The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.resume() raises a Python exception.
Arguments:
pidadr
Process identification of process to be resumed.
prcnam
Process name of process to be resumed.
Examples:
>>> import vms_sys

>>> print vms_sys.resume (464)
464
>>> vms_sys.resume (None,'TARG_PRC')
476
>>> vms_sys.resume (0,'TARG_PRC')
476

>>> vms_sys.resume (1,2)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: expected None or string, int found

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

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

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

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

SCHDWK - Schedule Wakeup


Schedules the awakening (restarting) of a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service.

Format:

    targpid = vms_sys.schdwk ([pidadr], [prcnam], daytim [,reptim])
Returns:
targpid
Process identification of process for which a wakeup has been scheduled.
The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.schdwk() raises a Python exception.
Arguments:
pidadr
Process identification of process for which a wakeup is to be scheduled.
prcnam
Process name of process for which a wakeup is to be scheduled.
daytim
Time at which the process is to be awakened.
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
reptim
Time interval at which the wakeup request is to be repeated.
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
Examples:
>>> import vms_sys

>>> # translate ASCII delta time to 'binary quadword' equivalent.
>>> ten_seconds = vms_sys.bintim ('0 00:00:10.00')
>>> ten_seconds
-100000000L

>>> # wait a single 10 second shot
>>> vms_sys.asctim ()
'12-AUG-1998 11:29:38.73'
>>> vms_sys.schdwk (0, None, ten_seconds)
96			<-- PID of current process
>>> vms_sys.hiber ()
>>> vms_sys.asctim ()
'12-AUG-1998 11:29:48.91'

>>> # repeated wakeup with 5 seconds interval
>>> vms_sys.asctim ()
'12-AUG-1998 11:29:49.08'
>>> vms_sys.schdwk (0, None, ten_seconds, \
...   vms_sys.bintim ('0 00:00:05.00'))
96			<-- PID of current process
>>> vms_sys.hiber ()
>>> vms_sys.asctim ()
'12-AUG-1998 11:29:59.33'
>>> vms_sys.hiber ()
>>> vms_sys.asctim ()
'12-AUG-1998 11:30:04.35'
>>> vms_sys.hiber ()
>>> vms_sys.asctim ()
'12-AUG-1998 11:30:09.33'
>>> vms_sys.canwak ()
96			<-- PID of current process
>>> vms_sys.hiber ()

--> process 'hangs' because wakeup was cancelled
    use <CONTROL-Y> to exit

>>> # None + None means this process as well as (0,None,LongInt)
>>> vms_sys.schdwk (None, None, 0xFFFFFFFFFA0A1F00L)
96			<-- PID of current process


>>> # first 'None' skips PID, second argument is process name
>>> vms_sys.schdwk (None, 'NOSUCHPROC', 0xFFFFFFFFFA0A1F00L)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (2280, '%SYSTEM-W-NONEXPR, nonexistent process')


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

>>> vms_sys.schdwk (None, None, 'not-a-long-int')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 3 must be long int

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

SETDDIR - Set Default Directory


Allows you to read and change the default directory string for the process.

Please note that the device name is stored in the logical name SYS$DISK! You can use vms_lib.set_logical() to change this logical name.

Format:

    cur-dir = vms_sys.setddir ([new-dir])
Returns:
cur-dir
Current /old default directory. Note that this is always returned!
Arguments:
new-dir
New default directory.
Examples:
>>> import vms_sys

>>> vms_sys.setddir ()
'[PYTHON.PYTHON-1.4.VMS]'
>>> vms_sys.setddir (None)
'[PYTHON.PYTHON-1.4.VMS]'
>>> vms_sys.setddir ('[-]')
'[PYTHON.PYTHON-1.3.VMS]'

* Note: setddir() returns the _old_ directory

>>> vms_sys.setddir ()
'[PYTHON.PYTHON-1.4]'

* the directory _has_ changed

>>> vms_sys.setddir (1)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: expected None or string, int found

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

>>> vms_sys.setddir ('BAD#DIRECTORY#SYNTAX#')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (100052, '%RMS-F-SYN, file specification syntax error')

>>> # only 8 levels supported
>>> vms_sys.setddir ('[----------]')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (99532, '%RMS-F-DIR, error in directory name')
>>>

SETPRI - Set Priority


Changes the base priority of the process. The base priority is used to determine the order in which executable processes are to run.

@@ Argument 4 not tested yet (23-MAY-1998) on OpenVMS Alpha.

Format:

    targpid, previous_priority, previous_policy = vms_sys.setpri (
	[pid], [prcnam], priority [, policy])
Returns:
targpid
Process identification of process for which the priority has been changed.
The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.setpri() raises a Python exception.
previous_priority
Previous process base priority.
previous_policy
Previous process policy (Alpha only - on VAX the function always returns 0 for consistency).
Arguments:
pid
Process identification of the process for which the priority and / or policy is to be changed and / or retrieved.
prcnam
Process name of the process for which the priority and / or policy is to be changed and / or retrieved.
priority
New base priority for the target process.
policy
New scheduling policy for the target process.
(Alpha only - this argument is ignored on VAX)
Examples:
>>> import vms_sys

>>> # lower priority using explicit PID
>>> print vms_sys.setpri (91,None,3)
(91, 4, 0)

>>> # set back old priority usind default PID
>>> vms_sys.setpri (0,None,4)
(91, 3, 0)

>>> vms_sys.setpri (None,None,3)
(91, 4, 0)

>>> vms_sys.setpri (None,"TARG_PRC",3)
(93, 4, 0)
 ^^ <-- PID of target process returned even if name was given

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

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

>>> vms_sys.setpri (1,2,3)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: expected None or string, int found

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

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

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

SETPRN - Set Process Name


Format:
    vms_sys.setprn ([prcnam])
Returns:

None. But you can get the current process name using vms_lib.getjpi() with the 'JPI$_PRCNAM' item code - see example below.

Arguments:

prcnam
Process name to be given to the calling process.
Examples:
$ SET PROCESS/NAME="OLD_PRCNAM"

>>> import vms_lib
>>> import vms_sys

>>> vms_lib.getjpi ('JPI$_PRCNAM',0)
(160, 'OLD_PRCNAM')
>>> vms_sys.setprn ('NEW_PRCNAM')
>>> vms_lib.getjpi ('JPI$_PRCNAM',0)
(160, 'NEW_PRCNAM')

>>> vms_sys.setprn ()
>>> vms_lib.getjpi ('JPI$_PRCNAM',0)
(160, '')

>>> # an empty argument results in a process with no name.
>>> vms_sys.setprn ('NEW_PRCNAM')
>>> vms_lib.getjpi ('JPI$_PRCNAM',0)
(160, 'NEW_PRCNAM')

>>> vms_sys.setprn (None)
>>> vms_lib.getjpi ('JPI$_PRCNAM',0)
(160, '')

>>> vms_sys.setprn (1)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: expected None or string, int found

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

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

>>> # Note: a process with the name 'DUP_PRCNAM' does
>>> #       already exist in the same UIC group.
>>> vms_sys.setprn ('DUP_PRCNAM')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
vms_sys.error: (148, '%SYSTEM-F-DUPLNAM, duplicate name')
>>>

SETSWM - Set Process Swap Mode


Format:
    oldflg = vms_sys.setswm ([swpflg])
Returns:
oldflg
This is the 'condition value returned' from the system service. The values of 'SS$_WASSET' or 'SS$_WASCLR' are returned as numbers 0 or 1 - other conditions result in a Python exception.
Arguments:
swpflg
Indicator specifying whether the process can be swapped.
Examples:
$ SET PROCESS/PRIVILEGE=PSWAPM

>>> import vms_sys

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

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

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

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

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


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

SUBSYSTEM - Subsystem


Format:
    oldflg = vms_sys.subsystem ([enbflg])
Returns:
oldflg
This is the 'condition value returned' from the system service. The values of 'SS$_WASSET' or 'SS$_WASCLR' are returned as numbers 0 or 1 - other conditions result in a Python exception.
Arguments:
enbflg
Value specifying whether the protected subsystem identifiers are to be saved (=0) or restored (=1).
Examples:
>>> import vms_sys

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

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

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

SUSPND - Suspend Process


Allows a process to suspend itself or another process. Execution can be resumed with the vms_lib.resume() service. Warning! A process that has suspended itself can only be resumed from a different one.

Format:

    targpid = vms_sys.suspnd ([pidadr] [,prcnam] [,flags])
Returns:
targpid
Process identification of process that has been suspended.
The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.suspnd() raises a Python exception.

Please note: if you do a SUSPND on your own process, then it will 'hang'. You must issue a resume() from a different process to continue. And _after that_, you will get the 'targpid' value back (which, of course, is your own PID).

Arguments:
pidadr
Process identification of process to be suspended.
prcnam
Process name of process to be suspended.
flags
Bit flags specifying options for the suspend operation.
Examples:
>>> import vms_sys

>>> # suspend current process
>>> # Note: resume can only be done from a different process!
>>> print vms_sys.suspnd ()
(process 'hangs')
91			<-- PID of current process
			it was resumed via: >>> vms_sys.resume(91)
			from a different process

>>> print vms_sys.suspnd (None)
(process 'hangs')
91			<-- PID of current process is printed after
			it was resumed via: >>> vms_sys.resume(91)
			from a different process


>>> targ_pid = 93
>>> print vms_sys.suspnd (targ_pid)
93			<-- PID of target process
			this process now 'hangs'
>>> vms_sys.resume (targ_pid)
93			<-- PID of target process
			this process now continues


>>> print vms_sys.suspnd (0,"TARG_PRC")
93			<-- PID of target process
			this process now 'hangs'
>>> vms_sys.resume (targ_pid)
93			<-- PID of target process
			this process now continues


>>> # this example uses the PID that is returned
>>> targ_pid = vms_sys.suspnd (None,"TARG_PRC")
(target process 'hangs')
>>> print targ_pid
95			<-- PID of target process
>>> vms_sys.resume (targ_pid)
95			<-- PID of target process
			this process now continues

* the flags argument cannot be used from Python because
  it runs in all user-mode code.


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

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

TIMCON - Time Converter


Converts 128-bit Coordinated Universal Time (UTC) format to 64-bit system format or 64-bit system format to 128-bit UTC format based on the value of the convert flag.

Format:

    utcadr = vms_sys.timcon ([timadr] , cvtflg=1)
    timadr = vms_sys.timcon ([utcadr] , cvtflg=0)
Returns:
timadr
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
utcadr
128-bit UTC value - an ASCII string of 32 hex characters.
Arguments:
timadr
64-bit system time - a Python 'long integer'.
See 'Programming', 'special OpenVMS datatypes' for details.
utcadr
128-bit UTC value - an ASCII string of 32 hex characters.
cvtflg
conversion flag indicating the direction of the conversion.
Examples:
>>> import vms_sys

>>> utc_tim = vms_sys.getutc ()
>>> print vms_sys.ascutc (utc_tim)
12-AUG-1998 12:21:50.37
>>> utc_tim
'103CFFFFFFFFFFFF01D231D6A4BBD020'
>>>
>>> bin_tim = vms_sys.timcon (utc_tim,0)
>>> print vms_sys.asctim (bin_tim)
12-AUG-1998 12:21:50.37
>>> bin_tim
44096413103700000L

>>> bin_tim = vms_sys.gettim ()
>>> print vms_sys.asctim (bin_tim)
12-AUG-1998 12:22:38.89
>>> bin_tim
44096413588900000L
>>>
>>> utc_tim = vms_sys.timcon (bin_tim,1)
>>> print vms_sys.ascutc (utc_tim)
12-AUG-1998 12:22:38.89
>>> utc_tim
'103CFFFFFFFFFFFF01D231D6C1A760A0'

>>> bin_tim = vms_sys.gettim ()
>>> print vms_sys.asctim (bin_tim)
12-AUG-1998 12:23:23.05
>>> bin_tim
44096414030500000L
>>> utc_tim = vms_sys.timcon (bin_tim,99)
>>> print vms_sys.ascutc (utc_tim)
12-AUG-1998 12:23:23.05
>>> utc_tim
'103CFFFFFFFFFFFF01D231D6DBF9A8A0'

>>> bin_tim = vms_sys.timcon (None,0)
>>> print vms_sys.asctim (bin_tim)
12-AUG-1998 12:23:59.63

>>> bin_tim = vms_sys.timcon ("",0)
Traceback (innermost last):
  File "", line 1, in ?
ValueError: argument 1: must be 32 hex characters

>>> utc_tim = vms_sys.timcon (None,1)
>>> print vms_sys.ascutc (utc_tim)
12-AUG-1998 12:24:49.06
>>>
>>> utc_tim = vms_sys.timcon ("",1)
Traceback (innermost last):
  File "", line 1, in ?
ValueError: argument 1: must be long int

>>> # bad chr -v
>>> utc_tim = 'X103CFFFFFFFFFFFF01D1757F00EEC740'
>>> bin_tim = vms_sys.timcon (utc_tim,0)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 1: must be 32 hex characters
>>>

WAKE - Wake Process from Hibernation


Activates a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service.

Format:

    targpid = vms_sys.wake ([pidadr] [,prcnam])
Returns:
targpid
Process identification of process which has been waked. The targed PID (targpid) is always returned - it is as if you have specified a '0' value for the 'pidadr' argument. If an error happens, then vms_sys.wake() raises a Python exception.
Arguments:
pidadr
Process identification of process to be activated.
prcnam
Process name of process to be activated.
Examples:
>>> import vms_sys

>>> print vms_sys.wake ()
96			<-- PID of current process

>>> wake_pid = 532
>>> print vms_sys.wake (wake_pid)
532			<-- PID of target process
>>> print vms_sys.wake (wake_pid,None)
532
>>> vms_sys.wake (None,'TARG_PRC')
532
>>> vms_sys.wake (0,'TARG_PRC')
532

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

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

>>> vms_sys.wake (1,2)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: expected None or string, int found

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

(go to: table of contents, index)

12-AUG-1998 ZE.