vmsobj_rab object

(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index, list of VMS objects, prev: vmsobj_nam, next: vmsobj_xaball)

The vmsobj_rab object provides high-level access to an OpenVMS RAB (Record 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_RAB.C) nor will it explain the use of each field in a RAB.

The 'vms_rabdef' module contains bitmasks and constants that apply to an OpenVMS RAB.

WARNING!

Not all details of handling the I/O buffers have been worked out, yet. It is presently possible to crash Python with an OpenVMS access violation while using some interface routines.

--------


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 RAB$L_CTX field of the OpenVMS RAB contains the address of the 'vmsobj_rab' object. This cannot be overwritten. The 'vmsobj_rab' object provides a "CTX" attribute which allows the programme 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.

>>> rab = pyvms.vmsobj_rab ()
>>> type (rab)
<type 'vmsobj_rab'>
>>>

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

>>> str = "CONTEXT-1"
>>> rab.CTX = str
>>> ctx_o = rab.CTX
>>>
>>> print ctx_o
CONTEXT-1
>>> id (str)
2192144
>>> id (ctx_o)
2192144
>>>

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

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


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

FAB
Read/write access for a 'vmsobj_fab' object. The readonly attribute "L_FAB" returns the memory address of the OpenVMS FAB.
>>> rab = pyvms.vmsobj_rab ()
>>> type (rab)
<type 'vmsobj_rab'>
>>>
>>> fab = pyvms.vmsobj_fab ()
>>> type (fab)
<type 'vmsobj_fab'>
>>> rab.FAB = fab
>>> f2 = rab.FAB
>>> fab
<vmsobj_fab, FAB at 0x001ad9f8>
>>> f2
<vmsobj_fab, FAB at 0x001ad9f8>
>>>
>>> rab.L_FAB
1759736
>>> hex(rab.L_FAB)
'0x1ad9f8'
>>>
>>>
>>> # remove FAB from RAB
>>> rab.FAB = None
>>> print rab.FAB
None
>>> print rab.L_FAB
0
>>>


>>> rab.L_FAB = 2
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_rab attribute
>>>
>>> rab.FAB = 'X'
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: FAB attribute - must be vmsobj_fab object or None
>>>
>>> # remove FAB from RAB
>>> rab.FAB = None
>>> rab.L_FAB
0
>>>

KBF
key buffer
It accepts and returns a string object (or None) and will store the address and the string length directly in the OpenVMS RAB. The readonly attributes "L_KBF" and "B_KSZ" return the memory address and length of the real buffer.

Note that the key buffer (KBF) and the prompt buffer (PBF) share the same RAB addresses.

>>> rab.KBF = 'key'
>>> rab.KBF
'key'
>>> rab.L_KBF
1988708
>>> rab.B_KSZ
3
>>> rab.PBF
'key'
>>> rab.PBF = None
>>> print rab.KBF
None
>>> rab.L_KBF
0
>>> rab.B_KSZ
0
>>>
>>> rab.B_KSZ = 1
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: read-only vmsobj_rab attribute
>>>

PBF
prompt buffer
It accepts and returns a string object (or None) and will store the address and the string length directly in the OpenVMS RAB. The readonly attributes "L_PBF" and "B_PSZ" return the memory address and length of the real buffer.

Note that the prompt buffer (PBF) and the key buffer (KBF) share the same RAB addresses.

See the examples of the "KBF" attribute.

RBF
record buffer
RMS functions can write to the RBF - this prohibits use of a string object, because Python strings are immutable objects!

@@
 6.16  RAB$L_RBF Field

  When a program invokes a service that writes records to
  a file, the output record buffer address (RBF) field contains
  the symbolic address of the buffer that holds the record to
  be written. The record size field (RAB$W_RSZ) specifies the
  size of the record buffer.

  When you invoke the Get or Read service, RMS sets this field
  to the address of the record just read from the file; you do not
  need to initialize this field. The record's address can be based
  on whether the program specifies locate mode (RAB$V_
  LOC). For locate mode, the address can be within an RMS
  buffer; otherwise, the address is in the user buffer (RAB$L_
  UBF) provided by the program.

 6.24  RAB$L_UBF Field

  The user record buffer address (UBF) field indicates the
  location of a record or block buffer.

                                  Note

      When you invoke the Get service, RMS takes control
      of the record buffer and can modify it. RMS returns
      the record size and only guarantees the contents from
      where it accessed the record to the completion of the
      record.


  This field contains the symbolic address of a work area
  (buffer) within your program. The size of this buffer must be
  defined in the RAB$W_USZ (user record area size) field.

  When you invoke a Get service, this field must contain the
  buffer address, regardless of the record transfer mode (locate
  or move). This option also applies when you invoke the Read
  service for block I/O. However, a Put or Write service never
  needs a user buffer.

The buffer space is hidden behind a 'vmsobj__membuf' object. There are several ways to 'attach' the vmsobj__membuf object to the "RBF" attribute:

  • Create the 'vmsobj__membuf' object via a function in the 'pyvms' module and assign it to "RBF":
    >>> # one way - specify its length
    >>> membuf = pyvms.vmsobj__membuf (5)
    >>> rab.RBF = membuf
    >>> membuf
    <vmsobj__membuf, buffer at 0x002165b8>
    >>> rab.RBF
    <vmsobj__membuf, buffer at 0x002165b8>
    >>>
    
  • Assign a Python string to the "RBF" attribute. The interface routine will automatically create a 'vmsobj__membuf' object and copy the data from the string into the buffer:
    >>> rab.RBF = 'data'
    >>> rab.RBF
    <vmsobj__membuf, buffer at 0x002145f8>
    >>> membuf = rab.RBF
    >>> membuf
    <vmsobj__membuf, buffer at 0x002145f8>
    >>> membuf.buffer
    'data'
    >>>

Finally, the 'None' object can be assigned to the "RBF" attribute. This will 'disconnect' the vmsobj__membuf object from the RAB. If there are no more references to the object, the buffer and its describing object will automatically be deallocated.

The readonly attributes "L_RBF" and "W_RSZ" return the memory address and length from the OpenVMS RAB.

W_RFA
Is represented as a 3-item tuple of 16-bit integers.

UBF
user buffer

@@
The buffer space is hidden behind a 'vmsobj__membuf' object.

"..."

The readonly attributes "L_UBF" and "W_USZ" return the memory address and length from the OpenVMS RAB.

XAB
There is currently no appropriate XAB object for this attribute, so this attribute is non-functional. RAB$L_XAB only accepts a XABTRM and a XABRU (on OpenVMS VAX V6.1 and perhaps later versions of OpenVMS Alpha).

The readonly attribute "L_XAB" returns the memory address of the OpenVMS XAB.


Creation:

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

Examples:

>>> import pyvms

>>> # create a vmsobj_rab object
>>>
>>> rab = pyvms.vmsobj_rab ()
>>> type (rab)
<type 'vmsobj_rab'>
>>> rab
<vmsobj_rab, RAB at 0x001dcc08>
>>>


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

11-FEB-1999 ZE.