vmsobj_xabitm object

(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index, list of VMS objects, prev: vmsobj_xabfhc, next: vmsobj_xabkey)

The vmsobj_xabitm object provides high-level access to an OpenVMS XABITM (ITeM list XAB (eXtended Attribute Block)) data structure. You DO need access to the 'OpenVMS Record Management Services Reference Manual'! The PYVMS documentation will neither list all possible attributes (although you can find them by looking into the file VMSOBJ_XABITM.C) nor will it explain the use of each field in a XABITM.

The 'vms_xabitmdef' module contains item codes, constants and bitmasks that apply to an OpenVMS XABITM.


Attributes:

Most BWLQ,M attributes can be directly read and written as shown in the introduction. Exceptions are noted below:

ITEMLIST
Read/write access for an OpenVMS item list.

When an item list (see example below) is assigned to the "ITEMLIST", an in-memory OpenVMS itemlist is build and its address is stored in "L_ITEMLIST", which can only be read(!) from the Python interface.

If an invalid item list is passed and the interface detects an errors, then a Python exception is raised and an existing old item list is left intact.

If 'None' is assigned, then the in-memory OpenVMS itemlist is freed from memory and a 0 value is stored in "L_ITEMLIST".

It is possible to 'query' the item list, even if no RMS call has been invoked. The interface routine will just return the output items with their current data in a dictionary - see example below.

The following items (as defined in OpenVMS VAX V6.1) are not available:

  • XAB$_STORED_SEMANTICS
  • XAB$_ACCESS_SEMANTICS
  • XAB$_RUJVOLNAM
  • XAB$_TID
>>> xabitm = pyvms.vmsobj_xabitm ()
>>>
>>> item_list = \
...   (
...    ('XAB$_NET_BLOCK_COUNT',4), # in + output
...    ('XAB$_NET_BUFFER_SIZE')    # output
...   )
>>>
>>> xabitm.ITEMLIST = item_list
>>>
>>> dict = xabitm.ITEMLIST
>>> for key in dict.keys():
...   print key, dict.get(key)
...
XAB$_NET_BLOCK_COUNT 4
XAB$_NET_BUFFER_SIZE 0    <-- default value for output item
>>>
>>> print hex(xabitm.L_ITEMLIST)
0x2227b0
>>>

>>>
>>> item_list = \
...   (
...    ('XAB$_NET_BLOCK_COUNT','BAD'),
...    ('XAB$_NET_BUFFER_SIZE',)
...   )
>>>
>>> xabitm.ITEMLIST = item_list
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: vms__cvt_py2bin(): data of item must be integer
>>>
>>> print hex(xabitm.L_ITEMLIST)
0x2227b0
>>> # -> same item-list


>>> xabitm.ITEMLIST = None
>>> print hex(xabitm.L_ITEMLIST)
0x0
>>> # -> item list removed from XABITM


>>>
>>> xabitm.ITEMLIST = 0
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: itemlist must be a tuple of strings, \
 tuples (string,data) or None
>>>
>>> xabitm.L_ITEMLIST = 2
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_xabitm attribute
>>>

NXT
Read/write access for a(nother) vmsobj_xabXXX object. The readonly attribute "L_NXT" returns the memory address of the OpenVMS XAB that was connected to the XABITM. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs.
>>> xabitm = pyvms.vmsobj_xabitm ()
>>> type (xabitm)
<type 'vmsobj_xabitm'>
>>>
>>> print xabitm.NXT
None
>>> print xabitm.L_NXT
0
>>>
>>> # this example uses a XABALL
>>> xaball = pyvms.vmsobj_xaball ()
>>> type (xaball)
<type 'vmsobj_xaball'>
>>>
>>>
>>> xabitm.NXT = xaball
>>> xaball
<vmsobj_xaball, XABALL at 0x002210c8>
>>> xabitm.NXT
<vmsobj_xaball, XABALL at 0x002210c8>
>>> hex (xabitm.L_NXT)
'0x2210c8'
>>>
>>>
>>> xabitm.NXT = None
>>> xabitm.L_NXT
0
>>>
>>> xabitm.NXT = 0
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: must be a XABxxx object or None
>>>
>>> xabitm.L_NXT = 2
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_xabitm attribute
>>>


Creation:

For now the 'pyvms' module contains a function to explicitly create a vmsobj_xabitm object within Python.

Examples:

>>> import pyvms

>>> # create a vmsobj_xabitm object
>>>
>>> xabitm = pyvms.vmsobj_xabitm ()
>>> type (xabitm)
<type 'vmsobj_xabitm'>
>>> xabitm
<vmsobj_xabitm, XABITM at 0x002213f8>
>>>


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

Use:
$ create /directory [.DIRTST.YES]
$ copy _NLA0:       [.DIRTST]NO.DIR;1

$ python
>>> import pyvms
>>> import vms_lib, vms_sys
>>> import vms_xabitmdef
>>>
>>> def is_dir (filespec):
...   #
...   fab = pyvms.vmsobj_fab ()
...   fab.FNA = filespec
...   #
...   xabitm = pyvms.vmsobj_xabitm ()
...   #
...   # Note trailing comma, because this is a tuple of tuples !
...   item_list = ('XAB$_UCHAR_DIRECTORY',0),
...   xabitm.ITEMLIST = item_list
...   #
...   xabitm.B_MODE = vms_xabitmdef.XAB_K_SENSEMODE
...   #
...   fab.XAB = xabitm
...   #
...   status = vms_sys.open (fab)
...   # print status
...   # print vms_sys.getmsg (status)
...   #
...   # Get sensed information from itemlist.
...   dict = xabitm.ITEMLIST
...   #
...   status = vms_sys.close (fab)
...   # print status
...   # print vms_sys.getmsg (status)
...   #
...   return dict.get ('XAB$_UCHAR_DIRECTORY')
...
>>>

>>> context = 0
>>> status  = 1
>>> while (status & 1):
...   status, status_value, context, resultant_filespec = \
...     vms_lib.find_file ('[.DIRTST]*.DIR;*', context, \
...     None, None, 0) # 0 = allow wildcards
...   if (status & 1):
...     print resultant_filespec
...     print '  is',
...     if (not is_dir (resultant_filespec)):
...       print 'not',
...     print 'a directory'
...   else:
...     print vms_sys.getmsg (status)
...     break  # reached end
...
DKA100:[PYTHON.PYTHON-1_5_1.VMS.DIRTST]NO.DIR;1
  is not a directory
DKA100:[PYTHON.PYTHON-1_5_1.VMS.DIRTST]YES.DIR;1
  is a directory
('%RMS-E-NMF, no more files found', (0, 0, 0, 0))
>>>
... @@
(go to: table of contents, index, list of VMS objects, prev: vmsobj_xabfhc, next: vmsobj_xabkey)

26-MAR-1999 ZE.