vmsobj_fab object

(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index, list of VMS objects, prev: (introduction), next: vmsobj_iosb)

The vmsobj_fab object provides high-level access to an OpenVMS FAB (File Access 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_FAB.C) nor will it explain the use of each field in a FAB.

The 'vms_fabdef' module contains bitmasks and constants that apply to an OpenVMS FAB.


Attributes:

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

CTX
The user context (CTX) field can be used to pass information to a completion routine. This field is never used by RMS.

Internally, the FAB$L_CTX field of the OpenVMS FAB contains the address of the vmsobj_fab object. It cannot be overwritten. The vmsobj_fab object provides a "CTX" attribute which allows the programmer to associate a Python object with it.

If no object was ever assigned to the "CTX" attribute, then a read access will return the 'None' object.

You can assign the 'None' object to "CTX", but this will not put a 0 value into "L_CTX" unlike some other attributes - see the examples below.

>>> fab = pyvms.vmsobj_fab ()
>>> type (fab)
<type 'vmsobj_fab'>
>>>

>>> print fab.CTX
None
>>>
>>> print fab.L_CTX  # the in-memory address of 'fab'
2190784
>>> id (fab)
2190784
>>>

>>> str = "CONTEXT-1"
>>> fab.CTX = str
>>> ctx_o = fab.CTX
>>>
>>> print ctx_o
CONTEXT-1
>>> id (str)
2192128
>>> id (ctx_o)
2192128
>>>

>>> fab.CTX = None
>>> print fab.CTX
None
>>> print fab.L_CTX  # as said, no change!
2190784
>>>

>>> fab.CTX = 2      # other type are possible
>>> ctx_o = fab.CTX
>>> print type(ctx_o), ctx_o
<type 'int'> 2
>>>


>>> fab.L_CTX = 1
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_fab attribute
>>>

DNA
Read/write access for the 'default file specification string'. Input is a Python string object (limited to a maximum of 255 characters) or the 'None' object, returns the same string object (or None). The readonly attribute "L_DNA" returns the memory address of the string. The readonly attribute "B_DNS" returns the size of the string.
>>> fab = pyvms.vmsobj_fab ()
>>> type (fab)
<type 'vmsobj_fab'>
>>>
>>> t_dna = 'A.DAT'
>>> fab.DNA = t_dna
>>> str = fab.DNA
>>> type (t_dna), id (t_dna)
(<type 'string'>, 2183816)
>>> type (str), id (str)
(<type 'string'>, 2183816)
>>>
>>> fab.L_DNA
2183836
>>> fab.B_DNS
5
>>>
>>> fab.DNA = None
>>> fab.L_DNA
0
>>> fab.B_DNS
0
>>>

>>> long_str = 's' * 256
>>> fab.DNA = long_str
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: string length limited to 255 characters
>>>
>>> fab.DNA = 0
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: attribute must be string or None
>>>
>>> fab.L_DNA = 2
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_fab attribute
>>>

FNA
Read/write access for the 'file specification string'. Input is a Python string object (limited to a maximum of 255 characters) or the 'None' object, returns the same string object (or None). The readonly attribute "L_FNA" returns the memory address of the string. The readonly attribute "B_FNS" returns the size of the string.

See the examples of the "DNA" attribute.

NAM
Read/write access for a vmsobj_nam object. The readonly attribute "L_NAM" returns the memory address of the OpenVMS NAM.
>>> fab = pyvms.vmsobj_fab ()
>>> type (fab)
<type 'vmsobj_fab'>
>>>
>>> print fab.NAM
None
>>> print fab.L_NAM
0
>>>
>>> nam = pyvms.vmsobj_nam ()
>>> type (nam)
<type 'vmsobj_nam'>
>>>
>>>
>>> fab.NAM = nam
>>> fab.NAM
<vmsobj_nam, NAM at 0x001ab0b0>
>>> hex (fab.L_NAM)
'0x1ab0b0'
>>>
>>>
>>> fab.NAM = 0
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: must be a vmsobj_nam object or None
>>>
>>> fab.L_NAM = 2
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_fab attribute
>>>

XAB
Read/write access for a vmsobj_xabXXX object. The readonly attribute "L_XAB" returns the memory address of the OpenVMS XAB that was connected to the FAB. Remember that each XAB contains a "NXT" / "L_NXT" attribute to build a chain of multiple XABs.
>>> fab = pyvms.vmsobj_fab ()
>>> type (fab)
<type 'vmsobj_fab'>
>>>
>>> print fab.XAB
None
>>> print fab.L_XAB
0
>>>
>>> # this example uses a XABALL
>>> xaball = pyvms.vmsobj_xaball ()
>>> type (xaball)
<type 'vmsobj_xaball'>
>>>
>>>
>>> fab.XAB = xaball
>>> fab.XAB
<vmsobj_xaball, XABALL at 0x0021a330>
>>> hex (fab.L_XAB)
'0x21a330'
>>>
>>>
>>> # remove XAB from FAB
>>> fab.XAB = None
>>> print fab.XAB
None
>>> print fab.L_XAB
0
>>>


>>> fab.XAB = 0
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: must be a vmsobj_xabXXX object or None
>>>
>>> fab.L_XAB = 2
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_fab attribute
>>>

Creation:

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

To date (10-FEB-1999) the following interface routines also pass a vmsobj_fab to their user-confirm routines:

Examples:

>>> import pyvms

>>> # create a vmsobj_fab object
>>>
>>> fab = pyvms.vmsobj_fab ()
>>> type (fab)
<type 'vmsobj_fab'>
>>> fab
<vmsobj_fab, FAB at 0x001acbf8>
>>>


>>> # invalid attribute access
>>> fab.no_attr = 0
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: non-existing vmsobj_fab attribute
>>> fab.no_attr
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: no_attr
>>>
... @@
(go to: table of contents, index, list of VMS objects, prev: (introduction), next: vmsobj_iosb)

11-FEB-1999 ZE.