(go to: table of contents, index, list of VMS objects, prev: vmsobj_nam, next: vmsobj_xaball)
The 'vms_rabdef' module contains bitmasks and
constants that apply to an OpenVMS RAB.
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.
Most BWL,M attributes can be directly read and written as shown in the
introduction. Exceptions are noted below:
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.
Note that the key buffer (KBF) and the prompt buffer
(PBF) share the same RAB addresses.
Note that the prompt buffer (PBF) and the key buffer (KBF) share the
same RAB addresses.
See the examples of the "KBF"
attribute.
The buffer space is hidden behind a
'vmsobj__membuf' object.
There are several ways to 'attach' the vmsobj__membuf object to the "RBF"
attribute:
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.
@@
"..."
The readonly attributes "L_UBF" and "W_USZ"
return the memory address and length from the OpenVMS RAB.
The readonly attribute "L_XAB" returns the memory address
of the OpenVMS XAB.
For now the 'pyvms' module contains a function to
explicitly create a 'vmsobj_rab' object within Python.
Examples:
Attributes:
>>> 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
>>>
>>> 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
>>>
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.
>>> 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
>>>
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.
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.
>>> # 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>
>>>
>>> rab.RBF = 'data'
>>> rab.RBF
<vmsobj__membuf, buffer at 0x002145f8>
>>> membuf = rab.RBF
>>> membuf
<vmsobj__membuf, buffer at 0x002145f8>
>>> membuf.buffer
'data'
>>>
The buffer space is hidden behind a
'vmsobj__membuf' object.
Creation:
>>> 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
>>>
...
@@