VMS-Specific Python Modules

From VSI OpenVMS Wiki
Revision as of 11:17, 30 June 2021 by Marty.stu (talk | contribs) (→‎vms.lib)
Jump to: navigation, search

VMS specific Python modules.

Contents

vms.decc


Wraps the C Run-Time Library for OpenVMS Systems functions.

dlopen_test(name:str)->int

Checks if a shared image can be opened and loaded into memory.

parameters
name:str: path to the shared image
returns
1: if the shared image exists and can be opened by dlopen()
0: otherwise

fix_time(vms_time:int)->int

Converts the VMS time to the Unix time stamp.

parameters
vms_time:int: VMS system time
returns
Time in the Unix format (number of seconds since 01/01/1970)

from_vms(vms_path:str, wild_flag:int)->list

Converts the VMS path to a list of Unix paths.

parameters
vms_path:str: path in the VMS format (supports wildcards)
wild_flag:int: If set to 0, the wildcards found in vms_path are not expanded
returns
List of paths in the Unix notation

getenv(name:str, def_value:str)->str

Gets the specified environment variable value. See getenv() description in the VSI C Run-Time Library Reference Manual for OpenVMS Systems.

parameters
name:str: name of the environment variable
def_value:str: default value
returns
Environment variable value

sleep(seconds:int)->int

Suspends execution of the current process or thread for the specified number of seconds.

parameters
seconds:int: seconds to sleep
returns
The number of seconds left before the sleep timer expires if sleep is interrupted. 0 if the process slept for the specified number of seconds

sysconf(name:int)->int

Provides a method for determining the current value of a configurable system limit or whether optional features are supported.

parameters
name:int: system variable to be queried
returns
Requested value

to_vms(unix_path:str, allow_wild:int, no_directory:int)->list

Converts UNIX style file specifications to OpenVMS file specifications.

parameters
unix_path:str: file name following the Unix file naming conventions
allow_wild:int: If set to 0, the wildcards found in unix_path are not expanded
no_directory:int An integer that has one of the following values:
  • 0 - Directory allowed
  • 1 - Prevent expansion of the string as a directory name
  • 2 - Force expansion of the string as a directory name
returns

List of OpenVMS style pathnames

unixtime(vms_time:int)->int

Converts the OpenVMS system time to the Unix local time.

parameters
vms_time:int OpenVMS system time
returns
Unix time

vmstime(unix_time:int)->int

Converts Unix time to the OpenVMS system time.

parameters
unix_time:int: Unix time
returns

OpenVMS system time

vms.ile3


Provides functions to work with item lists.

new()->object

Creates an empty item list.

parameters
None
returns
New empty item list

delete(il:object)->None

Deletes the item list.

parameters
il:object: item list to be removed
returns
None

size(il:object)->int

Gets the size of the item list.

parameters
il:object: item list
returns
The size of the specified item list

addint(il:object, item:int, item_type:int, item_value:int)->None

Adds a new integer to the item list.

parameters
il:object: item list
item:int: item to add
item_type:int: type of the item. See vms.dscdef
item_value:int: value of the item
returns
None

getint(il:object, index:int)->int

Gets the integer at the specified index in the item list.

parameters
il:object: item list
index:int: index of the item to get
returns
Integer value

gethex(il:object, index:int)->str

Gets the integer at the specified index in the item list and returns it as a hexadecimal string.

parameters
il:object: item list
index:int: index of the item to get
returns
Hexadecimal string

addstr(il:object, item:int, item_value:str, item_length:int)->None

Adds the specified string to the item list. If item_value is not None, item_length is ignored and the length of the buffer will be the same as the length of item_value.

parameters
il:object: item list
item:int: item to add
item_value:str: value to add (or None)
item_length:int: length of the buffer if item_value is None
returns
None

addstrd(il:object, item:int, item_value:str, item_length:int)->None

Adds the specified space-expanded string to the item list. The first byte of the buffer is the length of the string. If item_value is longer than item_length, it will be truncated.

parameters
il:object: item list
item:int: item to add
item_value:str: value to add
item_length:int: length of the buffer (the resulting string length is one byte less)
returns
None

addstrn(il:object, item:int, item_value:str, item_length:int)->None

Adds the specified space-expanded string to the item list. If item_value is longer than item_length, it will be truncated.

parameters
il:object: item list
item:int: item to add
item_value:str: value to add
item_length:int: length of the buffer
returns
None

getstr(il:object, index:int, flag:int)->str

Gets the string at the specified index in the item list.

parameters
il:object: item list
index:int: index of the item to get
flag:int: if set to 1, the first byte of the resulting string is the length of the string
returns
String

addbin(il:object, item:int, item_value:int, item_offset:int, item_len:int)->None

Adds a new binary item to the item list. This item will be interpreted as a string.

parameters
il:object: item list
item:int: item to add
item_value:int: value to store
item_offset:int: starting byte
item_len:int: amount of bytes
returns
None

getbyte(il:object, index:int, item_offset:int)->int

Gets the byte at the specified position in the item list.

parameters
il:object: item list
index:int: index of the item
item_offset:int: starting byte
returns
Integer value of the specified byte

vms.lib


Wraps the OpenVMS RTL Library (LIB$) functions.

create_dir(name:str, uic:int, pe:int, pv:int)->int

Creates a directory.

parameters
name:str: name of the directory to be created (following the OpenVMS naming conventions)
uic:int: unsigned integer value of the owner UIC:
* None: current user
* 0: owner of the parent directory
pe:int: protection-enable. Refer to the VSI OpenVMS RTL Library (LIB$) Manual for more info about LIB$CREATE_DIR.
pv:int: protection-value
returns
vms.ssdef.SS__CREATED: one or more directories created
vms.ssdef.SS__NORMAL: all the specified directories already exist
another error. See in vms.ssdef

date_time()->list

Gets current date and time.

parameters
None
returns
The list:
  • int: status code of the operation
  • str: resulting string

get_ef()->list

Allocates a local event flag.

parameters
None
returns
The list:
* int: status code of the operation
* int: resulting event flag

free_ef(ef:int)->int

Releases the local event flag.

parameters
ef:int: local event flag
returns
Status code of the operation

put_common(common:str)->int

Copies a string into the common area.

parameters
common:str: string to copy
returns
Status code of the operation

get_common()->list

Gets the string from the common area.

parameters
None
returns
The list:
* int: status code of the operation
* str: resulting string

get_hostname(flags:int)->list

Gets the host name of the local system.

parameters
flags:int if set to 1, the host node name is returned in a parseable format
returns
The list:
* int: status code of the operation
* str: resulting host node name

getjpi(item_code:int, pid:int, pname:str)->list

Gets the specified job/process information as a string.

parameters
item_code:int: item identifier code defining the item of the information to be returned. See vms.jpidef
pid:int: process id
pname:str: process name

For valid combination of the values of pid and pname, see the OpenVMS RTL Library (LIB$) Manual for LIB$GETJPI. The resulting pid is not returned.

returns
The list:
* int: status code of the operation
* str: resulting string

getsyi(item_code:int, node_name:str)->list

Gets system-wide information as a string.

parameters
item_code:int: item identifier code defining the item of the information to be returned. See vms.syidef
node_name:str: node name
returns
The list:
* int: status code of the operation
* str: resulting string
* int: resulting cluster system ID

spawn(command:str, input_file:str, output_file:str, flags:int, pname:str)->list

Requests the command language interpreter (CLI) of the calling process to spawn a subprocess for executing CLI commands.

parameters
command:str: command to execute
input_file:str: equivalence name to be associated with the logical name SYS$INPUT
output_file:str: equivalence name to be associated with the logical name SYS$OUTPUT
flags:int: flag bits that designate optional behavior. See vms.clidef
pname:str: name defined for the subprocess
returns
The list:
* int: status code of the operation
* int: process ID of the spawned process

do_command(command:str)->None

Stops program execution and directs the command language interpreter (CLI) to execute a command that is supplied as the argument.

parameters
command:str command to execute
returns
If successful, it does not return control to the calling program.

vms.sys


Wraps the OpenVMS System Services functions.

asctim(vms_time:int, time_only:int)->list

Converts an absolute or delta time from 64-bit system time format to an ASCII string.

parameters
vms_time:int OpenVMS system time. A negative time value represents a delta time.
time_only:int if set to 1, asctim returns the hour only.
returns
The list:
  • int status code of the operation
  • str resulting string

bintim(time_str:str)->list

Converts an ASCII string to an absolute or delta time value in the system 64-bit time format.

parameters
time_str:str in format:
  • Absolute Time: dd-mmm-yyyy hh:mm:ss.cc
  • Delta Time: dddd hh:mm:ss.cc
returns
The list:
  • int status code of the operation
  • int resulting time value

asctoid(name:str)->list

Translates the specified identifier name into its binary identifier value.

parameters
name:str identifier name
returns
The list:
  • int status code of the operation
  • int resulting identifier value
  • int resulting identifier attributes. See vms.kgbdef

idtoasc(id_val:int, context:int)->list

Translates the specified identifier value to the identifier name.

parameters
id_val:int identifier value. See OpenVMS System Services Reference Manual for SYS$IDTOASC
context:int context value used when idtoasc is called repeatedly. Must be initialized with the value 0.
returns
The list:
  • int status code of the operation
  • str resulting identifier name
  • int resulting identifier value
  • int resulting identifier attributes. See vms.kgbdef
  • int resulting context

crembx(tmp:int, maxmsg:int, bufquo:int, promsk:int, acmode:int, mbx_name:string, flags:int)->list

Creates a virtual mailbox device.

parameters
tmp:int the first bit specifies a permanent mailbox
maxmsg:int maximum size of a message (in bytes)
bufquo:int number of bytes of system dynamic memory that can be used to buffer messages sent to the mailbox
promsk:int protection mask to be associated with the created mailbox
acmode:int access mode to be associated with the channel to which the mailbox is assigned
mbx_name:string logical name to be assigned to the mailbox
flags:int options for the assign operation. See vms.cmbdef
returns
The list:
  • int status code of the operation
  • int resulting channel

delmbx(channel:int)->int

Marks a permanent mailbox for deletion.

parameters
channel:int mailbox channel
returns
Status code

assign(devnam:str, acmode:int, mbxnam:str, flags:int)->list

Provides a process with an I/O channel.

parameters
devnam:str name of the device
acmode:int access mode to be associated with the channel
mbxnam:str logical name of the mailbox to be associated with the device
flags:int an optional device-specific argument
returns
The list:
  • int status code of the operation
  • int resulting channel

dassgn(channel:int)->int

Unassigns (releases) an I/O channel.

parameters
channel:int number of the I/O channel to be unassigned
returns
Status code

readvblk(channel:int, max_read:int, block:int, fmod:int)->list

Read from I/O channel.

parameters
channel:int I/O channel
max_read:int amount of bytes to read
block:int starting block
fmod:int function code modifiers
returns
The list:
  • int status code of the operation
  • byte resulting buffer
  • int I/O completion code

writevblk(channel:int, buffer:bytes, block:int, fmod:int)->list

Write to I/O channel.

parameters
channel:int I/O channel
buffer:bytes bytes to write
block:int starting block
fmod:int function code modifiers
returns
The list:
  • int status code of the operation
  • int amount of written bytes
  • int I/O completion code

cancel(channel:int)->int

Cancel I/O operation.

parameters
channel:int I/O channel
returns
Status code

crelnm(attr:int, tabnam:str, lognam:str, acmode:int, il:object)->int

Creates a logical name and specifies its equivalence names.

parameters
attr:int attributes to be associated with the logical name. See vms.lnmdef
tabnam:str name of the table in which to create the logical name
lognam:str logical name to be created
acmode:int access mode to be associated with the logical name. See vms.psldef
il:object item list, created via vms.ile3.new()

See OpenVMS System Services Reference Manual for SYS$CRELNM.

returns
Status code

trnlnm(attr:int, tabnam:str, lognam:str, acmode:int, il:object)->int

Returns information about the specified logical name.

parameters
attr:int attributes controlling the search for the logical name. See vms.lnmdef
tabnam:str name of the logical name table or the name of a searchlist logical name
lognam:str logical name for which information is to be returned
acmode:int access mode to be used in the translation. See vms.psldef
il:object item list, created via vms.ile3.new()

See OpenVMS System Services Reference Manual for SYS$TRNLNM.

returns
Status code

dellnm(tabnam:str, lognam:str, acmode:int)->int

Deletes all logical names with the specified name.

parameters
tabnam:str name of the logical name table or the name of a searchlist logical name
lognam:str logical name to be deleted
acmode:int access mode to be used in the delete operation. See vms.psldef
returns
Status code

device_scan(search_devnam:str, item_list:object, context:int)->list

Returns the names of all devices that match a specified set of search criteria.

parameters
search_devnam:str name of the device for which device_scan to search
item_list:object item list specifying search criteria
context:int value used to indicate the current position of the search. On the initial call it must contain 0.

See OpenVMS System Services Reference Manual for SYS$DEVICE_SCAN

returns
The list:
  • int status code of the operation
  • str found device name
  • int context

uicstr(uic:int, flags:int)->list

Converts UIC to a string.

parameters
uic:int UIC
flags:int
  • 0 - use "!%I" SYS$FAO format
  • 1 - use "!%U" SYS$FAO format
returns
The list:
  • int status code of the operation
  • str UIC string

getdvi(dev_nam:str, item_list:object)->int

Returns information related to the primary and secondary device characteristics of an I/O device.

parameters
dev_nam:str the name of the device for which information is to be returned
item_list:object item list specifying which information about the device is to be returned.

See OpenVMS System Services Reference Manual for SYS$GETDVI

returns
Status code

getjpi(pid:int, pnam:str, item_list:object)->list

Returns information about one or more processes of the system or across the OpenVMS Cluster system.

parameters
pid:int process identification
pnam:str name of the process
item_list:object item list specifying which information about the process or processes is to be returned

See OpenVMS System Services Reference Manual for SYS$GETJPI

returns
The list:
  • int status code of the operation
  • int process id

getlki(lki:int, item_list:object)->list

Returns information about the lock database on a system.

parameters
lki:int identification of the lock (lock ID) information about which needs to be returned
item_list:object item list specifying the lock information to be returned

See OpenVMS System Services Reference Manual for SYS$GETLKI

returns
The list:
  • int status code of the operation
  • int lock identification

getmsg(msgid:int, flags:int)->list

Returns message text associated with a given message identification code.

parameters
msgid:int identification of the message to be retrieved
flags:int message components to be returned

See OpenVMS System Services Reference Manual for SYS$GETMSG

returns
The list:
  • int status code of the operation
  • str message string
  • int optional information

getqui(func:int, context:int, item_list:object)->list

Returns information about queues and the jobs initiated from these queues.

parameters
func:int function code specifying the function that getqui is to perform. See vms.quidef
context:int context stream for this call
item_list:object item list supplying the information to be used by the function

See OpenVMS System Services Reference Manual for SYS$GETQUI

returns
The list:
  • int status code of the operation
  • int context

getrmi(item_list:object)->int

Returns system performance information about the local system.

parameters
item_list:object item list specifying which information about the local node is to be returned

See OpenVMS System Services Reference Manual for SYS$GETRMI

returns
Status code

getsyi(csid:int, node_name:str, item_list:object)->list

Returns information about the local system or about other systems in an OpenVMS Cluster system.

parameters
csid:int OpenVMS Cluster system identification
node_name:str name of the node about which information is to be returned
item_list:object item list specifying which information about the node or nodes to return

See OpenVMS System Services Reference Manual for SYS$GETSYI

returns
The list:
  • int status code of the operation
  • int csid

gettim()->list

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

parameters
None
returns
The list:
  • int status code of the operation
  • int current system time

getuai(user_name:str, item_list:object)->int

Returns authorization information about the specified user.

parameters
user_name:str name of the user to get authorization information for
item_list:object item list specifying which information to return

See OpenVMS System Services Reference Manual for SYS$GETUAI

returns
Status code

hiber()->int

Allows a process to make itself inactive but to remain known to the system so that it can be interrupted.

parameters
None
returns
Status code

schdwk(pid:int, pname:str, time:int)->list

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

parameters
pid:int process identification (PID) of the process to be awakened
pname:str name of the process to be awakened
time:int time at which the process to be awakened

See OpenVMS System Services Reference Manual for SYS$SCHDWK

returns
The list:
  • int status code of the operation
  • int pid

add_holder(id:int, holder:int, attrib:int)->int

Adds a specified holder record to a target identifier.

parameters
id:int target identifier granted to the specified holder
holder:int holder identifier that is granted access to the target identifier
attrib:int attributes to be placed in the holder record

See OpenVMS System Services Reference Manual for SYS$ADD_HOLDER

returns
Status code

add_ident(name:str, id:int, attrib:int)->list

Adds the specified identifier to the rights database.

parameters
name:str identifier name to be added to the rights database
id:int identifier to be created
attrib:int attributes placed in the identifier’s record

See OpenVMS System Services Reference Manual for SYS$ADD_IDENT

returns
The list:
  • int status code of the operation
  • int resid, identifier value assigned by the system

find_held(holder:int, context:int)->list

Returns the identifiers held by the specified holder.

parameters
holder:int holder whose identifiers to be found
context:int context value used when find_held is called repeatedly

See OpenVMS System Services Reference Manual for SYS$FIND_HELD

returns
The list:
  • int status code of the operation
  • int id, identifier value that was found
  • int attrib attributes associated with the holder returned in id
  • int context

finish_rdb(context:int)->int

Deallocates the record stream and clears the context value.

parameters
context:int context value to be cleared
returns
Status code

forcex(pid:int, pname:str, code:int)->int

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

parameters
pid:int process identification (PID) of the process to force exit
pname:str process name of the process that is to force exit
code:int completion code value to be used as the exit parameter
returns
Status code

rem_holder(id:int, holder:int)->int

Deletes the specified holder record from the target identifier’s list of holders.

parameters
id:int binary value of the target identifier
holder:int identifier of the holder being deleted
returns
Status code

rem_ident(id:int)->int

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

parameters
id:int binary value of the identifier deleted from rights database
returns
Status code

setuai(user_name:str, item_list:object)->int

Modifies the user authorization file (UAF) record for the specified user.

parameters
user_name:str name of the user whose UAF record is modified
item_list:object item list specifying which information from the specified UAF record is to be modified

See OpenVMS System Services Reference Manual for SYS$SETUAI

returns
Status code

show_intrusion(user_criteria:str, flags:int, context:int)->list

Searches for and returns information about records in the intrusion database matching the caller specifications.

parameters
user_criteria:str description of an intruder or suspect
flags:int type of records in the intrusion database about which information is to be returned. NOTE: do not use vms.ciadef.CIA_M_ITEMLIST, because user_criteria is a string
context:int context information to keep between related calls

See OpenVMS System Services Reference Manual for SYS$SETUAI

returns
The list:
  • int status code of the operation
  • str intruder, user specification of the matched intruder or suspect record in the intrusion database
  • int expires, quadword time format indicating the time when the record will expire
  • int type, the types of the matched record and the status of the suspect
  • int count, number of login failures or break-in attempts

rdb


Wraps the Oracle RDB functions.

Attach(dbname:string)->int

Attaches to the specified database. The string may specify the full path to the RDB database in OpenVMS format or (more commonly) a logical name pointing to the database.

parameters
dbname:string path or logical name
returns
Status code:
  • 0 success
  • -1 failed

CloseCursor(cursor:object)->int

Closes the specified cursor.

parameters
cursor:object cursor
returns
Status code:
  • 0 success
  • -1 failed

Commit()->int

Commits the current database transaction.

parameters
None
returns
Status code:
  • 0 success
  • -1 failed

Data(cursor:object, idx:int)->str

Given a cursor handle and column index (integer), returns the data value for the specified column for the last fetch operation.

parameters
cursor:object cursor
idx:int index
returns
Resulting string

DeclareCursor(name:str, statement:str)->object

Declares a cursor. Inputs are the name for the cursor and the SQL statement. On success the function returns a cursor handle that can be used with OpenCursor(), FetchCursor(), and CloseCursor().

parameters
name:str name for the cursor
statement:str SQL statement
returns
Resulting cursor

Detach()->int

Disconnects from the database.

parameters

None

returns
Status code:
  • 0 success
  • -1 failed

Error()->str

Returns a description of the last error.

parameters
None
returns
Resulting error string

Exec(sh:object)->int

Executes a previously prepared SQL statement.

parameters
sh:object prepared SQL statement
returns
Status code:
  • 0 success
  • -1 failed

ExecI(st:str)->int

Executes the supplied SQL statement immediately.

   Note: the last letter is a capital 'i'
parameters
st:str SQL statement
returns
Status code:
  • 0 success
  • -1 failed

Fetch(cursor:object)->int

Fetches a row of data for the specified cursor but does not explicitly return the fetched data. The Data() method can then be used to retrieve individual data values for each column (Ncol() can be used to determine the number of columns).

parameters
cursor:object cursor
returns
Status code:
  • 1 success
  • 0 success, end of stream
  • -1 failed

FetchRow(cursor:object)->list

Fetches a row of data using the specified cursor handle. The fetched data is returned as an list of strings.

parameters
cursor:object cursor
returns
The list of strings

Free(cursor:object)->int

Frees resources associated with the supplied cursor handle for a cursor previously declared via DeclareCursor().

parameters
cursor:object cursor
returns
Status code:
  • 0 success

Ncol(cursor:object)->int

Returns the number of columns (values) that would be returned by a fetch for the specified cursor.

parameters
cursor:object cursor
returns
Number of columns

OpenCursor(cursor:object)->int

Opens a cursor using the supplied (previously declared) cursor handle.

parameters
cursor:object cursor
returns
Status code:
  • 0 success
  • -1 failed

Prepare(st:string)->object

Prepares an SQL statement and returns a handle for the prepared statement that can be used in subsequent calls to Exec().

parameters
st:string SQL statement
returns
Resulting prepared statement

Rollback()->int

Rolls back the current database transaction.

parameters
None
returns
Status code:
  • 0 success
  • -1 failed

SetReadonly()->int

Starts a read-only transaction.

parameters
None
returns
Status code:
  • 0 success
  • -1 failed

Sqlcode()->int

Returns the SQLCODE for the last database operation.

parameters
None
returns
Resulting SQL code

See also

Retrieved from "https://wiki.vmssoftware.com/index.php?title=VMS-Specific_Python_Modules&oldid=2332"